Contract-First API Design
Design API-kontrakten før koden: versjonering, idempotens, markør-paginering
Bestått
Hva den gjør
En doctrine skill that makes Claude write the API contract before any implementation code, picking the right standard for the protocol (OpenAPI, AsyncAPI, proto, GraphQL SDL) and pinning down versioning, error codes, idempotency keys, cursor pagination, rate-limit headers and a deprecation policy. Utløses når du ber om to design a new API or endpoint, or to check whether a change breaks existing clients. No scripts, no tooling — it is a review-and-authoring checklist the model applies to your design.
Testrapport
Designed the same URL-shortener API twice — once cold, once following the skill body — and diffed the two contracts against a 13-point contract rubric: the cold version scored 3, the skill version 13. The skill run added the things that are breaking changes to retrofit later: a required Idempotency-Key on POST (the cold draft silently minted a second short code on retry), signed cursor pagination with a max limit instead of page/offset, machine-readable error_code pluss request_id on every response, X-RateLimit-* headers, a Sunset deprecation policy and an oasdiff CI gate. It also caught a second contract surface the cold draft missed entirely — the Kafka click event needs its own AsyncAPI artifact. Cost: the skill-driven pass drifted into contract mechanics and dropped two domain rules the cold draft had (code recycling window, collision retry), so it complements rather than replaces product thinking.
Testet på: 2026-07-28 · Claude Code 2.x (agent harness)
Installer
git clone https://github.com/robisson/build-like-amazon-agent-skills.git mkdir -p ~/.claude/skills cd build-like-amazon-agent-skills && cp -r skills/api-contract-first ~/.claude/skills/contract-first-api-design
Kommandoer og eksempelprompter
/contract-first-api-designDesign API-kontrakten før koden: versjonering, idempotens, markør-paginering
Skills utløses av vanlige forespørsler — ingen kommandoer å huske. Etter installasjonen aktiverer prompter som disse skillen (på engelsk):
Design the REST API contract for our new billing service before codingWe're adding v2 endpoints, how do we avoid breaking existing clients?What pagination and idempotency contract should POST /payments have?