Tienes una idea. Le pides a Claude o Cursor que la construya. En 20 minutos tienes algo que funciona.
Dos semanas después, el proyecto es una bomba de tiempo. Cada feature nueva rompe algo. Nadie sabe por qué el código hace lo que hace. Y cada prompt al agente sale peor que el anterior porque el contexto se ha ido acumulando sin orden.
Eso no es un problema de la IA. Es un problema de proceso.
El vibe coding tiene un límite
El vibe coding es real. Funciona. Para prototipos, para explorar ideas, para hacer algo pequeño en un fin de semana.
Pero tiene un problema de escala.
Cuando el proyecto crece, el conocimiento sobre él vive en tu cabeza. En el historial de chats con el agente. En comentarios dispersos. Cuando quieres cambiar algo, tienes que reconstruir el contexto desde cero cada vez.
El agente ejecuta bien. El problema es que ejecuta lo que le dices. Y si lo que le dices es ambiguo, incompleto o contradictorio, el resultado también lo es.
Spec-Driven Development (SDD) resuelve exactamente eso.
Qué es SDD
Una frase lo resume:
La spec se convierte en el artefacto primario que dirige todo el trabajo posterior: implementación, tests, documentación, verificación.
En el desarrollo tradicional, el código es la fuente de verdad. La documentación sirve al código.
SDD invierte esa relación.
La spec no sirve al código. El código sirve a la spec.
Defines el comportamiento esperado antes de que empiece la implementación. Ese comportamiento está escrito en un documento que el agente puede leer, seguir y contra el que puede verificar su trabajo.
El agente ejecuta. Tú piensas. Cada uno en su sitio.
Lo que SDD no es
Antes de seguir, tres malentendidos comunes:
No es documentación que nadie lee. Una spec de SDD vive con el código, se versiona con el código, y cuando el proyecto cambia, la spec cambia. No es un PDF en Confluence que nadie ha abierto en dos años.
No es waterfall. SDD describe el destino, no el camino. El destino puede cambiar. Lo que no cambia es el principio: antes de que el agente ejecute, alguien tiene que haber pensado qué se quiere conseguir.
No mata la velocidad. La velocidad que te dio la IA se queda. Lo que cambia es que ahora va en la dirección correcta.
Las 7 fases del flujo
Matt Pocock publicó en 2025 un video sobre su flujo de trabajo con IA — más de 250k visualizaciones — donde describió siete momentos que ocurren en cualquier proyecto serio. Independientemente de la herramienta.
Aquí están.
Fase 1: Idea
Todo empieza aquí. La trampa es ir demasiado rápido a la siguiente fase.
Tienes la idea. La entiendes en tu cabeza. Quieres empezar.
El problema: "la entiendes en tu cabeza" no significa que esté suficientemente definida para que un agente la ejecute bien. En tu cabeza hay contexto implícito, restricciones que das por sentadas, decisiones que no has tomado conscientemente.
Una pregunta para salir de la fase 1: ¿puedo describir lo que quiero en dos frases que no sean ambiguas?
Si la respuesta es no, todavía estás aquí.
Fase 2: Research (opcional)
Si hay algo desconocido en el proyecto — una API nueva, una integración que nunca hiciste — necesitas entenderlo antes de especificar.
Formato: un archivo research.md. Temporal, vive mientras dura el sprint. No es documentación permanente. Es caché.
Fase 3: Prototipo (opcional)
El prototipo ocurre antes de la spec, no después.
Si le pides al agente que construya sin haber tocado el problema primero, el agente toma todas las decisiones de diseño, de UX, de arquitectura. El resultado puede ser perfectamente funcional y completamente distinto a lo que habrías elegido tú.
El prototipo es rápido y desechable. Una vez que lo tienes, lo commiteas. La spec puede referenciarlo. Entonces sí: a especificar.
Fase 4: PRD (La spec)
El Product Requirements Document. El artefacto central de todo el método.
El PRD describe el destino, no el viaje. Qué tiene que ser verdad cuando el trabajo esté hecho. Quién lo usa. Qué puede hacer. Qué no puede hacer. Qué asumes sobre el estado actual. Qué criterios vas a usar para verificar que está hecho.
No cómo implementarlo.
Un PRD bien escrito tiene menos de 500 palabras. Si es más largo, está describiendo implementación.
Ejemplo mínimo de estructura:
## Objetivo
[Qué problema resuelve esta feature en una frase]
## Usuarios
[Quién lo usa y en qué contexto]
## Comportamiento esperado
- [El usuario puede hacer X]
- [El sistema responde con Y]
- [Cuando Z ocurre, el resultado es W]
## Fuera de scope
- [Qué NO incluye esta versión]
## Assumptions
- [Qué das por sentado sobre el estado actual del sistema]
## Criterios de aceptación
- [ ] [Verificable, concreto, testeable]
- [ ] [...]
La sección de assumptions es la que más impacto tiene en la calidad del código generado. Es también la que más gente se salta.
Fase 5: Kanban
El PRD define el destino. El kanban define el camino.
El PRD se convierte en issues. Cada issue es una unidad de trabajo que el agente puede ejecutar de forma independiente.
Dos principios para dividirlo:
Vertical slices. Cada issue implementa algo de punta a punta: interfaz, lógica, base de datos. No issues por capa. No "issue de frontend" + "issue de backend". Eso genera dependencias artificiales y hace imposible verificar hasta que todos están hechos.
Tracer bullets. Los unknowns más arriesgados van primero. Si no sabes si algo es técnicamente posible de la forma en que lo imaginaste, ese es el primer issue.
Fase 6: Execution loop
Aquí el agente toma el control.
El loop es simple: el agente lee el issue, implementa, comenta y cierra. Pasa al siguiente.
Lo que nunca es opcional: leer el código que el agente produce. No para microgestionar. Para mantener el criterio sobre lo que se está construyendo. El agente ejecuta bien. Pero tú sigues siendo el responsable del resultado.
Fase 7: QA
El trabajo está hecho. Pero no está terminado.
QA significa verificar que el comportamiento real del sistema coincide con el comportamiento especificado en el PRD. El agente puede ayudar: dale el PRD y el código y pídele que genere un plan de QA. El plan lo genera él. Las pruebas las ejecutas tú.
Los bugs y las inconsistencias que encuentres se convierten en nuevos issues. Vuelven a la fase 6.
El flujo en una imagen
IDEA
└─ ¿Está suficientemente definida?
RESEARCH (si aplica)
└─ research.md — caché temporal de lo desconocido
PROTOTIPO (si aplica)
└─ Exploración rápida, desechable — commitear como referencia
PRD
└─ Destino, no viaje
└─ Máx. ~500 palabras — criterios de aceptación testeables
KANBAN
└─ Vertical slices — tracer bullets primero
└─ Blocking relationships — dependencias explícitas
EXECUTION LOOP
└─ Agente ejecuta issue por issue
└─ Humano lee el código producido
QA
└─ Agente genera el plan — humano ejecuta
└─ Bugs → nuevos issues → vuelve al loop
Por qué ahora
Thoughtworks, en su radar tecnológico de 2025, describió SDD como "una de las prácticas más importantes que emergieron con la IA generativa."
GitHub SpecKit tiene más de 72.000 estrellas y soporte para más de veinte plataformas: Claude Code, GitHub Copilot, Amazon Q, Gemini CLI. No es un proyecto de nicho. Es infraestructura.
¿Por qué importa ahora y no antes?
Porque antes, las specs las leían desarrolladores humanos. Un desarrollador puede llenar huecos, hacer preguntas, pedir aclaraciones.
Un agente no puede. Un agente rellena los huecos con lo que le parece más probable.
Y lo que le parece más probable no siempre es lo que tú querías.
Cuando el ejecutor es una IA, la calidad de las instrucciones importa más que nunca. SDD es la respuesta a eso.
Para empezar hoy
Tengo una plantilla gratuita de PRD que puedes usar en tu próximo proyecto. Incluye la estructura completa, ejemplos de criterios de aceptación y la sección de assumptions que la mayoría se salta.
👉 dominicode.com/spec-driven-development
Bezael — DominiCode
Top comments (0)