| name | devex-sdk-design |
| description | Developer experience (DX) engineering, SDK design patterns, API ergonomics, CLI tooling design, documentation-driven development, and developer onboarding. Use when designing SDKs, improving API ergonomics, building developer tools, or creating developer documentation. |
Developer Experience & SDK Design
SDK Design Principles
API Ergonomics
createUser(name, email, role, true, false, null, 'active');
const user = await sdk.users.create({
name: 'Alice',
email: 'alice@example.com',
role: 'admin',
});
const results = await sdk.query('users')
.where('role', '=', 'admin')
.orderBy('createdAt', 'desc')
.limit(10)
.execute();
Progressive Disclosure
const client = new MySDK('api-key');
const result = await client.doThing();
const client = new MySDK({
apiKey: 'api-key',
baseUrl: 'https://custom.endpoint.com',
timeout: 30000,
retries: { maxAttempts: 3, backoff: 'exponential' },
middleware: [loggingMiddleware, authRefreshMiddleware],
});
Error Design
class SDKError extends Error {
constructor(
message: string,
public readonly code: string,
public readonly statusCode?: number,
public readonly retryable: boolean = false,
public readonly docs?: string,
) {
super(message);
}
}
CLI Design
Command Structure
mycli <command> <subcommand> [flags]
mycli init # Interactive setup
mycli deploy --env production # Explicit flags
mycli logs --follow # Streaming output
mycli config set key value # Noun-verb pattern
CLI Best Practices
- Sensible defaults: Work out of the box,
--flag for customization
- Progressive output: Spinners for long ops,
--verbose for debug, --json for machines
- Confirmation prompts: Destructive actions require
--yes or interactive confirm
- Shell completion: Generate for bash/zsh/fish/PowerShell
- Exit codes: 0 = success, 1 = error, 2 = usage error
Documentation-Driven Development
README Structure (for SDKs)
- One-liner: What it does in one sentence
- Quick start: Copy-paste working example (< 10 lines)
- Installation: Package manager commands
- Usage: Common patterns with code examples
- API reference: Auto-generated from types/docstrings
- Error handling: Common errors and solutions
- Migration guide: Breaking changes between versions
Code Examples
- Every public method needs a usage example
- Examples must compile/run — test them in CI
- Show the happy path first, then edge cases
- Include expected output in comments
Developer Onboarding Metrics
- Time to Hello World: < 5 minutes from docs to working code
- Time to first API call: < 10 minutes including auth setup
- Copy-paste success rate: Quick start examples work on first try
- Error resolution time: Error messages lead directly to fix
Versioning & Breaking Changes
- Semantic versioning strictly followed
- Deprecation warnings 2 minor versions before removal
- Migration codemods for major version upgrades
- Changelog with every release (keep-a-changelog format)