Spec-driven development: primero la especificación, después el código
Escribir la especificación antes de que la IA genere código y usarla como fuente de verdad. Sus fases en Spec Kit, qué debe contener y cuándo no conviene.
¿Qué problema intenta resolver?
El vibe coding, donde describes una idea sin detalle y aceptas el resultado, tiene un problema de deriva. En cada sesión la IA puede tomar decisiones nuevas: cambiar un nombre, inventar una arquitectura u olvidar una regla de la sesión anterior. Sin un documento que lo fije, nadie sabe qué se decidió ni por qué.
La especificación funciona como contrato. Si la regla “un cliente solo ve sus propias citas” está escrita, cada cambio posterior puede contrastarse con ella. Fernando Ruiz lo plantea así en su artículo del blog: la especificación es el contrato que una interfaz de chat no puede dar por sí sola (Spec-Driven Development, en el blog).
El término todavía no tiene una definición cerrada. Birgitta Böckeler, de Thoughtworks, lo resume en martinfowler.com como escribir una especificación antes de escribir código con IA, y distingue tres niveles de compromiso:
- Spec-first: la especificación se escribe primero y se usa para la tarea en curso.
- Spec-anchored: se conserva después de terminar la tarea, para evolucionar y mantener la función.
- Spec-as-source: la especificación es el archivo principal y las personas solo editan eso, nunca el código.
Según su análisis, todas las herramientas que revisó son spec-first; no todas aspiran a los otros dos niveles.
¿Cuáles son las fases?
GitHub publicó Spec Kit, un kit de código abierto con licencia MIT, y lo presentó en su blog el 2 de septiembre de 2025. Su flujo tiene cuatro fases. Según GitHub, con IA la especificación se convierte en la fuente de verdad y determina qué se construye (GitHub Blog, Spec Kit).
| Fase | Qué produce | Qué revisa una persona |
|---|---|---|
| Especificar | Un documento con usuarios, problemas, recorridos y criterios de éxito | Que describa el qué y el porqué, sin tecnología |
| Planificar | Un plan técnico con stack, arquitectura y restricciones | Que respete los estándares del equipo |
| Tareas | Una lista de elementos pequeños que se pueden probar | Que se puedan cortar o reordenar antes de programar |
| Implementar | El código, tarea por tarea | Cada cambio, en lugar de un volcado enorme de código |
Spec Kit añade una “constitución”: principios generales del proyecto, como calidad de código o pruebas, que se aplican a todos los cambios. Böckeler advierte que los archivos y listas de verificación que genera los interpreta la IA, así que no hay garantía de que los cumpla.
Otras herramientas siguen una lógica parecida. Kiro, por ejemplo, trabaja con tres documentos en Markdown por función: requirements.md (historias de usuario y criterios de aceptación), design.md (arquitectura técnica) y tasks.md (tareas con seguimiento) (Kiro, documentación de specs).
¿Qué debe contener la especificación?
Según GitHub, la especificación trata del lado del usuario: quién usará el producto, qué problema resuelve, cómo interactúa y qué resultados importan. No se trata de stacks técnicos ni del diseño de la app: las decisiones técnicas van en el plan. Para un diseñador esto es una ventaja: ya piensa en estados, flujos y reglas. Una especificación útil responde cinco preguntas:
- ¿Quién usa el producto?
- ¿Qué problema resuelve y para cuándo?
- ¿Cuáles son los recorridos principales, paso a paso?
- ¿Qué reglas no se pueden romper?
- ¿Cómo sabemos que funciona?
La quinta es la que más se omite. Un criterio como “el usuario recibe confirmación en menos de dos segundos” se puede probar; “debe ser rápido” no. Para llevar esto a un documento de producto, mira cómo escribir un PRD que un agente entienda.
¿Cómo se usa en la práctica?
Una guía de Augment Code describe el flujo de Spec Kit con comandos y archivos concretos. Hay puntos de control humanos entre etapas: la persona edita la especificación antes de que se genere el plan, ajusta arquitectura y contratos en el plan, recorta o reordena las tareas y revisa el cambio de cada tarea. Hay un análisis de consistencia opcional, que corre después de las tareas, para buscar huecos entre especificación, plan y tareas (Augment Code, guía de Spec Kit). Augment vende una plataforma competidora, así que conviene leer sus comparaciones con cautela.
La misma guía señala límites. En un proyecto existente, hay que escribir la constitución antes de la primera especificación; si no, se generan plantillas genéricas que ignoran la arquitectura real. Y un archivo de tareas con cientos de entradas se vuelve difícil de editar. Su sugerencia es recortar funciones hasta que el archivo de tareas quepa en una sola pasada de implementación.
¿Cuándo NO conviene?
El método tiene costo. Böckeler describe que usar el flujo completo en un error pequeño le pareció como usar una maza para romper una nuez. También cuenta que prefería revisar código antes que tantos archivos Markdown, que a menudo repetían lo mismo entre sí y con el código existente. Vio que el agente no seguía todas las instrucciones y que, al generar código varias veces desde la misma especificación, el resultado variaba. Y se declara escéptica de mucho diseño anticipado.
La conclusión práctica es proporcional: un script de una tarde o una demo para una reunión no necesitan cuatro documentos. A más personas, más vida útil y más cambios previstos, más sentido tiene especificar. Si no estás seguro, compara con cuándo no hacer vibe coding y con vibe coding vs. ingeniería asistida.
Ejemplo
Ejemplo ilustrativo: un equipo de diseño construye un formulario de solicitud de vacaciones. La especificación de una página dice quién aprueba, qué pasa si el jefe no responde en cinco días y qué estados tiene una solicitud (borrador, enviada, aprobada, rechazada). Al planificar, la IA propone una base de datos; el equipo la revisa y cambia el almacenamiento porque ya tiene uno. Las tareas se dividen en “crear solicitud”, “aprobar” y “notificar”. Cuando el jefe pide un cambio de regla, se modifica la especificación primero y el plan se regenera, sin rehacer todo el código.
¿Cómo aplicarlo mañana?
- Toma una función que vas a pedir esta semana y escribe su especificación en una página, con las cinco preguntas anteriores.
- Revisa el plan que propone la IA antes de dividirlo en tareas. Corta lo que sobra y anota qué decisiones cambiaste y por qué.
- Ejecuta una tarea a la vez y revisa el resultado contra el criterio de éxito de la especificación, no contra tu impresión. Si el cambio es grande, usa una rama y un pull request.
- Cuando cambie una regla, edita primero la especificación y luego regenera el plan. Si especificación y código no coinciden, el documento está obsoleto y hay que corregirlo.
Con un proyecto pequeño puedes comprobar si el método te ahorra tiempo o solo te añade pasos. Para la revisión de cada resultado, mira iterar por prompts sin perder el control.
Errores comunes
- Escribir la especificación con detalles técnicos y no con comportamiento.
- Aprobar el plan sin leerlo, solo para llegar al código.
- Criterios de éxito imprecisos, como “debe ser intuitivo”.
- No actualizar la especificación cuando cambia una regla; el documento queda como ficción.
- Usar el método para scripts de una tarde.
- Dejar que la IA escriba la especificación sin que una persona de producto la revise.
- Suponer que el agente cumplió todo lo escrito sin comprobarlo.
Fuentes
- GitHub Blog, “Spec-driven development with AI: Get started with a new open source toolkit”
- Birgitta Böckeler, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl”, martinfowler.com
- Kiro, documentación de specs
- Augment Code, “GitHub Spec Kit: A Practical Guide to the SDD Workflow”
- Fernando Ruiz, “Spec-Driven Development: El fin del Vibe Coding amateur” (blog de fernandoux.com)