- Spec-Driven Development (SDD) revive un enfoque tipo waterfall de redactar documentación extensa antes de programar; busca estructurar el trabajo para herramientas de asistencia de código con IA, pero corre el riesgo de perjudicar la agilidad
- La comunidad open source ha desarrollado herramientas que generan automáticamente especificaciones, planes de implementación y listas de tareas a partir de prompts e instrucciones iniciales; entre las más representativas están Spec-Kit, Kiro, Tessl y BMad Method
- Sin embargo, en el uso real aparecen varias limitaciones, como falta de reconocimiento de contexto, documentación excesiva, doble revisión de código y una falsa sensación de seguridad; en codebases grandes, la eficiencia cae con fuerza
- El artículo señala que SDD, como intento de reemplazar al desarrollador, repite el fracaso del modelo waterfall y propone en su lugar un desarrollo iterativo basado en lenguaje natural
- Un enfoque que combine los principios de Agile y Lean Startup resulta más adecuado para el desarrollo moderno con agentes de código, y el siguiente reto es avanzar en herramientas de interacción visual
La aparición del desarrollo guiado por especificaciones (SDD)
- Spec-Driven Development (SDD) introduce un proceso de redactar documentos de especificación antes de programar para ofrecer un método de desarrollo estructurado para herramientas de asistencia de código con IA
- A partir de prompts e instrucciones iniciales, un LLM genera especificaciones de producto, planes de implementación y listas de tareas
- Cada documento depende de la etapa anterior, y el usuario lo corrige para refinar la especificación
- Los documentos terminados se entregan a agentes de código como Claude Code, Cursor y Copilot para utilizarlos en la escritura de código
- Entre las herramientas representativas están Spec-Kit de GitHub, Kiro de AWS, Tessl y BMad Method (BMM)
- También se menciona el análisis comparativo Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl de Birgitta Böckeler
Los problemas de la documentación en Markdown
- Las especificaciones de SDD suelen estar compuestas principalmente por archivos Markdown; como ejemplo, una implementación sencilla de una función usando GitHub Spec-Kit llega a 8 archivos y 1,300 líneas
- El caso de agregar el campo “referred by” en Atomic CRM con Kiro también queda dividido en numerosos documentos
- En el uso real aparecen las siguientes desventajas
- Falta de reconocimiento de contexto (Context Blindness): se pierden funciones existentes o el contexto del código, por lo que sigue siendo necesaria la revisión de un experto
- Documentación excesiva (Markdown Madness): los documentos largos hacen que incluso buscar errores simples consuma mucho tiempo
- Burocracia sistemática (Systematic Bureaucracy): la repetición innecesaria y el exceso de detalle generan ineficiencia
- Falso Agile (Faux Agile): el mal uso del concepto de “User Story” provoca dispersión
- Doble revisión de código (Double Code Review): hay que revisar por separado el código en la especificación y la implementación real
- Falsa sensación de seguridad (False Sense of Security): el agente no sigue la especificación por completo
- Rendimientos decrecientes (Diminishing Returns): puede servir en proyectos iniciales, pero a mayor escala el ritmo se ralentiza
- Como la mayoría de los agentes de código ya ofrecen plan mode y funciones de lista de tareas, la ventaja adicional de SDD es limitada y puede incluso aumentar el costo de desarrollo
La revancha del project manager
- Las limitaciones de SDD podrían deberse a la inmadurez de las herramientas, pero en el fondo nacen de un planteamiento equivocado del problema
- Parte del objetivo de “cómo sacar al desarrollador del desarrollo de software”
- Propone reemplazar al desarrollador con agentes de código y controlarlos mediante una planificación minuciosa
- Esto se parece al modelo waterfall, ya que mediante una documentación masiva convierte al desarrollador en un simple traductor
- Pero el desarrollo de software es un proceso no determinista (non-deterministic), y la planificación por sí sola no puede eliminar la incertidumbre (se cita el artículo No Silver Bullet)
- SDD requiere tanto la experiencia de un analista de negocio en la etapa de requerimientos como la de un desarrollador en la etapa de diseño, por lo que en la práctica solo puede usarlo una minoría capaz de desempeñar ambos roles
- En consecuencia, al igual que las herramientas No Code, promete “desarrollo sin desarrolladores”, pero al final sigue necesitando desarrolladores
Una nueva alternativa: desarrollo iterativo basado en lenguaje natural
- La metodología Agile resolvió el problema del desarrollo no determinista al priorizar la adaptabilidad por encima de la previsibilidad
- Dividir requerimientos complejos en varios problemas simples es la clave para aprovechar agentes de código
- Se propone un proceso iterativo simple aplicando principios de Lean Startup
- Identificar la suposición más riesgosa del producto
- Diseñar el experimento mínimo para validarla
- Desarrollar el experimento e iterar según los resultados
- Como ejemplo, se desarrolló una herramienta de escultura 3D (sculpt-3D) en unas 10 horas usando Claude Code
- Sin especificaciones, se fueron agregando funciones gradualmente con instrucciones breves
- Las implementaciones incorrectas se corregían de inmediato y se iteraba con rapidez
- Este enfoque permite converger rápido sin documentación tipo waterfall, y la combinación de Agile con agentes de código hace posible construir productos en tiempo real
- Aun así, como los agentes de código están centrados en texto, falta interacción visual, por lo que en el futuro será necesario desarrollar herramientas que refuercen las interfaces visuales
Conclusión
- La metodología Agile ya había vuelto innecesarios los documentos de especificación, y SDD se evalúa como un intento de traerlos de vuelta
- SDD es un enfoque teórico que busca excluir al desarrollador y desperdicia la oportunidad de fortalecer a una nueva generación de desarrolladores mediante agentes de código
- Se compara a los agentes de código con un motor de combustión interna: mientras SDD los ata solo a una locomotora, nosotros deberíamos expandirlos hacia autos, aviones y otras formas
- Por último, si se considera el medio ambiente, hace falta un uso moderado de los agentes de código
1 comentarios
Opiniones en Hacker News
Como desarrollador, la mayor mejora de productividad que he logrado vino de crear el hábito de planear todo el trabajo por adelantado
Cada vez que recibo un ticket, lo descompongo en una gran lista de TODOs y dejo claros de antemano el diseño, las dependencias y la especificación
Eso me permite entrar con más frecuencia en estado de flujo (flow) cuando programo
Este enfoque también funciona con agentes de código con IA porque traslada el proceso de pensamiento de antemano
Expliqué más detalles en mi artículo
En la práctica, desglosar el problema y escribir especificaciones es algo bueno
El problema son las especificaciones inmutables. Si la implementación empieza meses después, la especificación se rigidiza
En cambio, Agile muchas veces se usa como excusa para posponer la planificación estratégica. El resultado es mucho retrabajo
Al final es un tema de equilibrio, y creo que “It depends” es un buen lema tanto para la vida como para el desarrollo
Si un LLM gestionara las especificaciones, podría reducirse la carga de mantenimiento
El artículo relacionado está aquí
Cuando es difícil estimar, primero hacemos un spike para explorar el código y las librerías
Creamos tanto un diagrama ideal como otro que refleje las restricciones reales, para evitar a largo plazo trampas arquitectónicas
Después de hacer vibe coding durante unos meses, en los últimos 6 meses cambié a spec-driven development
Paso 2 o 3 horas al día escribiendo especificaciones y despliego funcionalidades probadas ese mismo día
Escribir especificaciones no me volvió menos ágil. Al contrario, me permite iteraciones rápidas de 8 horas
La especificación no es un prompt, sino un criterio para juzgar la corrección
Tener pruebas end-to-end bien definidas reduce mucho los errores de la IA
El resultado cambia en cada ejecución y, al final, una persona igual tiene que revisarlo, así que puede ser ineficiente
Llamar “especificación” a una tarea de un día lleva a confusión. Al final es el proceso de siempre con otro nombre
A menudo interpretan mal incluso expresiones lógicas simples, así que hacer que entiendan especificaciones en lenguaje natural es riesgoso
Se la paso al agente, él implementa y yo solo reviso de vez en cuando
Mientras la IA trabaja, yo me pongo a arreglar mi auto de carreras, así que todos ganamos
Al final, lo único importante es que el código pase las pruebas
Este artículo parece dirigido a quienes ya concluyeron que “el desarrollo basado en especificaciones no es para mí”
Yo veo las especificaciones como un punto de entrada al contexto del LLM
Si le das suficiente información sobre la estructura del proyecto, modelos, funciones y requisitos, el LLM puede entender el contexto y extenderlo
Además, si haces que el propio LLM actualice la especificación, también se vuelve posible una iteración Agile
Las pruebas sirven como anclaje a la realidad (grounding) para el LLM y ayudan a evitar alucinaciones
Las pruebas son documentación y criterio de calidad, y al LLM hay que gestionarlo como si fuera un desarrollador junior
Si ejecutas varios agentes en paralelo y haces que se validen entre sí con una capa de pruebas, salen resultados sorprendentes
Gracias a los LLM puedes iterar la especificación completa de manera barata y veloz, pero la esencia sigue siendo la misma
Una especificación demasiado larga más bien estorba el pensamiento exploratorio
Como los LLM no son sistemas deterministas sino probabilísticos, ahora tenemos que debuggear la especificación en vez del código
El desarrollador debe evolucionar hacia un arquitecto de sistemas cognitivos (cognitive systems architect)
Coexisten especificaciones de alto nivel y especificaciones detalladas de componentes
Probé hacer una herramienta CLI con Spec-Kit de GitHub, pero hizo falta demasiado proceso de edición, análisis y reescritura
Como en waterfall, faltaba retroalimentación iterativa y eso era frustrante
Al final, en vez de revisar código incorrecto y buscar la causa, era mejor empezar de nuevo
Me gusta programar con LLM, pero SDD me pareció un flujo de trabajo pesado e ineficiente
A los LLM les gusta el contexto, así que hay que darles instrucciones claras de forma iterativa
Por ejemplo, al crear una app de NextJS, describo con claridad el login, el RBAC y que la implementación debe priorizar las pruebas
Empezar con unidades pequeñas e ir agregando funciones gradualmente encaja mejor
El problema de waterfall era el largo lead time y el alto costo de iteración
En SDD esas dos cosas se resuelven, así que me parece bien
Llamar waterfall a una especificación de unas pocas horas es una exageración
Si entras demasiado pronto en un espacio de soluciones complejo, resolver problemas simples se vuelve difícil
Agile empieza en un espacio pequeño y se expande gradualmente
Si la especificación es suficientemente detallada, la iteración se vuelve lenta; si no lo es, el LLM no funciona bien
Al final conserva la contradicción del waterfall que tanto les gusta a los gerentes
Los LLM funcionan mejor cuando reciben instrucciones claras en unidades pequeñas
Van a escribir especificaciones de varios años, ejecutar el LLM cada 6 meses y, si falla, culparán a los desarrolladores
Soy el propio autor del artículo
Me parece interesante que el debate de waterfall vs. Agile siga tan vivo
También es entretenido leer el contexto de quienes sienten que SDD sí les aporta valor
Pero yo ya uso el modo Plan antes de implementar, así que SDD no me aporta valor adicional
Casi nunca me ha tocado que un agente de código implemente algo perfecto de una sola vez
Al final siempre hace falta iterar, así que se pierde el sentido de Big Design Up Front
Aun así, sí creo que los agentes de código están abriendo un nuevo paradigma de desarrollo
Me acordé de este video que vi hace tiempo
Hablaba de lo que ingenieros y programadores pueden aprender unos de otros, y me llamó la atención la importancia de planear por adelantado
Se dice que Agile mató los documentos de especificación, pero en realidad solo los convirtió en miles de tickets de Jira
La IA podría registrar todas esas decisiones y contextos dispersos, y hacer preguntas cuando contradigan elecciones pasadas
Podría dar retroalimentación como: “¿La razón por la que Jim escribió este código así hace 5 años sigue siendo válida?”
Este artículo se me hizo un poco raro
Recibir una especificación incompleta y resolver a prueba y error es lo mismo para un desarrollador humano que para una IA
Si sabes con claridad lo que quieres, lo correcto es dar instrucciones detalladas
Quizá el punto real del artículo sea hablar de las “malas especificaciones”
En general, parece una lógica de autodefensa de la industria Agile
Probé SDD con varios archivos de especificación en Markdown, y lo que de verdad me resultó eficiente fue beads
Le permite al agente concentrarse siguiendo un árbol de tareas
Divide cada tarea con TDD y no deja pasar a la siguiente etapa hasta que las pruebas estén aprobadas
El agente incluso te indica comandos de revisión, así que el code review se vuelve fácil
Spec-Kit es demasiado pesado, así que beads es mucho más práctico
Incluso el proyecto zmx, que hice totalmente en modo vibe, después lo reescribí por completo tomando como referencia código del agente