API Design: $ARGUMENTS

Principle

A public contract is the kit's heaviest door: once a consumer you don't control depends on it, every field name is permanent and every quirk is load-bearing (Hyrum's law — with enough consumers, all observable behavior becomes the contract, including your bugs). So the design order is fixed: consumers and compatibility promise first, then the resource model, then the mechanics — and consistency with the house's existing API beats global best practice every time: one project, one dialect.

Phase 0 — Load context

Read .claude/PROJECT.md (Architecture — where API code lives; Domain; Integrations), CONTEXT.md (names come from the ubiquitous language), and — decisive — grep the existing API surface: current endpoints/commands, their casing, envelope shape, error format, auth pattern. Missing/TEMPLATE profile → fall back to the root CLAUDE.md (always in context) when it carries the architecture/integrations (note you're running without a kit profile); STOP for /bootstrap first only if neither has them — the API-surface grep runs regardless. An /analyst spec for the feature is the ideal input; without one, get WHAT/WHY first.

Phase 1 — Consumers and the compatibility promise

• Who calls this — own frontend / other internal services / third parties / public / an LLM agent (an MCP server, a tool API, a CLI a model drives)? Each step outward hardens the door (core.md).
• Can you break them? Sets the promise per edge, not per endpoint: internal-only where both sides ship together, versioned-public (additive-only within a version; breaking = new version via /rollout coexistence) where the counterpart releases on a clock you don't control — an app-store review queue is reason enough. Write each edge's promise into the contract doc, with the condition that would tighten a loose edge again; the dialect stays one.
• The hard consumer case — the ugliest real call pattern (bulk import, polling at scale, retry storms, mobile on flaky network). Designs are judged against it in Phase 5.
• What counts as breaking — safe iff the change requires a subset of what it required, accepts a superset, returns a superset, and enforces a subset of the old constraints. Adding validation to a field you never validated is breaking: the implementation is the spec.

When an agent is on that list, the hard consumer case becomes a caller whose only memory is its context window, and Phase 5 is run against it. The unit of the contract is a completed step of work, not a resource row (schedule_event, not list_users + list_events + create_event); wrapping each existing endpoint one-to-one is the default failure, and the endpoints you deliberately did not expose belong in the doc beside the ones you did. Responses lead with what the caller can act on, technical ids behind an explicit response_format=detailed — a second response mode, never a guessable id scheme, both modes under one promise and both in Phase 4. Name the surface so its boundary reads from outside (acme_invoices_search): your names will sit in a list beside other people's.

Phase 2 — Resource model, in the domain language

Name the nouns from CONTEXT.md/domain vocabulary — the API is the domain made visible, not the database made public:

• Resources, their identifiers (opaque IDs; never enumerable integers on anything tenant-scoped), relationships and nesting depth (flat + link beats deep nesting — nest only when the child cannot be listed, linked to, or acted on without its parent; "unknown" = no). An identifier you only pass through belongs to someone else: keep the type as received, never re-type or format-validate it, and name its one authority in the contract doc.
• Which internal fields are not exposed (default-closed: expose what the consumer needs, not what the model has — every exposed field is forever, per Hyrum). The decomposition freezes too: label each resource "client use case" or "internal structure", and mark the mirrored ones "shape frozen, accepted" — a 1:1 mirror makes your next model refactor their breaking change.
• Actions that aren't CRUD: model state transitions explicitly (/orders/{id}/cancel or a status-transition body — pick the house's existing dialect) instead of overloading generic updates with side effects.

Phase 3 — The contract checklist

One decision per row; "same as existing API" is the default answer, deviations are declared with a reason. Whatever a row decides is enforced on the server: a client-side copy of a rule (a validation, a limit) is a hint that drifts, never the enforcement point.

Phase 4 — Worked examples (the real spec)

For each endpoint: one happy request/response pair plus the errors — validation failure, authz denial, not-found, conflict/idempotent-replay, limit refusal — with exact bodies. Examples are the executable part of a contract doc: they pin what prose leaves open, and error examples force the error model to actually get designed (the unhappy-path floor, core.md, applied to contracts). If the project uses OpenAPI/schema files, draft the stub; else the contract doc carries the examples.

Phase 5 — Consumer's-eyes review

Before finalizing, switch sides (lens activation, core.md): write the client code for the hard consumer case from Phase 1 — the actual calls, the pagination loop, the retry-on-409, the error handling — against your draft. Every place the client code gets awkward (three calls where one is needed, ambiguous error branching, undocumented ordering) is a contract bug found at paper price. Then write the careless client — the one that ignores the return value: if misreading an entry point fails open, change the shape until it fails closed; when both a quiet and a loud form are needed, ship two differently named operations rather than one with a flag. Check consistency against the existing surface one last time — a second dialect in one API is a permanent tax on every consumer.

When the awkwardness is that one call is too general, layer it: one entry point makes the dominant case a single obvious call, an explicit path serves the rare one over the same implementation — not seven optional parameters, and not a thin wrapper to delete. Per parameter, keep it when dropping would drag a dependency into the body; never trade one for global state.

Deliver: contract doc (+ schema stub) to the Plans location (<slug>-api-contract.md), route to /threat-model if the surface is new/external (entry points are already enumerated — cheap now), then /prepare (the contract becomes plan steps; interface-first, so parallel sessions build against it).

Hard rules

• Consistency beats best practice — deviations from the house dialect are declared decisions, not silent improvements. A departure costs the reader a learning curve: say what the convention already buys, then justify the departure as self-explanatory or worth the curve.
• Every list paginates; every non-GET has a retry story; every endpoint has error examples. No exceptions without an "accepted — why" line.
• Expose default-closed — each field earns its place; you can add later, you can never remove (from a public version).
• Breaking changes don't ship in place — they route through /rollout coexistence.
• Read-only on app code — the deliverables are the contract doc and schema stub.

See also

• /codebase-design — internal seams (this skill is its public-boundary sibling);
• /threat-model — the same surface, attacker's eyes; /rollout — shipping contract changes; /analyst — the WHAT/WHY feeding this; rules/_generic/resilience.md, code.md — the always-on floor the contract must satisfy.