Contract-First API Design
Diseña el contrato de la API antes del código: versionado, idempotencia, paginación por cursor
Probado · Funciona
Qué hace
Una skill doctrinal que hace que Claude escriba el contrato de la API antes de cualquier código de implementación, eligiendo el estándar correcto para el protocolo (OpenAPI, AsyncAPI, proto, GraphQL SDL) y fijando el versionado, códigos de error, claves de idempotencia, paginación por cursor, encabezados de límite de tasa y una política de deprecación. Se activa cuando solicitas diseñar una nueva API o endpoint, o para verificar si un cambio rompe clientes existentes. Sin scripts, sin herramientas — es una lista de verificación de revisión y autoría que el modelo aplica a tu diseño.
Informe de la prueba
Diseñé la misma API de acortador de URL dos veces (una vez en frío, otra siguiendo el cuerpo de la skill) y comparé los dos contratos con una rúbrica de contrato de 13 puntos: la versión en frío obtuvo 3, la versión con skill 13. La ejecución con skill añadió los elementos que son cambios importantes para adaptar posteriormente: una Idempotency-Key requerida en POST (el borrador en frío acuñó silenciosamente un segundo código corto al reintentar), paginación por cursor firmada con un límite máximo en lugar de página/offset, error_code legible por máquina más request_id en cada respuesta, encabezados X-RateLimit-*, una política de deprecación Sunset y una puerta CI oasdiff. También detectó una segunda superficie de contrato que el borrador en frío omitió por completo: el evento de clic de Kafka necesita su propio artefacto AsyncAPI. Costo: la pasada impulsada por la skill se desvió hacia la mecánica del contrato y omitió dos reglas de dominio que tenía el borrador en frío (ventana de reciclaje de código, reintento de colisión), por lo que complementa en lugar de reemplazar el pensamiento de producto.
Probado el: 2026-07-28 · Claude Code 2.x (agent harness)
Instalación
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
Comandos y prompts de ejemplo
/contract-first-api-designDiseña el contrato de la API antes del código: versionado, idempotencia, paginación por cursor
Los skills se activan con peticiones en lenguaje natural, sin comandos que memorizar. Tras instalarlo, prompts como estos lo activan (en inglés):
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?