Contract-First API Design
Entwerfen Sie den API-Vertrag vor dem Code: Versionierung, Idempotenz, Cursor-Paging
Getestet · Funktioniert
Was es kann
Ein Doktrin-Skill, der Claude dazu bringt, den API-Vertrag vor jeglichem Implementierungscode zu schreiben, den richtigen Standard für das Protokoll (OpenAPI, AsyncAPI, proto, GraphQL SDL) auszuwählen und Versionierung, Fehlercodes, Idempotenzschlüssel, Cursor-Paginierung, Rate-Limit-Header und eine Deprecation-Richtlinie festzulegen. Wird ausgelöst, wenn Sie eine neue API oder einen Endpunkt entwerfen oder prüfen möchten, ob eine Änderung bestehende Clients beeinträchtigt. Keine Skripte, keine Tools – es ist eine Überprüfungs- und Erstellungs-Checkliste, die das Modell auf Ihr Design anwendet.
Testbericht
Entwarf dieselbe URL-Shortener-API zweimal – einmal 'kalt', einmal nach dem Skill-Text – und verglich die beiden Verträge mit einer 13-Punkte-Vertragsrubrik: Die kalte Version erzielte 3 Punkte, die Skill-Version 13. Der Skill-Lauf fügte die Dinge hinzu, die später zu Breaking Changes führen würden: einen erforderlichen Idempotency-Key bei POST (der kalte Entwurf prägte stillschweigend einen zweiten Kurzcode bei Wiederholung), signierte Cursor-Paginierung mit einem Max-Limit anstelle von Seite/Offset, maschinenlesbaren error_code plus request_id bei jeder Antwort, X-RateLimit-*-Header, eine Sunset-Deprecation-Richtlinie und ein oasdiff CI-Gate. Es fing auch eine zweite Vertragsoberfläche ab, die der kalte Entwurf vollständig übersehen hatte – das Kafka-Klickereignis benötigt ein eigenes AsyncAPI-Artefakt. Kosten: Der Skill-gesteuerte Durchlauf driftete in die Vertragsmechanik ab und ließ zwei Domänenregeln fallen, die der kalte Entwurf hatte (Code-Recycling-Fenster, Kollisionswiederholung), sodass er das Produktdenken ergänzt, anstatt es zu ersetzen.
Getestet am: 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
Befehle & Beispiel-Prompts
/contract-first-api-designEntwerfen Sie den API-Vertrag vor dem Code: Versionierung, Idempotenz, Cursor-Paging
Skills reagieren auf normale Anfragen — keine Slash-Befehle nötig. Nach der Installation aktivieren Prompts wie diese den Skill (auf Englisch):
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?