¿Qué es el spec-driven development y cuándo es útil?

¿Qué es el spec-driven development?

Cuando le das una tarea a un agente de programación, casi siempre explicas lo que quieres en el chat. Si eso se queda solo en el chat, se pierde al cerrar la sesión. El spec-driven development (SDD) escribe esa intención en un archivo antes del código. La spec, abreviatura de especificación, es el documento que cuenta qué va a hacer el agente y por qué. El agente escribe primero la spec, luego un plan técnico que cuenta cómo hacerlo y después una lista de tareas. El código lo genera al final, a partir de estos documentos.

En el artículo de septiembre de 2025 en el que presentó Spec Kit, GitHub resume la idea en una frase: «We’re moving from “code is the source of truth” to “intent is the source of truth.”» Es decir, lo que es correcto no lo decide el código, sino la intención escrita. El mismo artículo dice también qué le toca al desarrollador: «Crucially, your role isn’t just to steer. It’s to verify.» Este artículo trata de esa segunda frase.

Qué pasa con la spec cuando el trabajo termina depende del enfoque. Los tres niveles del artículo de octubre de 2025 en el que Birgitta Böckeler, de Thoughtworks, probó tres herramientas de SDD aparecen hoy también en la documentación de Spec Kit:

• Spec-first. La spec se escribe antes del código; cuando el trabajo termina, se puede tirar.
• Spec-anchored. La spec se conserva después del trabajo y se usa en los cambios posteriores.
• Spec-as-source. Las personas solo editan la spec; el código se genera a partir de ella y nunca se cambia a mano.

Según Böckeler, todos los enfoques que encontró son spec-first; cómo mantener la spec con el tiempo suele quedar sin definir. Como veremos más abajo, esa indefinición es también lo que más complica la revisión de código.

Nuestra fuente principal sobre el uso real es el estudio Spec-Driven Development as Prescribed and as Practiced, de investigadores de la Universidad Carnegie Mellon y de Google. Su última versión en arXiv es del 15 de octubre de 2026. El estudio se basa en debates de Reddit, entrevistas con 21 profesionales (8 de ellos desarrollan herramientas) y 266 repositorios de GitHub. Los dos porcentajes de arriba también salen de este estudio.

Los archivos de reglas de los agentes de programación los explicamos en el artículo sobre AGENTS.md y CLAUDE.md, y cómo revisar un pull request escrito por IA, en otro artículo. Este pone la spec entre los dos.

¿Qué pasos llevan de la spec al código?

Las herramientas llaman a los pasos de forma distinta, pero el orden es el mismo: primero qué hay que hacer, luego cómo, después las tareas y, al final, el código. Al terminar cada paso, lees el documento y lo corriges; el agente pasa al siguiente con esa versión.

En Spec Kit se ejecuta /speckit.constitution una vez por proyecto y después, para cada funcionalidad, specify, plan, tasks, implement y converge, en ese orden. En la constitution están los principios del proyecto, y cada paso posterior se evalúa según ellos; se parece al archivo de reglas de un agente de programación. clarify, checklist y analyze son controles de calidad opcionales: se añaden cuando la tarea tiene puntos poco claros.

En Kiro, cada spec consta de tres archivos: requirements.md, design.md y tasks.md. Los requisitos se escriben con un patrón llamado EARS: «WHEN [condición] THE SYSTEM SHALL [comportamiento esperado]». El orden es requisitos, diseño, tareas; si ya tienes una arquitectura, también puedes empezar por el diseño. Los archivos de reglas de Kiro están en la carpeta .kiro/steering/, y Kiro también lee el AGENTS.md de la raíz del repositorio.

OpenSpec guarda cada cambio en una carpeta propia: en openspec/changes/<cambio>/ están la justificación (proposal.md), los requisitos (specs/), un diseño si hace falta (design.md) y las tareas (tasks.md). El ciclo es exploración, propuesta, revisión, aplicación y archivo. La spec de un cambio solo recoge la diferencia: qué requisito se añadió, cambió, eliminó o renombró. Al archivar, esas diferencias se incorporan a las specs principales en openspec/specs/; las specs principales describen cómo es el sistema hoy. Este es un archivo delta de ejemplo del README de OpenSpec:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Este archivo delta es la parte que más ayuda en la revisión: en el pull request muestra de un vistazo dónde cambió la intención. Volveremos a ello más abajo.

¿En qué se diferencian Spec Kit, Kiro y OpenSpec?

Leímos la documentación de las tres herramientas el 18 de octubre de 2026. La tabla muestra qué archivos escribe cada una, qué comprueba cuando termina el trabajo y qué propone para las tareas pequeñas:

Fuente: la documentación de cada herramienta, 18 de octubre de 2026. Cómo se escriben los comandos depende del agente de programación que uses (por ejemplo, /speckit.plan o /speckit-plan). Según la documentación de Kiro, los tests property-based solo funcionan en el IDE. En Kiro también puedes pedir que se analicen los requisitos antes del diseño en busca de incoherencias y huecos.

Las tres funcionan en sitios distintos. Spec Kit es un conjunto de herramientas de código abierto que se añade a tu agente de programación como comandos o skills. OpenSpec también se suma a las herramientas que ya usas; su README dice que es compatible con 30+ herramientas. Kiro, en cambio, es un agente de programación con IDE, CLI e interfaz web propios. El README de OpenSpec dice de Kiro que está «limited to Claude models»; en la página de modelos de Kiro, a 18 de octubre de 2026, aparecen también GPT-5.6 y modelos de pesos abiertos. Lo que una herramienta dice de su rival conviene comprobarlo en la documentación del propio rival.

En 2025 había un nombre más en esta lista: Tessl. Böckeler lo había probado junto a Kiro y Spec Kit. En septiembre de 2025, Tessl presentó sus primeros productos como basados en el spec-driven development: un Spec Registry en beta abierta y el Tessl Framework en beta cerrada. Su documentación actual, en cambio, define Tessl como «an open platform for managing agentic development across your organization» y no menciona el spec-driven development. El método sigue hoy en el registry de Tessl como un plugin público. No encontramos ninguna página actual que diga en qué estado está hoy el Tessl Framework.

Hay otros dos métodos de código abierto que trabajan con specs. En Superpowers, el agente primero averigua con preguntas qué quieres; los cambios pequeños se acuerdan en el chat y para los proyectos se prepara un documento de diseño por escrito. En la implementación, que funciona con subagentes, cada tarea se revisa en dos fases: primero la conformidad con la spec y después la calidad del código. BMAD Method dice que su proceso se ajusta al tamaño del trabajo: los cambios pequeños pasan directamente a la construcción.

¿Por qué lo llaman «el nuevo waterfall»?

El waterfall, o modelo en cascada, es el enfoque que diseña el trabajo de antemano y recorre las fases en un orden estricto: no se pasa al diseño sin requisitos escritos y aprobados, ni al código sin terminar el diseño. Según sus críticos, el spec-driven development trae de vuelta ese orden con archivos markdown. Dos artículos lo dicen en el propio título: «The Waterfall Strikes Back» y «Reinvented Waterfall?». Pero lo que tienen en común las críticas es, más que el orden, la carga de revisión.

Thoughtworks, octubre de 2025. Böckeler le pidió a Kiro que corrigiera un error pequeño. El documento de requisitos convirtió ese error pequeño en 4 historias de usuario con un total de 16 criterios de aceptación. Cuando probó Spec Kit con una funcionalidad más grande, también le parecieron demasiados los archivos markdown que tenía que leer para el tamaño del trabajo: «To be honest, I’d rather review code than all these markdown files.» Escribe además que, pese a tantos archivos, vio a menudo que el agente no seguía todas las instrucciones.

Scott Logic, noviembre de 2025. Colin Eberhardt borró una funcionalidad de una app que hace por afición, hizo que Spec Kit la construyera de nuevo y anotó el tiempo de cada paso. La construyó en dos pasos: primero las pantallas para gestionar los circuitos y después el GPS. El primer paso dejó 2.577 líneas de markdown y 689 líneas de código, y leerlas y revisarlas le llevó 3,5 horas; el segundo, 2.262 líneas de markdown y unas 300 líneas de código, con unas 2 horas de revisión. Cuando hizo la misma funcionalidad sin spec, como suele trabajar, invirtió 24 minutos en total: 15 minutos de revisión de código y 9 minutos de pruebas. Es la medición del propio Eberhardt: un solo desarrollador, una sola app de afición, Spec Kit tal como estaba en noviembre de 2025; el paso converge no aparece en ese artículo.

La diferencia no está en el código: sin spec, el código de los dos pasos sumaba unas 1.000 líneas. El tiempo se lo llevó el markdown. Eberhardt escribe que sin spec fue unas 10 veces más rápido y lo resume así: «For now, the fastest path is still iterative prompting and review, not industrialised specification pipelines.» Es la experiencia de un solo desarrollador con una sola app, no una medición general.

Marmelab, noviembre de 2025. Según François Zaninotto, la spec técnica ya contiene código. El desarrollador lee ese código antes de ejecutarlo y, como seguirá habiendo errores, lee también el código final: «As a result, review time doubles.» En el ejemplo que muestra, el agente dio por terminada la tarea «verify implementation» sin escribir ni un solo test unitario.

Thoughtworks Technology Radar, noviembre de 2025. El Radar colocó el método en el anillo «Assess» y escribió que algunas herramientas generan «lengthy spec files that are hard to review». Su nota termina con esta frase: «We may be relearning a bitter lesson — that handcrafting detailed rules for AI ultimately doesn’t scale.» Esa nota no figura en la edición actual del Radar.

Todas estas críticas hablan de la carga de revisión: más markdown que leer que código, leer dos veces lo mismo, un agente que no hace caso de lo escrito. Y todas se escribieron en otoño de 2025, con las herramientas tal como estaban entonces; la propia Böckeler señala que las herramientas cambian muy deprisa.

¿Qué ven distinto quienes lo defienden?

Meg Kretz, de Atomic Object, dice en su artículo de mayo de 2026 que el parecido está en el documento y la diferencia, en el comportamiento: «The difference comes down to four behaviors, which are observable, not philosophical.» Para ella, el waterfall usa los documentos como una puerta: se escriben, se aprueban, se congelan y se entregan. En el spec-driven development, en cambio, el documento es una herramienta de trabajo que se escribe y se reescribe junto con el código. Estos son los cuatro comportamientos que enumera:

• ¿Cuándo cambia la spec? El mismo día en que llega información nueva, a menudo dentro de la misma hora.
• ¿Cómo avanzan el diseño y la spec? Ninguno espera al otro; avanzan juntos y cada uno va cambiando al otro.
• ¿Cuándo termina el trabajo? Los requisitos Must/Should/May de la spec son los criterios de aceptación; cuando se cumplen, el trabajo está terminado.
• ¿Quién edita la spec? El desarrollador que se topa con una ambigüedad corrige la spec en ese momento; la corrección va al commit junto con el código.

Lo que Kretz llama la «prueba operativa» es, para la revisión, la idea central de este artículo: la spec y el código van en commits del mismo pull request. «If specs lag code, the spec is documentation, not source of truth.»

Los profesionales también cuentan mejoras, aunque con cautela. La mayoría de los participantes del estudio de Carnegie Mellon dice que las specs hacen más fiable el trabajo del agente, pero no logra separar esa mejora de la de los modelos en el mismo periodo. Un equipo que usó el método durante meses escribió que no podía demostrar que hubiera mejorado el código. Según el estudio, el SDD no elimina el coste: traslada tokens, tiempo y carga mental de la implementación a la planificación.

Desde esos artículos, también las herramientas han cambiado. Spec Kit añadió en junio de 2026 una extensión opcional para corregir errores y, también en junio de 2026, documentó cómo se mantienen las specs una vez terminado el trabajo. La documentación de Kiro incluye hoy Quick Spec, sin paso de aprobación, y el modo Plan, que no escribe archivos. Kiro describe así uno de los casos en que recomienda Quick Spec: «You've been defaulting to Vibe mode because the standard Spec flow felt too heavy».

¿Cuándo es útil y cuándo estorba?

El hallazgo del estudio de Carnegie Mellon es claro: la mayoría de los profesionales no usa el SDD para todo, sino según el tamaño de la tarea. Se lo saltan en tareas pequeñas, errores y scripts de un solo uso. Un participante dice, sobre un arreglo urgente en producción: «there is no time for spec-driven development and the whole flow». Otros deciden según el riesgo: si un error sale caro y la intención está clara, escriben una spec.

El rastro en los repositorios apunta en la misma dirección. Los investigadores hicieron que un modelo de lenguaje etiquetara una muestra de 1.000 specs; según su estimación, el 82,0 % de las specs describe una funcionalidad nueva. La documentación de las herramientas hace la misma distinción:

El escalón del medio importa. Kiro recomienda el modo Plan para tareas de 15 a 60 minutos, en las que una spec formal sería excesiva. El plan se queda en el chat y no entra ningún archivo de spec en el repositorio; es decir, tampoco habrá un documento con el que revisar después el código. Para una tarea pequeña no es un problema: ese pull request lo revisas como siempre, mirando el diff y la descripción.

Para corregir errores, Spec Kit propone un camino aparte: el diagnóstico, la corrección y la verificación se mantienen separados, y una corrección sin verificar no cuenta como éxito. Kiro, por su parte, considera suficiente un arreglo rápido en el chat para erratas o cambios de una línea bien entendidos.

¿Cómo se separan el código y la spec con el tiempo?

La mayoría de los participantes del estudio de Carnegie Mellon contó que el código y la spec acabaron separándose. Los investigadores distinguen dos caminos y les ponen nombre: implementation drift (el código se desvía de la spec) y spec decay (la spec se queda obsoleta). Su ejemplo es cuánto tiempo sigue abierta una sesión:

En los dos casos el código dice 60 minutos y la spec, 30 minutos; una herramienta que compara código y spec ve los dos casos igual. Lo que marca la diferencia es cuál de los dos está mal. El estudio lo dice con claridad: las revisiones programadas con agentes o las pruebas de extremo a extremo en la CI pueden mostrar que el código y la spec no coinciden, pero no cuál de los dos está mal. Esa decisión la toma quien es dueño de la intención.

El implementation drift ocurre en el pull request en el que se escribe el código. El estudio recomienda a quienes crean herramientas convertir los criterios de aceptación en pruebas que el agente tenga que superar; que Kiro genere tests property-based a partir de sus requisitos EARS es un ejemplo. El spec decay ocurre después, en otro pull request: un cambio que modifica un comportamiento no toca la spec que lo describe. El estudio lo ve sobre todo en las specs vivas (living specs), cuando un cambio afecta también a un comportamiento que describen otras specs.

Los controles que traen las herramientas funcionan al final del trabajo. El paso converge de Spec Kit compara el código con la spec, el plan y las tareas de esa funcionalidad y solo añade las tareas que faltan; tras el resultado «Converged», la documentación te remite a la revisión o a abrir un pull request. El paso verify de OpenSpec compara el código con los documentos del cambio antes de archivar y solo informa. En Kiro puedes preguntar en el chat, con #spec, si el trabajo cumple sus criterios de aceptación, y hacer que Sync Files marque las tareas completadas.

Todos estos controles los ejecuta el mismo agente de programación que hizo el trabajo; la documentación que leímos no dice si el control debería hacerlo otro modelo o hacerse en una sesión aparte. El estudio también escribe que no pudo determinar si alguna de estas herramientas comprueba, una vez terminado el trabajo, que la spec y el código siguen coincidiendo. La documentación de Spec Kit le pone nombre al riesgo: «The main risk is silent divergence.»

¿Cómo se revisa el código según su spec?

Los pasos generales para revisar un pull request escrito por IA los contamos en otro artículo: ¿hace lo que dice la descripción?, ¿qué cambió que no debía?, ¿las pruebas comprueban algo de verdad? En un equipo que trabaja con specs se añaden algunas preguntas propias de la spec:

La spec y el código deben ir en el mismo pull request. Spec Kit dice que se revisen juntos el código y los cambios en los documentos, y OpenSpec, que la carpeta del cambio vaya en el commit junto con el código. Si la spec llega en otro pull request, o no llega, no puedes ver si la intención cambió.

Lee primero el diff de la spec. OpenSpec dice que, al revisar el plan, lo que más vale la pena leer es specs/, y hace una sola pregunta: «Would you accept these requirements as done?» En el pull request le haces esa pregunta al diff: qué criterio de aceptación se añadió, cuál cambió, cuál se borró. El estudio también recomienda a las herramientas mostrar los cambios en los criterios de aceptación como un diff. El código lo lees según la nueva spec que trae el pull request; el cambio en la spec, comparándolo con su versión anterior en la rama de destino. Si el código se ajusta a la spec lo pueden comprobar las pruebas y las herramientas; si el cambio en la spec es correcto solo lo puede responder el dueño de la intención.

Los criterios de aceptación debe escribirlos o aprobarlos una persona. El estudio lo recomienda sin rodeos: «Practitioners should write or approve acceptance criteria even when agents produce the rest.» No hace falta leer toda la spec con el mismo cuidado; según el estudio, la definición del problema, las decisiones clave y los criterios de aceptación expresan la intención, y el resto es contexto para el agente. Los participantes que fijaban los criterios de aceptación o repasaban las pruebas del agente no mencionaron la verificación como un problema; los investigadores añaden que no pueden demostrar que eso evitara defectos.

Cada criterio debe tener su prueba. Una casilla marcada en la lista de tareas no es una prueba: en el ejemplo de Zaninotto, el agente cerró la tarea de verificación sin escribir ninguna prueba. Empareja cada criterio de aceptación con una prueba. Un criterio sin prueba es una promesa sin nada detrás en el código.

El control no debe hacerlo el agente que hizo el trabajo. Según el estudio, cuando un solo agente escribe la spec, el código y las pruebas, un solo malentendido puede pasar a los tres; por eso algunos participantes dicen «an agent must not review its own implementation». Spec Kit pone el mismo límite para sus propias checklists: el paso de implementación no debe aprobarlas por su cuenta. El estudio también dice lo que cuesta dejar la revisión de la spec por completo en manos de un agente: «Delegating spec review to an agent removes the one point where a person decides what the system should do.»

Mira si se rompió otra spec. El spec decay suele empezar aquí. Según el estudio, un agente que cambia una funcionalidad puede añadir un comportamiento que cumple la tarea del momento y pasa sus pruebas, pero que incumple una restricción de una spec más antigua. Si hay otras specs que describen el comportamiento que cambió, también hay que actualizarlas en el mismo pull request.

En el registro de los repositorios de código abierto, las personas apenas aparecen en estos pasos. En la muestra de 266 repositorios del estudio, el 98,3 % de los 36.888 archivos de spec con historial registrado tiene un solo autor, y los bots escribieron el 68,5 % de los 1.731 comentarios en línea sobre specs. En palabras de los investigadores, el segundo lector de una spec, si lo hay, suele ser un bot. Estas cifras no muestran con cuánto cuidado leen las personas las specs ni si la revisión se hace en otro sitio; solo muestran que hay poca participación humana registrada.

¿Qué ve de la spec una herramienta de revisión?

diffox es una herramienta de revisión de código formada por 17 agentes especializados. No lee las carpetas de specs (specs/, .kiro/specs/, openspec/); lleva dos textos a la revisión. El primero es el archivo de reglas de la raíz del repositorio: primero busca AGENTS.md y, si no está, CLAUDE.md. No lo lee de la rama del propio pull request, sino de la rama en la que se va a hacer el merge, tal como estaba en el punto del que salió la rama; por eso, un pull request que cambia el archivo de reglas se revisa con las reglas antiguas hasta que se hace el merge.

diffox solo toma del archivo de reglas las frases que expresan una obligación (como «must», «never», «debe», «nunca») y se las da a los agentes de la revisión como las reglas que deciden qué cuenta como error. Uno de los agentes, House Rules Agent, busca entre las líneas cambiadas la que incumple alguna de estas reglas y no se inventa reglas que no estén en la lista. El segundo texto es la descripción del pull request: también entra en el contexto que leen los agentes.

Para un equipo que trabaja con specs, esto significa que las obligaciones que quieres comprobar en cada pull request tienen que estar en el archivo de reglas. Una frase como «Every database migration must include a rollback plan.», del ejemplo de constitution que da Spec Kit para proyectos existentes, se usa como regla en la revisión si está en el archivo de reglas; el archivo de constitution de Spec Kit en .specify/memory/, en cambio, diffox no lo lee. Escribe también en la descripción del pull request qué spec implementaste y qué criterios de aceptación cambiaron; esa misma descripción la lee la persona que hace la revisión.

¿Por dónde empezar en tu proyecto?

En lugar de extender el método a todo el repositorio de golpe, empieza por poco:

1. Elige una sola funcionalidad grande. Una funcionalidad nueva con una intención clara y en la que un error salga caro. Las correcciones de errores y las tareas pequeñas, sigue haciéndolas como siempre.
2. Escribe tú los criterios de aceptación o apruébalos uno a uno. El resto lo puede escribir el agente. Un patrón como EARS o WHEN/THEN facilita convertir un criterio en una prueba.
3. Decide desde el principio cómo vivirá la spec. Spec Kit enumera tres modelos y no hace ninguno el predeterminado: flow-back, en el que todos los documentos pueden actualizarse entre sí; flow-forward, en el que cada cambio abre una carpeta nueva; y living spec, en el que la spec es la única fuente. Escribe el modelo elegido en la constitution o en las notas de incorporación del equipo.
4. Envía la spec y el código en el mismo pull request. Empieza la revisión por el diff de la spec.
5. Que el control lo haga otra mirada. El resultado de converge o verify del agente que hizo el trabajo es un punto de partida; los criterios de aceptación y el diff de la spec también tiene que mirarlos una persona.

Pasado un tiempo, fíjate en dos cosas: si las specs siguen cambiando junto con el código y adónde se va el tiempo de revisión. El criterio de Kretz es sencillo: si la spec va por detrás del código, ya no es la fuente de verdad, sino documentación.