Contract-First API Design
Progetta il contratto API prima del codice: versioning, idempotenza, paginazione a cursore
Promosso
Cosa fa
Una skill dottrinale che fa scrivere a Claude il contratto API prima di qualsiasi codice di implementazione, scegliendo lo standard giusto per il protocollo (OpenAPI, AsyncAPI, proto, GraphQL SDL) e definendo versioning, codici di errore, chiavi di idempotenza, paginazione a cursore, header di rate-limit e una politica di deprecazione. Si attiva quando chiedi di progettare una nuova API o endpoint, o di verificare se una modifica rompe i client esistenti. Nessuno script, nessun tool — è una checklist di revisione e authoring che il modello applica al tuo design.
Rapporto di test
Progettato la stessa API di accorciamento URL due volte — una volta a freddo, una volta seguendo il corpo della skill — e confrontato i due contratti con una rubrica di contratto a 13 punti: la versione a freddo ha ottenuto 3, la versione con skill 13. L'esecuzione della skill ha aggiunto gli elementi che sono modifiche che rompono la compatibilità da retrofittare in seguito: una Idempotency-Key richiesta su POST (la bozza a freddo coniava silenziosamente un secondo codice breve al riprovo), paginazione a cursore firmata con un limite massimo invece di pagina/offset, error_code leggibile dalla macchina più request_id su ogni risposta, header X-RateLimit-*, una politica di deprecazione Sunset e un gate CI oasdiff. Ha anche colto una seconda superficie di contratto che la bozza a freddo aveva completamente mancato — l'evento click di Kafka necessita del proprio artefatto AsyncAPI. Costo: il passaggio guidato dalla skill è scivolato nella meccanica del contratto e ha tralasciato due regole di dominio che la bozza a freddo aveva (finestra di riciclo del codice, riprovo in caso di collisione), quindi completa piuttosto che sostituire il pensiero del prodotto.
Testato il: 2026-07-28 · Claude Code 2.x (agent harness)
Installazione
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
Comandi e prompt di esempio
/contract-first-api-designProgetta il contratto API prima del codice: versioning, idempotenza, paginazione a cursore
Gli skill si attivano con richieste in linguaggio naturale, senza comandi da ricordare. Dopo l'installazione, prompt come questi lo attivano (in inglese):
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?