Contract-First API Design
Navrhněte API kontrakt před kódem: verzování, idempotence, stránkování kurzorem
Otestováno · Funguje
Co umí
Doktrinální skill, který přiměje Claudea napsat API kontrakt před jakýmkoli implementačním kódem, vybere správný standard pro protokol (OpenAPI, AsyncAPI, proto, GraphQL SDL) a určí verzování, chybové kódy, idempotency klíče, stránkování kurzorem, hlavičky pro omezení rychlosti a politiku zastarání. Spouští se, když požádáte o návrh nového API nebo endpointu, nebo o kontrolu, zda změna narušuje stávající klienty. Žádné skripty, žádné nástroje – je to kontrolní seznam pro revizi a autorství, který model aplikuje na váš návrh.
Testovací report
Navrhl jsem stejné API pro zkracování URL dvakrát – jednou 'za studena', jednou podle těla skillu – a porovnal oba kontrakty s 13bodovou rubrikou kontraktu: studená verze získala 3 body, verze skillu 13. Běh skillu přidal věci, které jsou později lámavými změnami k dodatečnému zavedení: povinný Idempotency-Key na POST (studený návrh tiše vytvořil druhý krátký kód při opakování), podepsané stránkování kurzorem s maximálním limitem namísto stránky/offsetu, strojově čitelný error_code plus request_id na každé odpovědi, hlavičky X-RateLimit-*, politiku zastarání Sunset a oasdiff CI bránu. Také zachytil druhou smluvní plochu, kterou studený návrh zcela opomenul – událost kliknutí Kafka potřebuje svůj vlastní AsyncAPI artefakt. Náklady: průchod řízený skillem se posunul do mechaniky kontraktu a vynechal dvě doménová pravidla, která měl studený návrh (okno pro recyklaci kódu, opakování kolize), takže spíše doplňuje než nahrazuje produktové myšlení.
Testováno: 2026-07-28 · Claude Code 2.x (agent harness)
Instalace
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
Příkazy a ukázkové prompty
/contract-first-api-designNavrhněte API kontrakt před kódem: verzování, idempotence, stránkování kurzorem
Skilly se spouštějí běžnými požadavky — žádné příkazy k zapamatování. Po instalaci ho aktivují prompty jako tyto (anglicky):
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?