Design

Design interfaces that are hard to misuse, easy to extend, and stable under change. Applies to API contracts, module boundaries, config schemas, and any surface where components interact.

Principles

Contract first

Define the interface before implementing it. The schema is the contract — implementation follows.

Hyrum's Law

All observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract. Every public behavior becomes a de facto commitment. Be deliberate about what you expose.

Prefer addition over modification

Extend interfaces by adding optional fields rather than changing existing ones. Changing a field's type or removing it breaks consumers silently. Adding is safe; modifying is not.

When different behaviors carry different intent, prefer separate variants or schemas over a single shared shape with conditionally meaningful fields.