API Contract Review

Audita controladores Spring/REST para verbos HTTP, versionado, códigos de estado y compatibilidad.

Por decebals · decebals/claude-code-java

Probado · Funciona ★ 8.8/10

API Contract Review — Audita controladores Spring/REST para verbos HTTP, versionado, códigos de estado y compatibilidad.

Qué hace

Revisa controladores de API REST (enfocados en Java/Spring) contra una lista de verificación de 6 puntos que cubre la semántica de verbos HTTP, versionado de URL, fugas de DTO vs entidad, corrección de códigos de estado, formato de respuesta de error y compatibilidad hacia atrás. Se activa cuando el usuario pide revisar una API, verificar endpoints REST, o antes de lanzar cambios de API. Se empareja con spring-boot-patterns, que escribe controladores mientras esta los audita.

Informe de la prueba

Obtuve SKILL.md + README vía API de GitHub/crudo; ambos archivos referenciados devuelven HTTP 200, el frontmatter tiene nombre+descripción, sin scripts externos, sin olores de seguridad (solo consejos benignos de grep en línea). Escribí un SpringUserController con problemas plantados (eliminar basado en GET, POST para actualización idempotente, sin /v1/, retorno de entidad, nulo si falta, Map status:200 body) y produje dos revisiones. La línea base detectó el GET-delete, retorno nulo, fuga de entidad y paginación faltante, pero NO detectó el versionado, el verbo PUT/POST incorrecto, el anti-patrón 200-con-status-body, y la falta de @Valid; la revisión de la skill detectó todos esos y organizó los hallazgos por las 6 categorías, omitiendo ruido de higiene no relacionado (inyección de constructor). Juicio del disparador: se carga en "revisar los endpoints REST en UserController", "verificar mi API antes de lanzar", "¿son correctos mis verbos/códigos de estado HTTP?"; correctamente NO se carga en "escribir un nuevo controlador REST para pedidos" (creación, no auditoría) o "revisar mi esquema de DB para indexación" (no REST) — 5/5.

Probado el: 2026-07-21 · Claude Code 2.x (agent harness)

Instalación

git clone --depth 1 https://github.com/decebals/claude-code-java.git /tmp/api-contract-review-src
mkdir -p ~/.claude/skills
cp -R /tmp/api-contract-review-src/.claude/skills/api-contract-review ~/.claude/skills/api-contract-review
# Self-contained: SKILL.md + README.md only, no external scripts or deps.
# Java/Spring-oriented (Spring annotations, JPA entities), but the HTTP/REST
# checklist applies to any REST API. No API keys, no tools to install.

Comandos y prompts de ejemplo

/api-contract-reviewAudita controladores Spring/REST para verbos HTTP, versionado, códigos de estado y compatibilidad.

Los skills se activan con peticiones en lenguaje natural, sin comandos que memorizar. Tras instalarlo, prompts como estos lo activan (en inglés):

Review this API for backward compatibility issues
Check these endpoints for REST semantics violations
Review the API contract before releasing v2

Informe completo →