Contract-First API Design
Concevoir le contrat d'API avant le code : versioning, idempotence, pagination par curseur
Testé · Fonctionne
Ce que fait
Une compétence doctrinale qui fait écrire à Claude le contrat d'API avant tout code d'implémentation, en choisissant le bon standard pour le protocole (OpenAPI, AsyncAPI, proto, GraphQL SDL) et en fixant le versioning, les codes d'erreur, les clés d'idempotence, la pagination par curseur, les en-têtes de limite de débit et une politique de dépréciation. Se déclenche lorsque vous demandez de concevoir une nouvelle API ou un nouveau point de terminaison, ou de vérifier si un changement rompt les clients existants. Pas de scripts, pas d'outils — c'est une liste de contrôle de révision et d'élaboration que le modèle applique à votre conception.
Rapport de test
Conçu la même API de raccourcisseur d'URL deux fois — une fois à froid, une fois en suivant le corps de la compétence — et comparé les deux contrats à une grille de 13 points : la version à froid a obtenu 3, la version avec compétence 13. L'exécution de la compétence a ajouté les éléments qui sont des changements majeurs à intégrer plus tard : une Idempotency-Key requise sur POST (le brouillon à froid a silencieusement créé un deuxième code court en cas de nouvelle tentative), une pagination par curseur signée avec une limite maximale au lieu de page/offset, un error_code lisible par machine plus request_id sur chaque réponse, des en-têtes X-RateLimit-*, une politique de dépréciation Sunset et une passerelle CI oasdiff. Elle a également détecté une deuxième surface de contrat que le brouillon à froid avait entièrement manquée — l'événement de clic Kafka a besoin de son propre artefact AsyncAPI. Coût : le passage piloté par la compétence a dérivé vers la mécanique du contrat et a omis deux règles de domaine que le brouillon à froid avait (fenêtre de recyclage de code, nouvelle tentative de collision), il complète donc plutôt qu'il ne remplace la réflexion produit.
Testé le: 2026-07-28 · Claude Code 2.x (agent harness)
Installation
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
Commandes et exemples de prompts
/contract-first-api-designConcevoir le contrat d'API avant le code : versioning, idempotence, pagination par curseur
Les skills se déclenchent sur des demandes en langage courant — aucune commande à retenir. Après installation, des prompts comme ceux-ci l'activent (en anglais) :
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?