Cómo redactar una spec efectiva para Claude Code
DominicodeAnatomía de una buena spec para Claude Code
Tiempo estimado de lectura: 6 min
- Una spec compacta y accionable evita suposiciones del agente y reduce iteraciones.
- La estructura mínima: Requirements → Design → Tasks → Implementation.
- Para bugs: seguir Report → Analyze → Fix → Verify.
- Coloca SPEC.md junto al código y versiona la spec con el PR.
Introducción
Anatomía de una buena spec para Claude Code: si esperas que un agente genere código alineado con tu arquitectura, la spec es el mínimo imprescindible. Sin ella, Claude Code (o cualquier agente) hará suposiciones; con ella, ejecutará decisiones coherentes desde la primera iteración.
Claude Code opera sobre repositorios y contexto local; el modelo subyacente (Claude) razona según la información que le entregues. Documenta la intención antes de pedir implementación y evitarás iteraciones costosas. Referencias útiles: Anthropic — Claude Code overview y Claude.
Resumen rápido (lectores con prisa)
Qué es: Una spec compacta y accionable que define comportamiento observable, diseño, tareas y criterios de aceptación para que Claude Code ejecute sin inventar.
Cuándo usarla: Antes de pedir a un agente que implemente features o arregle bugs en un repositorio.
Por qué importa: Minimiza suposiciones del agente, reduce iteraciones y evita parches superficiales.
Cómo funciona: Estructura mínima: Requirements → Design → Tasks → Implementation; para bugs: Report → Analyze → Fix → Verify.
Anatomía de una buena spec para Claude Code: estructura y propósito
Una spec útil no es un tratado largo. Es un artefacto compacto y accionable, pensado para que un agente pueda ejecutar sin inventar. Su estructura mínima:
- Requirements → 2. Design → 3. Tasks → 4. Implementation
Para bugs: Report → Analyze → Fix → Verify.
Cada bloque reduce incertidumbre y acota el espacio de decisiones del agente.
1. Requirements — qué debe hacer el sistema (externo)
Define el comportamiento observable, no la implementación.
Incluye:
- Comportamiento nominal: qué hace la API/función.
- Casos de borde: inputs nulos, límites, formatos erróneos.
- Restricciones no funcionales: latencia p95 < 200 ms, tamaño máximo de payload 2 MB.
- Dependencias permitidas/prohibidas.
Ejemplo (sin spec vs con spec):
Con spec: “POST /users: recibe {email, name}. Valida email según RFC 5321. Inserta en PostgreSQL usando el ORM X. Devuelve 201 con {id, email, name} o 409 si email existe. No usar nuevas dependencias.”
2. Design — cómo debe integrarse la solución (interno)
Define firmas, modelos y patrones. Evita que el agente elija un estilo distinto al del repo.
Incluye:
- Firma de funciones/handlers (tipado).
- Modelos DTO/Entity.
- Patrones obligatorios (repositorio, servicios, inyección).
- Efectos secundarios permitidos (logs, eventos, mutaciones).
Plantilla mínima:
Function: createUser(payload: CreateUserDto): PromiseModels: CreateUserDto, UserDto, UserEntity (campos, tipos)Patterns: usar userRepository.insert, no acceso directo a SQL.
3. Tasks — pasos atómicos y ordenados
Desglosa el trabajo en tareas verificables. Un agente ejecuta mejor secuencias claras.
Ejemplo de Tasks para feature nueva:
- Añadir CreateUserDto en src/models.
- Implementar userRepository.insert según patrón existente.
- Implementar handler POST /users con validación.
- Añadir tests unitarios (caso feliz, email duplicado, payload inválido).
- Actualizar documentación OpenAPI.
Cada tarea debe producir un artefacto comprobable.
4. Implementation — criterios de aceptación y pruebas
Define qué significa “terminado”. No dependas solo de que compile o pase CI.
Incluye:
- Cobertura mínima (ej. 80% sobre módulo).
- Tests obligatorios (unit + integración básica).
- Requisitos de performance y seguridad.
- Revisión arquitectónica (no introducir dependencias nuevas, mantener separaciones).
Ejemplo: “Merge solo si tests pasan y cobertura del módulo ≥ 85%; latencia p95 < 200ms en test de integración local.”
Flujo para bugs: Report → Analyze → Fix → Verify
Para corrección de errores, no saltes al fix. Sigue este flujo:
- Report: pasos reproducibles, logs, versión del commit.
- Analyze: causa raíz documentada (por el agente o humano) con ubicación del código.
- Fix: parche mínimo que restaure el contrato.
- Verify: tests que confirmen el caso original y aseguren regresión negativa.
Pedir “arregla X” sin Analyze genera parches superficiales que reaparecen.
Ejemplos reales (comparativa rápida)
Caso: validar emails
Sin spec: agente instala validator.js y devuelve distinto comportamiento al estándar del proyecto.
Con spec: “validateEmail(input: string): boolean — RFC 5321, rechaza dominios locales, no usar libs externas.” Resultado: implementación consistente y sin nuevas dependencias.
Caso: feature auth token
Sin spec: token store ad-hoc en memoria.
Con spec: define AuthToken interface, TTL, almacenamiento en redis existente y tests. Resultado: integración correcta con infra existente.
Práctica recomendada y colocación en repo
- Coloca SPEC.md junto al test file o en la carpeta del feature.
- Versiona la spec con el mismo PR.
- Incluye ejemplos de I/O y criterios de aceptación textuales.
- Si usas herramientas visuales, añade diagramas Mermaid (https://mermaid.js.org/) o contrato OpenAPI (https://spec.openapis.org/).
Conclusión
Claude Code puede automatizar implementaciones, pero su fidelidad depende de tu spec. La diferencia entre un parche plausible y una integración sostenible es específica: Requirements → Design → Tasks → Implementation para features; Report → Analyze → Fix → Verify para bugs. Escribe la spec antes de ejecutar al agente. Lo barato es ahorrar minutos ahora; lo caro es rehacer horas después.
Dominicode Labs
Si trabajas con automatización, agentes o workflows, considera recursos prácticos y experimentos en Dominicode Labs. Es una continuación lógica para explorar patrones operativos y plantillas de spec aplicables a pipelines de IA y automatización.
FAQ
- ¿Qué debe contener la sección Requirements de la spec?
- ¿Por qué es importante definir el Design explícitamente?
- ¿Cómo se desglosan las Tasks de forma efectiva?
- ¿Qué criterios deben incluirse en Implementation?
- ¿Cuál es el flujo recomendado para corregir bugs?
- ¿Dónde debo colocar la SPEC.md en el repo?
Respuesta — ¿Qué debe contener la sección Requirements de la spec?
Debe definir el comportamiento observable: casos nominales, bordes, restricciones no funcionales (p. ej. latencia, tamaño de payload) y dependencias permitidas o prohibidas.
Respuesta — ¿Por qué es importante definir el Design explícitamente?
Porque evita que el agente elija un estilo distinto al del repositorio. Definir firmas, modelos y patrones garantiza consistencia con la arquitectura existente.
Respuesta — ¿Cómo se desglosan las Tasks de forma efectiva?
Divídelas en pasos atómicos y ordenados que produzcan artefactos comprobables (archivos, tests, cambios en la API). Cada tarea debe ser verificable aisladamente.
Respuesta — ¿Qué criterios deben incluirse en Implementation?
Criterios de aceptación claros: cobertura mínima de tests, pruebas obligatorias (unit/integración), requisitos de performance y restricciones de seguridad o dependencias.
Respuesta — ¿Cuál es el flujo recomendado para corregir bugs?
Report (pasos reproducibles y logs) → Analyze (causa raíz y ubicación) → Fix (parche mínimo) → Verify (tests que confirmen y prevengan regresiones).
Respuesta — ¿Dónde debo colocar la SPEC.md en el repo?
Junto al test file o en la carpeta del feature. Versiona la spec en el mismo PR para mantener trazabilidad.