api-and-interface-design

API and Interface Design Skill

When to apply

• Designing a new MCP tool, CLI command, or HTTP endpoint
• Defining a public type contract between modules (especially across src/ package boundaries)
• Designing component prop interfaces or hooks
• Establishing a database schema that informs API shape
• Evolving an existing public interface — see deprecation-and-migration for the safe-removal path

Core principles

Hyrum's Law

With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.

Every observable behavior — undocumented quirks, error message text, ordering, timing — becomes a de facto contract. Design implications:

• Be intentional about what you expose. Every public symbol is a commitment.
• Don't leak implementation details. If users can observe it, they will depend on it.
• Plan for deprecation at design time. New surfaces should be removable later — see deprecation-and-migration.
• Tests aren't enough. Even with perfect contract tests, "safe" changes can break consumers depending on undocumented behavior.

One-Version Rule

Avoid forcing consumers to choose between multiple versions of the same dependency or API. Diamond-dependency problems arise when different consumers need different versions of the same thing. Design to extend rather than fork — see CLAUDE.md Anti-Sprawl Policy ("ONE canonical implementation path").

Contract first