Lo esencial
- El desarrollo guiado por especificaciones (SDD) consiste en escribir una spec antes de generar código con un agente de IA; la spec se convierte en la fuente de verdad para el humano y la máquina.
- Coexisten tres niveles: spec-first (spec escrita antes de la tarea), spec-anchored (spec conservada para el mantenimiento) y spec-as-source (solo se edita la spec).
- El riesgo principal es recaer en el ciclo en cascada: demasiado Markdown, relecturas duplicadas y specs que se desenganchan en cuanto el código crece.
- Una spec útil sigue siendo corta, behavior-oriented, y se vincula directamente a las user stories y a sus criterios de aceptación en un backlog vivo.
- Los criterios de aceptación en formato GIVEN/WHEN/THEN sirven como contrato verificable tanto para el agente de IA como para el equipo.
Por qué la spec vuelve a la mesa
Un asistente de código es un área de entrada y poco más. Sin menús, sin estructura impuesta. ¿Cómo asegurarse de que el código producido responde a la necesidad? La respuesta que se ha impuesto desde 2025: escribir una spec antes de dejar que el agente programe.
Este movimiento tiene un nombre, el desarrollo guiado por especificaciones (SDD). Birgitta Böckeler, Distinguished Engineer en Thoughtworks, da una definición operativa: escribir una spec antes de escribir código con la IA, convirtiéndose la spec en la fuente de verdad para el humano y para el agente (martinfowler.com).
GitHub, AWS con Kiro, Tessl o el método BMad proponen todos herramientas para ello. El principio es simple: un prompt inicial, algunas instrucciones, y el LLM genera specs de producto, un plan de implementación y una lista de tareas. Cada documento depende del anterior. El humano edita, el agente programa.
Tres niveles de SDD, que no hay que confundir
No todas las herramientas que se reclaman del SDD persiguen lo mismo. Böckeler distingue tres niveles (martinfowler.com):
- Spec-first: se escribe una spec cuidada antes de la tarea, y luego se usa en el flujo de desarrollo asistido por IA.
- Spec-anchored: la spec se conserva después de la tarea, para hacer evolucionar y mantener la funcionalidad.
- Spec-as-source: la spec es el archivo principal en el tiempo; el humano nunca toca el código.
Todas las herramientas son al menos spec-first. Pocas asumen el spec-anchored, aún menos el spec-as-source. Es un punto que hay que verificar antes de adoptar una herramienta: ¿en qué se convierte la spec dentro de seis meses, cuando el código haya cambiado?
Otra distinción útil: la spec no es el memory bank. El memory bank son los archivos de contexto válidos para todas las sesiones (reglas, descripción del producto, arquitectura). La spec, en cambio, solo concierne a la funcionalidad en curso de creación o modificación.
La trampa: el Markdown que entierra la agilidad
François Zaninotto, en Marmelab, probó el SDD y su veredicto es tajante: « Spec-Driven Development (SDD) revives the old idea of heavy documentation before coding — an echo of the Waterfall era » (marmelab.com).
Su ejemplo es elocuente. Con GitHub spec-kit, una funcionalidad simple — mostrar la fecha del día en una app de seguimiento de tiempo — produjo 8 archivos y 1300 líneas de texto. Con Kiro, añadir un campo « referred by » a unos contactos generó tres documentos: requirements, design, tasks.
Los problemas que enumera:
- Context blindness: el agente descubre el contexto por búsqueda textual y pasa por alto funciones existentes que hay que actualizar.
- Markdown madness: demasiado texto, sobre todo en fase de diseño; se lee en lugar de pensar.
- Burocracia sistemática: repeticiones, casos límite imaginarios, refinamientos inútiles.
- Falso agile: las « user stories » generadas no lo son. « As a system administrator, I want the referred by relationship to be stored in the database » no es una user story.
- Doble revisión de código: la spec técnica ya contiene código, que hay que releer antes de releer la implementación final.
- Rendimientos decrecientes: el SDD brilla en un proyecto nuevo, pero se desengancha en cuanto la base de código crece.
Zaninotto resume: « spending 80% of your time reading instead of thinking ». El SDD, en su versión pesada, repite el error del Big Design Up Front.
Cómo es una spec que se sostiene
Una spec útil no es un documento de 40 páginas. Es un artefacto estructurado, orientado a comportamiento, escrito en lenguaje natural, que expresa una funcionalidad y guía al agente (martinfowler.com). Bastan tres elementos.
El contrato de comportamiento
Lo que el módulo, la función o el endpoint debe hacer. Precondiciones, postcondiciones, invariantes. Tipos de entrada, de salida, de error. Sin ambigüedad.
El catálogo de casos límite
¿Qué pasa si la entrada es nula? ¿Vacía? ¿De tamaño máximo? ¿Negativa? ¿Unicode? ¿En concurrencia? El método VSDD propone plantear estas preguntas explícitamente al agente para que sea exhaustivo (gist.github.com).
Los criterios de aceptación
En formato GIVEN… WHEN… THEN…. Es lo que Kiro produce en su documento de requirements, siendo cada requirement una user story con sus criterios (martinfowler.com). Estos criterios sirven dos veces: al agente para generar el código, al equipo para verificar que el código hace lo que se pidió.
El punto clave: la spec debe ser verificable. Si no puedes escribir un test o un criterio de aceptación que la valide, es demasiado vaga.
Vincular spec, user stories y backlog
Una spec que vive en un archivo aislado no sirve para nada. Debe anclarse en el backlog, en el mismo lugar que las user stories y sus criterios de aceptación.
El framework AI SDLC Scaffold propone una estructura de carpetas que materializa este vínculo: una carpeta 1-spec/ con subcarpetas goals/, user-stories/, requirements/, assumptions/, constraints/, cada una con su template (github.com). Cada artefacto tiene un identificador (US-, REQ-, ASM-, CON-) y vive en el repositorio, versionado con el código.
Concretamente, en una herramienta de gestión de proyectos ágil:
- Una user story en el backlog con su prioridad y sus puntos.
- Sus criterios de aceptación en formato GIVEN/WHEN/THEN, en la descripción o en checklist.
- La spec corta vinculada a la story: contrato, casos límite, restricciones no funcionales.
- El enlace al código generado, para mantener la trazabilidad.
Este funcionamiento se integra de forma natural en un tablero Kanban con columnas personalizables, checklists y registro de actividad. Por ejemplo, en Ever Earlier, una user story puede llevar sus criterios de aceptación en checklist y su spec en adjunto o en comentario fijado, lo que evita mantener una carpeta Markdown separada que se desincroniza del backlog.
Lo importante no es la herramienta. Es que la spec siga viva: actualizada cuando la story evoluciona, archivada cuando se entrega, nunca dejada a pudrirse en un rincón.
Un método en cinco etapas
Aquí tienes un método concreto para specs cortas que generan código correcto.
- Partir de la intención, no del código. Describe la funcionalidad en tres frases. Si no puedes, es que la necesidad no está clara.
- Escribir la user story y sus criterios de aceptación. Formato « Como… quiero… para… » para la story, GIVEN/WHEN/THEN para los criterios. Tres a cinco criterios como máximo.
- Añadir el contrato de comportamiento y los casos límite. Media página basta. Enumera explícitamente las entradas degeneradas.
- Hacer que el agente genere el código, y luego releer. La spec guía, no garantiza nada. Böckeler cita a GitHub: « Crucially, your role isn't just to steer. It's to verify. » (martinfowler.com)
- Actualizar la spec tras la entrega. Si el código ha divergido, la spec debe reflejarlo. Si no, se convierte en una mentira documentada.
Un punto de vigilancia: los agentes no siempre siguen la spec. Zaninotto cuenta que un agente marcó la tarea « verify implementation » como hecha sin escribir un solo test unitario, redactando en su lugar instrucciones de test manual (marmelab.com). La verificación humana sigue siendo no negociable.
Lo que el SDD no resuelve
El SDD no es una varita mágica. Tres límites que hay que tener en cuenta.
La calidad de los datos de entrenamiento. Un estudio de Penn State y Oregon State University, publicado en Media Psychology, muestra que la mayoría de los usuarios no detecta un sesgo sistemático en los datos de entrenamiento de un sistema de IA, incluso cuando es visible (psu.edu). De 769 participantes repartidos en tres experimentos, la mayoría no notó que los rostros felices eran mayoritariamente blancos y los rostros tristes mayoritariamente negros. Dicho de otro modo: una spec bien escrita no protege de un modelo sesgado.
El contexto existente. El SDD brilla en un proyecto nuevo. En una base de código madura, las specs fallan en el contexto y ralentizan el desarrollo. Zaninotto lo dice sin rodeos: « For large existing codebases, SDD is mostly unusable. »
El mantenimiento de la spec. ¿Quién actualiza la spec cuando el código evoluciona? Si la respuesta es « nadie », el SDD se convierte en una capa de documentación muerta. Böckeler señala que la estrategia de mantenimiento a menudo queda vaga en las herramientas (martinfowler.com).
La conclusión razonable: quedarse con lo mejor del SDD — la spec como contrato verificable — sin retomar su pesadez documental. Specs cortas, ancladas en el backlog, vinculadas a las user stories y a sus criterios de aceptación. El resto es Markdown que no le sirve a nadie.