Spec-Driven Development con Claude Code: el workflow en la práctica
Cómo correr Spec-Driven Development dentro de Claude Code: plan mode, el sistema de contexto en tres capas, steering files, gates de .status y subagents especializados que convierten una IA sin estado en un colaborador consistente.
Claude Code es capaz y no guarda estado. Sin un sistema, esa combinación es peligrosa. Spec-driven development resuelve el segundo problema para que puedas usar el primero con seguridad.
Este es el complemento práctico de qué es spec-driven development: el cómo, específicamente en Claude Code. ¿Nuevo en SDD? Empieza por ahí. ¿Ya entiendes por qué importan las specs? Es aquí.
El método le da a Claude Code tres cosas que no puede conseguir por sí solo: una memoria que sobrevive a la sesión, un gate de aprobación que impide implementar antes de tiempo y un review estructurado que contrasta el resultado con lo que realmente se aprobó. Cada sección de abajo agrega una pieza de ese sistema.
Anthropic ya te dijo que planifiques primero
Antes de cualquier framework, lee el manual de quien hizo el modelo. Las buenas prácticas de Claude Code que publica Anthropic describen un loop de cuatro pasos: explorar, planificar, implementar, hacer commit. Hay un plan mode dedicado cuya única función es impedir que el agente escriba código mientras piensa. El motivo que dan es directo: “dejar que Claude salte directo al código puede producir código que resuelve el problema equivocado.”
Plan mode no es un empujoncito conceptual. Es una funcionalidad real del producto. En la terminal, Shift+Tab entra a plan mode. Ahí, Claude lee archivos y responde preguntas sin cambiar nada. Cuando tienes un plan que vale la pena revisar, Ctrl+G lo abre en tu editor para que lo edites directamente antes de que Claude siga. Después sales de plan mode y dejas que implemente.
Anthropic es igual de específica sobre lo que contiene una buena spec: “las specs más útiles son autocontenidas: nombran los archivos e interfaces involucrados, dicen qué queda fuera del alcance y terminan con un paso de verificación de punta a punta que demuestra que la feature funciona.” Esa frase es el brief de diseño de todo lo que sigue.
La técnica de la entrevista para la spec
Anthropic publica el prompt que convierte una idea en spec antes de que exista una sola línea de código. Esta es su plantilla:
I want to build [brief description]. Interview me in detail using the
AskUserQuestion tool. Ask about technical implementation, UI/UX, edge
cases, concerns, and tradeoffs. Don't ask obvious questions, dig into
the hard parts I might not have considered. Keep interviewing until
we've covered everything, then write a complete spec to SPEC.md.Córrelo en una sesión nueva. Claude te presiona con edge cases que todavía no consideraste. Cuando termine, abre otra sesión nueva para implementar. El contexto limpio mantiene la implementación enfocada solo en la spec, y no en la conversación que la produjo.
Esta es la fase de PRD de un workflow de SDD estructurado, formalizada. La técnica es de Anthropic. El sistema alrededor es el método.
Cuándo saltarte el plan
Anthropic traza la línea sin rodeos: “si puedes describir el diff en una frase, sáltate el plan.” Una variable renombrada, una línea de log, un typo: nada de eso necesita spec. La ceremonia existe para trabajo que dura más de una sentada, atraviesa varias sesiones o toca arquitectura y corrección de verdad. Para todo lo demás: prompt y listo.
CLAUDE.md es la capa uno, no el sistema completo
Claude Code lee CLAUDE.md al inicio de cada conversación. Anthropic lo llama “un archivo especial que Claude lee al inicio de cada conversación” y da una disciplina clara para mantenerlo útil: “sé conciso. Para cada línea, pregúntate: ¿quitarla haría que Claude se equivoque? Si no, bórrala. Los archivos CLAUDE.md inflados hacen que Claude ignore tus instrucciones reales.”
Esa última frase es la falla en la que cae la mayoría de los devs. Llenan el CLAUDE.md de convenciones de código, preferencias de herramientas, normas del equipo y contexto del proyecto hasta llegar a 400 líneas. Claude lee el primer tercio y se salta el resto. Las convenciones que más importan son las que se pierden.
La solución no es organizar mejor el CLAUDE.md. Es sacar la mayor parte del contenido de ahí y llevarlo a un sistema de contexto con tres capas, cada una con un solo trabajo.
El sistema de contexto en tres capas
Un proyecto que dura más de una sesión necesita tres capas de contexto, cada una con una vida útil y una función distintas.
Tres capas, tres funciones
- 01
CLAUDE.md
Se carga en cada sesión. Contiene solo lo que tiene que cargarse antes de que el agente haga cualquier cosa: punteros a las otras capas, un recordatorio de una línea para revisar el .status antes de implementar y las reglas de comportamiento que aplican a todas las conversaciones.
Mantenlo por debajo de 30 líneas. Si quitarlo no causa errores, bórralo.
- 02
steering/
Contexto estable del producto, que casi nunca cambia. Qué es el producto y qué no es, el stack con sus motivos, convenciones de código más allá del linter y las reglas de arquitectura innegociables. El CLAUDE.md apunta aquí; el agente lee lo que necesita.
Cambia cuando tomas una decisión de arquitectura deliberada. Nunca cambia por una sola feature.
- 03
specs/NNN-feature/
Specs por feature que evolucionan a lo largo del pipeline: requisitos, diseño, tasks y el archivo .status que habilita la implementación. El único lugar donde se autoriza trabajo de implementación.
Cada archivo avanza una fase. .status es el único gate. Que el archivo exista no es aprobación.
CLAUDE.md es un conjunto corto de punteros: “El contexto del producto vive en steering/. Las specs de features viven en specs/NNN-name/. Antes de implementar cualquier cosa, lee el archivo .status de esa feature.” Esa estructura de punteros hace que Claude lea los archivos correctos cuando importan, y no todo de golpe. También es lo que mantiene corto el CLAUDE.md: la mayor parte del contenido tiene un mejor lugar.
El directorio completo
Estructura de proyecto para SDD con Claude Code
- CLAUDE.md// punto de entrada, se carga en cada sesión, enruta al agente a todo el contexto de abajo
- steering/estable
- product.md// qué es, quién lo usa, qué explícitamente no es
- tech-stack.md// stack, versiones, librerías y el motivo de cada una
- conventions.md// estructura de API, forma de los errores, patrones de auth, reglas de nombres
- principles.md// reglas de arquitectura que sostienen el sistema, las innegociables
- specs/
- 001-user-auth/feature
- requirements.md// comportamientos en formato EARS, criterios de aceptación
- design.md// arquitectura, modelos de datos, contratos de API
- tasks.md// unidades implementables, 2-4h cada una, testeables de forma independiente
- .status// tasks:approved es la única luz verde para EXEC
- .claude/
- commands/slash commands// /spec, /tasks, /review para cada etapa del pipeline
- agents/
- architect.md// diseña, nunca implementa
- implementer.md// implementa solo después de tasks:approved, SE DETIENE ante la ambigüedad
- reviewer.md// revisa solo contra la spec, no contra preferencias
La profundidad es deliberada. CLAUDE.md es un archivo de enrutamiento. La carpeta steering guarda la memoria del producto. La carpeta de spec guarda la feature actual. La carpeta agents guarda los prompts de los subagents. Armas esta estructura una vez y trabajas desde ella en cada feature.
El toolkit que convierte esto en slash commands es mi @felipefontoura/pi-sdd-kit, que implementa la misma estructura para el Pi coding agent. El método funciona sin ningún kit, con markdown plano y disciplina constante. Lo que importa es la estructura; el tooling es opcional.
Steering: la memoria que sobrevive a la sesión
Los cuatro archivos en steering/ guardan el contexto que el agente necesita para tomar buenas decisiones sin que tengas que volver a explicar todo en cada sesión.
product.md es una respuesta de dos páginas a qué hace el producto, quién lo usa y qué deliberadamente no hace. Un agente que no sabe que “esto es un backend de pagos para comercios cripto, no una app de consumo” va a derivar hacia defaults de consumo, agregar features que nadie pidió y optimizar lo que no es. El alcance negativo importa tanto como el positivo.
tech-stack.md indica el stack, las versiones y por qué se tomó cada decisión importante. No es una lista de dependencias: es una justificación. “PostgreSQL porque los registros de pagos necesitan garantías ACID” es la frase que evita que el agente sugiera SQLite cuando agregues un módulo nuevo dentro de tres sesiones. El motivo es lo que hace útil al archivo entre sesiones. Sin él, el archivo es un changelog que nadie lee.
conventions.md va más allá de las reglas del linter. Registra patrones: cómo se estructuran las rutas de la API, qué forma tienen los errores, cómo se aplica la autenticación en el borde. El conocimiento tácito que vive en la cabeza de los devs con experiencia, hasta que alguien lo escribe.
principles.md es el archivo más corto y el más difícil de escribir bien. Reglas de arquitectura que sostienen el sistema, en oraciones declarativas. En la fintech: “Toda la aritmética de dinero es con enteros, nunca float.” “Ningún acceso directo a la base de datos fuera de la capa de repositorio.” “Si no estás seguro de que algo está dentro del alcance, no lo está.” Estas restricciones evitan errores de categoría antes de que el agente genere una sola línea de código.
Estos archivos cambian poco. Cuando cambian, es porque tomaste una decisión de arquitectura deliberada. Escribirla en steering/ es como esa decisión se vuelve contexto permanente del agente en todas las sesiones futuras.
El pipeline con gates
Cada feature pasa por una secuencia definida. IDEA y PLAN son opcionales para trabajo chico o bien conocido. La secuencia central para cualquier feature real va del PRD al REVIEW:
Pipeline de SDD en Claude Code
Entrada
Un comportamiento a construir: no una línea de código, algo que el sistema tiene que hacer
- PRDDocumento de requisitos de producto
Descripción en lenguaje de negocio: qué tiene que hacer el sistema, quién lo usa, qué queda explícitamente fuera del alcance. Sin código. Aquí vive la técnica de la entrevista para la spec.
- SPECEspecificación técnica
Requisitos en formato EARS, decisiones de arquitectura, modelos de datos, contratos de API. Gate humano antes de seguir: el .status tiene que decir requirements:approved, después design:approved.
- TASKSDescomposición en tasks
Unidades implementables de 2-4 horas cada una, testeables de forma independiente, con dependencias explícitas. El Implementation Readiness Check confirma que cada requisito se mapea a por lo menos una task. Gate humano: el .status tiene que decir tasks:approved.
- EXECImplementación
El agente lee tasks.md e implementa task por task. Solo empieza cuando el .status dice tasks:approved. Plantea cada ambigüedad antes de actuar.
- REVIEWReporte de verificación
Cada task verificada: Claim, Command, Exit code, Verdict PASS o FAIL. Un FAIL significa que la spec estaba mal: corrige el documento y regenera. Nunca parchees el código para esconder un error de la spec.
Salida
Feature implementada con un rastro de auditoría trazable desde el requisito hasta el resultado de la verificación
El gate entre TASKS y EXEC se aplica con un único archivo .status dentro de cada carpeta de feature. Una línea. El agente lo lee antes de cada paso de implementación. El estado de ese archivo es la única señal de aprobación que el agente respeta.
Suena obvio hasta que ves a un agente apurado saltar de una spec terminada directo a la implementación porque los archivos existen. El gate lo impide. Actualizas el .status a mano, después de leer y aprobar cada fase. Ese paso manual es la aprobación humana alrededor de la cual está construido todo el método. También es el hábito más difícil de sostener con la presión de un deadline, que es justo cuando más importa.
Tres subagents especializados
El patrón más efectivo es repartir el trabajo entre tres subagents acotados, en lugar de pedirle a un solo agente que haga todo. Cada uno tiene una función y una restricción.
Los tres subagents
- 01
Architect
Lee el PRD y todo el contexto de steering. Produce requirements.md y design.md: modelos de datos, contratos de API, decisiones tecnológicas con justificación explícita y un mapa de trazabilidad de cada requisito a una decisión de diseño.
Restricción central: nunca escribir código de implementación. Si te piden implementar, aclara el alcance.
- 02
Implementer
Lee tasks.md y .status (tiene que decir tasks:approved). Implementa task por task y escribe los tests junto con el código. Los requisitos EARS de la spec son los criterios de aceptación, no la interpretación que el Implementer hace de ellos.
Restricción central: DETENTE si encuentras ambigüedad. No supongas. No infieras. Pregunta.
- 03
Reviewer
Lee requirements.md, design.md, tasks.md y todo el código generado. Revisa solo contra la spec: no contra buenas prácticas generales, no contra preferencias de estilo. Reporta brechas, no opiniones.
Restricción central: revisa contra la spec, no contra tus preferencias. No agregues requisitos. Solo señala brechas.
El patrón del Reviewer coincide directamente con la recomendación de la propia Anthropic para ejecuciones autónomas: “antes de dar una task por terminada, haz que un subagent revise el diff en un contexto limpio y reporte las brechas.” Su razonamiento es preciso: un reviewer que corre en un contexto de subagent limpio ve solo el diff y los criterios que le das, y no el razonamiento que produjo el cambio. Evalúa el resultado por lo que es. El subagent Reviewer de aquí es esa recomendación hecha explícita, con una restricción que impide que se convierta en una segunda sesión de diseño.
La separación entre Architect e Implementer resuelve una falla específica. Un agente que diseña e implementa tiene un incentivo para diseñar algo que ya sabe construir. El Architect no puede escribir código, así que las decisiones de diseño tienen que sostenerse solas. La restricción también vuelve honesto el documento de diseño: lo escribió algo que no puede tomar atajos en sus propias recomendaciones.
GitHub Spec Kit vs pi-sdd-kit: qué te da cada uno
El Spec Kit de GitHub le da a tu agente un pipeline de skills para spec-driven development: una constitution una vez por proyecto, luego /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement y /speckit-converge por feature. Codifica el instinto correcto, escribir la spec antes del código, y corre en Claude Code, instalando sus skills en .claude/skills. Es la opción correcta cuando tu equipo usa varios agentes y quiere un estándar compartido. Lo cubro a fondo en la guía de GitHub Spec Kit. La comparación más amplia, con OpenSpec y Superpowers, está en OpenSpec vs. Spec Kit vs. Superpowers.
Qué te da cada enfoque
| Característica | GitHub Spec Kit | Estructura de pi-sdd-kit |
|---|---|---|
| Workflow spec-first | Sí, de specify a converge | Sí, vía pipeline del PRD a TASKS |
| Memoria estable del producto entre sesiones | En parte: constitution.md guarda los principios | Sí, carpeta steering/ con 4 archivos de contexto |
| Gate de aprobación legible por máquina | No: --require-spec solo comprueba que el archivo exista | Sí, archivo .status con token explícito |
| Subagents especializados con restricciones | No viene incluido | Sí, Architect / Implementer / Reviewer |
| Soporte de agentes | 42 integraciones, Claude Code incluido | El método funciona con cualquier agente |
Si estás armando un prototipo en una tarde, ninguno de los dos hace falta. Una spec en markdown y el plan mode alcanzan para obtener el beneficio. La estructura gana valor a medida que se multiplican las sesiones, las features y las personas del equipo.
Una feature del PRD al REVIEW
Aquí va una feature concreta pasando por el pipeline: PATCH /users/me para que un usuario autenticado actualice su nombre visible y su zona horaria. Es una versión simplificada de un endpoint real de la fintech.
PRD en cinco minutos. La feature en lenguaje de negocio: “Los usuarios autenticados necesitan actualizar su nombre visible (2-64 caracteres) y su zona horaria (string IANA, validado en el servidor). Pueden actualizar uno o ambos campos en una sola solicitud. Ningún otro campo del perfil está dentro del alcance de este endpoint.”
El Architect lee el PRD y steering/ (específicamente tech-stack.md y principles.md) y produce requirements.md en formato EARS:
WHEN an authenticated user sends PATCH /users/me,
THE SYSTEM SHALL validate all provided fields before persisting any change.
IF displayName is provided AND length is less than 2 OR greater than 64,
THE SYSTEM SHALL return 400 with message "displayName must be 2 to 64 characters".
IF timezone is provided AND is not a valid IANA timezone identifier,
THE SYSTEM SHALL return 400 with message "Invalid timezone identifier".
THE SYSTEM SHALL NOT allow unauthenticated requests to this endpoint.Revisas. Los requisitos coinciden con el PRD. Ninguna ambigüedad. Actualizas .status a requirements:approved.
El Architect produce design.md: route handler, capa de validación, método del repositorio, forma de la respuesta y una nota explícita de que la validación de zona horaria usa la base IANA tz del servicio de auth existente. Revisas. El diseño se mapea limpio a cada requisito y sigue steering/conventions.md. Actualizas .status a design:approved.
La descomposición produce cuatro unidades en tasks.md:
- Agregar la ruta
PATCH /users/mecon guard de autenticación. Testeable: la ruta devuelve 401 sin un token válido. - Implementar la validación de displayName. Testeable: 400 con menos de 2 o más de 64 caracteres.
- Implementar la validación de zona horaria contra la base IANA. Testeable: 400 con un string de zona horaria desconocido.
- Implementar el método de update en el repositorio. Testeable: persiste los cambios y devuelve el objeto de usuario actualizado.
El Implementation Readiness Check confirma que cada requisito se mapea a por lo menos una task, que cada task es testeable de forma independiente y que no hay dependencias no declaradas. .status pasa a tasks:approved.
El Implementer lee tasks.md, encuentra tasks:approved y recorre la lista en orden: tests en paralelo, no después. A mitad de la task 3 se topa con una ambigüedad: ¿qué status HTTP si la cuenta del usuario está desactivada? SE DETIENE y pregunta en lugar de adivinar. Respondes: 403. Esa decisión vuelve a requirements.md antes de retomar la implementación.
Después de EXEC, el Reviewer corre el reporte de verificación:
Reporte de verificación: PATCH /users/me
| Claim | Command | Exit code | Verdict |
|---|---|---|---|
| 401 sin token de auth | curl -X PATCH /users/me | 0 | PASS |
| 400 con displayName demasiado corto | PATCH /users/me displayName=x (1 carácter) | 0 | PASS |
| 400 con zona horaria inválida | PATCH /users/me timezone=badzone | 0 | PASS |
| 403 con cuenta desactivada | PATCH /users/me X-Test-Inactive: 1 | 0 | PASS |
| 200 con update válido | PATCH /users/me displayName=Felipe | 0 | PASS |
Todas las filas dan PASS. Si alguna diera FAIL, la corrección empezaría en la spec: el requisito estaba mal (actualiza requirements.md) o a la implementación se le escapó algo (corrige tasks.md y regenera). La spec es la fuente de verdad. Parchear el código para que pase una fila de la verificación y dejar la spec como estaba es la forma silenciosa en que muere el método.
Ese loop (del PRD al REVIEW) es el mismo para cada feature. La disciplina se acumula: después de diez features, los steering files están afinados, el agente casi nunca se detiene por ambigüedad y el Implementation Readiness Check toma dos minutos porque los patrones ya están establecidos. La fricción queda toda al principio.
Una falla real que atrapó el gate
Durante la construcción de la fintech, una de las primeras specs de creación de cobros pasó el PRD y llegó al gate en la revisión de diseño. Los requisitos EARS estaban bien. Pero al design.md que produjo el Architect le faltaba la restricción de idempotencia: el índice UNIQUE(merchant_id, idempotency_key) que garantiza cobrar exactamente una vez a nivel de base de datos.
El diseño era técnicamente coherente. Y estaba mal. El gate obligó a revisar el diseño antes de que el agente pudiera implementar. Detecté la restricción faltante en esa revisión, y no en un incidente en producción.
Un agente apurado sin el gate habría implementado a partir del diseño, el índice no existiría y el primer retry bajo carga habría generado un cobro duplicado. En un sistema que mueve transacciones reales en BRL, eso no es un escenario de prueba. El gate lo atrapó cuando todavía era un archivo de texto, y no un error de facturación. Un error detectado en el diseño cuesta minutos. Detectado en producción, en un sistema de pagos, cuesta semanas y una disculpa.
Por eso también el gate es manual. Un gate automático podría avanzar con “design.md está completo.” El gate humano obliga a leer, y leer es la única forma de detectar lo que contiene un documento técnicamente válido pero equivocado.
Cómo el CLAUDE.md crece mal, y cómo podarlo
El patrón es predecible. Una mala sesión produce una regla. La siguiente mala sesión produce otra. Tres meses después, el CLAUDE.md tiene 300 líneas y el agente ignora la mitad. La descripción de la falla, en palabras de Anthropic: “si Claude sigue haciendo algo que no quieres a pesar de tener una regla en contra, probablemente el archivo es demasiado largo y la regla se está perdiendo.”
Checklist para podar el CLAUDE.md
- Obligatorio:¿Quitar esto haría que Claude se equivoque?Si no, bórralo. Es la prueba de la propia Anthropic, al pie de la letra. Aplícala a cada línea, no solo a las sospechosas.
- Obligatorio:¿Claude ya hace esto bien sin la instrucción?Entonces la instrucción es ruido. Bórrala o conviértela en un hook para aplicarla de forma determinística.
- Obligatorio:¿Es conocimiento de dominio o un paso de workflow?Muévelo a un steering file o a un archivo en .claude/skills/. El CLAUDE.md no es una base de conocimiento; es configuración de comportamiento.
- Obligatorio:¿Claude sigue ignorando esta regla a pesar de la instrucción?El archivo es demasiado largo y la regla quedó enterrada. Primero poda, después reformula. Un archivo corto con tres reglas le gana a uno largo con treinta.
- Obligatorio:¿Es una regla de comportamiento no obvia que aplica a cada sesión?Esta se queda. El CLAUDE.md es para instrucciones de comportamiento a nivel de sesión que no pueden vivir en otro lado.
La forma correcta del CLAUDE.md en un proyecto que usa este sistema: una descripción breve de la estructura en tres capas, un puntero a steering/ para el contexto del producto, un puntero a specs/ para el trabajo de features, la instrucción de revisar .status antes de implementar y las reglas de comportamiento que aplican siempre. Menos de 30 líneas. Todo lo demás va en otro lado.
FAQ
¿Claude Code trae spec-driven development incorporado?
Claude Code trae plan mode incorporado, y las buenas prácticas de Anthropic describen el loop de cuatro pasos (explorar, planificar, implementar, hacer commit). Esa es la base del SDD aplicado a Claude Code.
Lo que Claude Code no trae incorporado es el sistema de contexto en tres capas, el gate de .status ni los subagents especializados. Esa es la estructura que aplicas encima, con markdown plano y disciplina o con una herramienta como pi-sdd-kit.
¿Qué es el plan mode en Claude Code?
Plan mode es una funcionalidad nativa de Claude Code que impide que el agente escriba código mientras explora y planifica. Presiona Shift+Tab en la terminal para entrar. En plan mode, Claude lee archivos y responde preguntas sin cambiar nada.
Presiona Ctrl+G para abrir el plan actual en tu editor y editarlo directamente. Después sal de plan mode y deja que Claude implemente. Anthropic recomienda usar plan mode para cualquier cosa más allá de un cambio trivial, y saltarlo cuando el diff se puede describir en una frase.
¿Qué es un steering file?
Un steering file es un documento de contexto persistente que el agente lee en cada sesión a través de los punteros del CLAUDE.md. Los cuatro principales (product.md, tech-stack.md, conventions.md, principles.md) responden las preguntas en las que el agente adivinaría: qué es el producto, sobre qué stack corre, cómo se escribe el código y qué reglas de arquitectura son innegociables.
Viven en steering/ y cambian poco. Cuando cambian, es porque tomaste una decisión de arquitectura deliberada. Escribirla es como esa decisión se vuelve contexto permanente del agente en todas las sesiones futuras.
Spec Kit vs Claude Code: ¿qué workflow gana?
GitHub Spec Kit y Claude Code no son herramientas rivales. Spec Kit es un kit de workflow que corre en muchos agentes, Claude Code incluido: instala skills (speckit-specify, speckit-plan, speckit-tasks y las demás) que codifican el spec-driven development.
Lo que el enfoque de pi-sdd-kit agrega encima es steering como memoria duradera más amplia que una constitution, .status como gate de aprobación legible por máquina y subagents con restricciones explícitas. Alcances distintos, no una competencia: puedes correr el pipeline de Spec Kit y mantener un gate de .status.
¿Por qué SDD usa un gate de .status en lugar de solo revisar la spec?
Porque 'ya lo revisé' es un estado mental, no una señal que el agente pueda leer. El archivo .status le da al agente un token explícito y legible por máquina que tiene que revisar antes de avanzar a la siguiente fase.
La regla dura (que un archivo exista no implica aprobación) existe porque, para un agente que recorre el directorio, un archivo terminado y un archivo aprobado se ven idénticos. El token de status elimina esa ambigüedad por completo.
¿Qué es pi-sdd-kit y lo necesito?
pi-sdd-kit es mi paquete de npm que codifica el workflow de SDD como slash commands para el Pi coding agent: /skill:sdd-prd, /skill:sdd-spec, /skill:sdd-tasks, /skill:sdd-exec, /skill:sdd-review y la convención del gate de .status. Publicado como @felipefontoura/pi-sdd-kit.
No lo necesitas. La carpeta steering/, la estructura specs/NNN-feature/ y el gate de .status funcionan con cualquier agente y cualquier editor usando markdown plano. El kit quita ceremonia y hace que el workflow sea consistente entre proyectos. Es infraestructura, no un requisito previo.
¿Qué es el Implementation Readiness Check?
Una validación previa a EXEC de que tasks.md está realmente listo para implementarse: cada requisito EARS se mapea a por lo menos una task, cada task tiene criterios de aceptación explícitos, cada task es testeable de forma independiente y ninguna task tiene una dependencia no declarada de otra.
Corre antes de que tasks:approved entre en .status. Su trabajo es distinguir 'creo que estamos listos' de 'la spec está lo bastante completa para implementar sin ambigüedad.' Son cosas distintas, y detectar esa diferencia aquí sale más barato que durante la implementación.
¿En qué se diferencia esto de usar un CLAUDE.md con muchas instrucciones?
CLAUDE.md es una capa: el punto de entrada que se carga en cada sesión. SDD agrega dos más: steering/ para el contexto estable del producto, que casi nunca cambia, y specs/NNN-feature/ para las specs por feature que evolucionan a lo largo del pipeline.
CLAUDE.md le dice al agente cómo comportarse. Steering le dice qué está construyendo y por qué se tomaron esas decisiones. La spec de la feature le dice qué construir ahora. Las tres sostienen el sistema. Cada una falla sin las otras dos.
A dónde ir ahora
SDD con Claude Code es una estructura que aplicas sobre la herramienta que ya tienes. El problema de memoria es real, y el sistema de contexto en tres capas (CLAUDE.md, steering, specs) lo resuelve sin agregar ceremonia que te frene.
El método está explicado completo en qué es spec-driven development. Para verlo corriendo a escala de producción (13 apps, dinero real, 70 días), el caso de estudio tiene las pruebas. Para los documentos de spec en sí (cómo escribir requisitos en formato EARS, qué contiene una sección de diseño completa, cómo descomponer tasks), el texto complementario es cómo escribir una spec a partir de la cual una IA pueda construir.
El kit está en @felipefontoura/pi-sdd-kit. Markdown plano y gates de aprobación consistentes alcanzan para empezar sin él.
La newsletter
Don’t Code, Specify. Cada semana, agentes de IA en producción de verdad. Sin hype: lo que funcionó y lo que se rompió.
Suscríbete en Substack (se abre en una pestaña nueva)El código ahora se escribe solo. Las specs, no. Ese es el trabajo.