coding-api-design

Design an API or interface contract

Every observable field, status code, ordering guarantee, and error shape becomes part of the contract the moment a consumer depends on it (Hyrum's Law): design as if it will be relied upon exactly as built, not only as documented. Do not load bundled references when this skill activates.

Establish the boundary and its consumers

1. Identify the producer, every current consumer, and which ones deploy independently of it. A consumer that cannot upgrade atomically with the producer makes this a compatibility change, not a free-form redesign.
2. Separate what is already observable (and therefore load-bearing) from what is still a private implementation detail with room to change.
3. Define the three outcomes for every operation — success, failure, and unknown (timeout, partial write, disconnected client) — and what a caller must do for the unknown case specifically, not only the first two.
4. Read references/api-contract-checklist.md when choosing an HTTP status/error shape, a discriminated-union variant, an idempotency-key design, or a versioning strategy.

When the existing boundary is known only by route, event name, field, or error text, call code_context with action="search" once to find its declared symbol. Skip search when the exact type or handler is already known.

For an exact endpoint, schema, or type symbol, use code_context to find direct callers/references — every consumer that already depends on its current shape — before changing it. Start at depth 1; treat an unresolved cross-repository reference as an unknown consumer, not as evidence none exists. Once the boundary and its consumers are located, make the graph the next structural observation instead of continuing broad discovery.

Keep refresh=true for the first indexed query and after edits. Use refresh=false only for an immediate follow-up that intentionally reuses the same index version.