Contract-First API Design
Projektuj kontrakt API przed kodem: wersjonowanie, idempotencja, stronicowanie kursorowe.
Testowano · Działa
Co robi ten skill
Umiejętność doktrynalna, która sprawia, że Claude pisze kontrakt API przed jakimkolwiek kodem implementacyjnym, wybierając odpowiedni standard dla protokołu (OpenAPI, AsyncAPI, proto, GraphQL SDL) i ustalając wersjonowanie, kody błędów, klucze idempotencji, stronicowanie kursorowe, nagłówki limitu szybkości i politykę deprecjacji. Uruchamia się, gdy prosisz o zaprojektowanie nowego API lub punktu końcowego, lub o sprawdzenie, czy zmiana nie łamie istniejących klientów. Brak skryptów, brak narzędzi – to lista kontrolna przeglądu i autorstwa, którą model stosuje do Twojego projektu.
Raport z testu
Zaprojektowano to samo API skracania URL dwukrotnie – raz na zimno, raz zgodnie z treścią umiejętności – i porównano oba kontrakty z 13-punktową rubryką kontraktową: zimna wersja uzyskała 3 punkty, wersja z umiejętnością 13. Uruchomienie umiejętności dodało rzeczy, które są zmianami łamiącymi kompatybilność do późniejszego dostosowania: wymagany Idempotency-Key na POST (zimny szkic cicho tworzył drugi krótki kod przy ponownej próbie), podpisane stronicowanie kursorowe z maksymalnym limitem zamiast page/offset, czytelny maszynowo error_code plus request_id w każdej odpowiedzi, nagłówki X-RateLimit-*, politykę deprecjacji Sunset i bramkę CI oasdiff. Złapało również drugą powierzchnię kontraktu, którą zimny szkic całkowicie pominął – zdarzenie kliknięcia Kafka potrzebuje własnego artefaktu AsyncAPI. Koszt: przejście napędzane umiejętnością wpadło w mechanikę kontraktu i pominęło dwie zasady domenowe, które miał zimny szkic (okno recyklingu kodu, ponowna próba kolizji), więc uzupełnia, a nie zastępuje myślenie produktowe.
Testowano: 2026-07-28 · Claude Code 2.x (agent harness)
Instalacja
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
Komendy i przykładowe prompty
/contract-first-api-designProjektuj kontrakt API przed kodem: wersjonowanie, idempotencja, stronicowanie kursorowe.
Skille uruchamiają się na zwykłe polecenia — bez komend do zapamiętania. Po instalacji aktywują go prompty takie jak te (po angielsku):
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?