What problem does it solve?
APIs, module boundaries, and public interfaces often break consumers when terminology, error formats, or observable behaviors change unexpectedly; this guidance helps teams design interfaces that minimize accidental breakage, ambiguity, and implementation leakage. The Skill emphasizes intentional surface design, deprecation planning, and validation at boundaries so interfaces remain predictable and maintainable as systems evolve.
Core Features & Use Cases
- Contract-first design: Define typed input and output contracts before implementation to make types the source of truth.
- Consistent error semantics: Use a single, structured error shape and stable status code mapping across endpoints.
- Boundary validation: Validate all external inputs and third-party responses at the system edge while trusting internal contracts.
- Backward-compatible evolution: Prefer additive changes, optional fields, and principled deprecation with migration paths.
- Predictable naming and patterns: RESTful resource conventions, pagination, filtering, and partial updates (PATCH) for list and CRUD operations.
- Type-system patterns: Discriminated unions, input/output separation, and branded ID types to prevent misuse and improve developer ergonomics.
Quick Start
Audit each endpoint by listing its contract (inputs and outputs), standardizing the error format, and ensuring pagination or a migration plan is defined for any breaking change.
