Spec Driven Development: qué es y cómo aplicarlo con agentes de IA

Pedir a un agente de IA «añade autenticación» puede producir una primera versión de código en minutos. Pero también le obliga a adivinar decisiones que no estaban en la petición: qué proveedor usar, dónde guardar la sesión, cómo tratar los enlaces caducados, qué reglas de seguridad respetar o cómo probar el resultado. Spec Driven Development (SDD) propone cambiar el punto de partida: acordar una especificación antes de implementar.

En este enfoque, la especificación no es documentación que se redacta al final. Es un artefacto versionado que explica qué se construye, por qué, cuáles son sus límites y cómo se comprobará. Sirve a producto, al equipo de ingeniería y al agente que ejecuta el trabajo. El código sigue siendo importante, pero deja de ser el único lugar donde vive la intención.

¿Qué es Spec Driven Development?

Spec Driven Development, o desarrollo guiado por especificaciones, es una forma de trabajar en la que la especificación precede y dirige al código. Antes de abrir un editor o lanzar una tarea a un agente, se describe el cambio con el detalle suficiente para tomar decisiones y validar el resultado.

Una buena definición práctica es esta:

No es una metodología cerrada ni sinónimo de documentación extensa. Tampoco sustituye a Agile, TDD o BDD. SDD aporta el marco de un cambio; TDD puede asegurar el comportamiento de una unidad de código y BDD puede expresar escenarios de negocio de extremo a extremo. En un flujo maduro, las tres prácticas se complementan.

La diferencia cobra fuerza con los agentes de IA. Un prompt vago deja que el modelo complete huecos sobre arquitectura, reglas de negocio y casos de error. Una spec reduce esa ambigüedad y ofrece una referencia persistente que se puede revisar en una pull request.

Por qué SDD es útil al programar con IA

Los agentes pueden explorar un repositorio, modificar varios archivos, crear pruebas y ejecutar comandos. Esa capacidad acelera la implementación, pero no convierte una petición ambigua en un requisito correcto. Si el contexto solo existe en el historial de chat, puede perderse entre sesiones o interpretarse de forma distinta por cada persona y cada agente.

La spec funciona como un contrato de trabajo. Deja claro lo que debe suceder, lo que no debe cambiar y qué evidencia hace falta para considerar la tarea terminada. Así, la revisión humana puede empezar por las decisiones y los criterios de aceptación, no únicamente por cada línea generada.

Esto no vuelve determinista a un modelo ni elimina el code review. Lo que hace es disminuir el espacio en el que el agente tiene que improvisar. La documentación oficial de OpenSpec describe precisamente una capa ligera para acordar qué construir antes de escribir código; GitHub Spec Kit plantea un ciclo de principios, especificación, plan, tareas, implementación y convergencia.

Qué debe incluir una especificación útil

La mejor spec no es la más larga, sino la que permite tomar las decisiones necesarias sin imponer detalles accidentales de implementación. Para una funcionalidad de tamaño medio, conviene incluir al menos estas piezas:

• Problema y objetivo: quién tiene el problema y qué resultado se quiere conseguir.
• Alcance: comportamiento incluido y lo que queda explícitamente fuera.
• Requisitos y criterios de aceptación: reglas observables, preferiblemente con escenarios concretos.
• Restricciones: seguridad, rendimiento, compatibilidad, datos sensibles, APIs existentes o decisiones que no deben alterarse.
• Casos límite y errores: qué ocurre con datos vacíos, permisos insuficientes, reintentos o fallos de red.
• Plan y validación: áreas afectadas, tareas y pruebas que deben pasar.

Una distinción importante: la spec define el qué y el porqué; el diseño técnico explica el cómo. En ocasiones ambos documentos serán breves; en un cambio con impacto arquitectónico conviene separarlos para poder discutir el comportamiento sin confundirlo con una librería concreta.

Ejemplo: recuperación de contraseña

«Añade recuperación de contraseña» no permite saber si el resultado es correcto. Una especificación inicial podría ser:

La spec no dicta todavía el nombre de cada función. Sin embargo, evita que el agente elija un comportamiento inseguro o incompatible por falta de información.

El ciclo de trabajo: de la idea a una implementación verificable

Un ciclo SDD puede ser ligero. La clave es que haya una pausa explícita entre entender el cambio y modificar el código.

1. Explorar y delimitar. Convertir la petición de negocio en una hipótesis de cambio. Revisar código, usuarios afectados, datos y restricciones.
2. Especificar. Escribir requisitos, escenarios, no objetivos y criterios de aceptación. Resolver ambigüedades con la persona responsable antes de implementar.
3. Diseñar y planificar. Identificar módulos afectados, decisiones técnicas, riesgos y tareas. Este es el buen momento para que un agente proponga alternativas; no para que elija en silencio.
4. Implementar. Ejecutar tareas pequeñas y trazables contra la spec aprobada.
5. Verificar. Ejecutar tests, análisis estático, build y comprobaciones manuales relevantes. Comparar el resultado con los criterios, no solo con que «compile».
6. Actualizar y archivar. Si cambió el comportamiento del sistema, actualizar la documentación viva. Conservar la propuesta y las decisiones facilita mantenimiento, auditoría y cambios futuros.

El flujo no debe interpretarse como una cascada. Si durante la implementación aparece un requisito nuevo, se corrige la spec, se revisa el impacto y se continúa. La trazabilidad es más valiosa que fingir que el plan inicial era perfecto.

Especificaciones de sistema y de cambio

En proyectos con agentes conviene separar dos niveles de contexto:

El primer nivel puede vivir en AGENTS.md, CONTRIBUTING.md, una constitución de proyecto o documentación por dominios. El segundo debe estar cerca del cambio y bajo control de versiones. Sin reglas de sistema, un agente puede entregar una feature que funciona pero rompe patrones del repositorio; sin una spec de cambio, tendrá reglas pero no sabrá cuál es el resultado esperado.

OpenSpec y GitHub Spec Kit: dos formas de empezar

No es obligatorio adoptar una herramienta para practicar SDD: una carpeta de Markdown bien mantenida puede ser suficiente. Las herramientas ayudan cuando se quiere repetir el flujo y hacerlo visible para todo el equipo.

OpenSpec organiza el trabajo en especificaciones del sistema y carpetas de cambio. Habitualmente cada cambio contiene una propuesta, especificaciones incrementales, un diseño y una lista de tareas. Su guía oficial propone explorar una idea o crear una propuesta antes de aplicar cambios al código.

GitHub Spec Kit plantea una secuencia explícita: definir principios de proyecto, especificar el qué y el porqué, planificar, descomponer en tareas, implementar y converger el resultado contra los artefactos. Es útil como referencia para equipos que desean institucionalizar ese ciclo.

La elección no es una cuestión de marca. Empieza por el grado de estructura que el equipo pueda sostener. Para una feature pequeña, una spec de una página y un checklist de validación pueden ser suficientes. Para una modificación que afecta varios servicios, datos personales o un contrato público, el coste de una propuesta más completa suele ser mucho menor que el de corregir malentendidos después.

Cómo introducir SDD sin crear burocracia

1. Elige una funcionalidad de riesgo medio. Evita tanto el cambio de una línea como la migración más compleja del producto.
2. Escribe una spec corta antes de pedir código. Empieza con objetivo, alcance, escenarios, restricciones y validación.
3. Revisa el plan antes de ejecutar. Pide al agente que identifique archivos afectados, dudas y riesgos. Responde a las dudas que cambien el alcance.
4. Convierte la definición de terminado en comandos. Por ejemplo: npm run lint, npm test, npm run build y una prueba manual definida.
5. Mide el trabajo de vuelta. No solo el tiempo de la primera versión: revisiones, regresiones, aclaraciones y cambios posteriores a QA.

La prueba de que una spec sirve no es que genere muchos archivos Markdown. Es que reduce decisiones reabiertas, hace más clara una revisión y deja el sistema mejor explicado para el siguiente cambio.

Errores frecuentes

Confundir especificar con dictar cada línea

Una spec que obliga a copiar una implementación exacta no aprovecha el conocimiento técnico del equipo ni del agente. Define invariantes, interfaces, resultados y restricciones; deja libertad razonable en los detalles que no afectan al contrato.

Usar SDD para cualquier ajuste minúsculo

Un typo o una modificación trivial no necesita una propuesta formal. La estructura debe ser proporcional al riesgo, al alcance y a la dificultad de revertir el cambio.

Dejar la spec fuera de Git

Una nota privada o un hilo de chat no es una fuente de verdad compartida. Si la especificación importa para entender y mantener el software, debe versionarse junto al código o estar vinculada de forma inequívoca a él.

Dar por bueno el código generado sin evidencia

Una especificación aclara la intención, pero no demuestra que la implementación sea segura ni correcta. Tests, revisión, observabilidad y despliegues graduales siguen siendo necesarios.

Preguntas frecuentes sobre Spec Driven Development

¿SDD sustituye a TDD o BDD?

No. SDD sitúa el cambio en su contexto de producto y arquitectura. TDD puede seguir guiando la implementación de componentes y BDD puede expresar escenarios compartidos con negocio. Son capas complementarias.

¿Es necesario usar IA para aplicar SDD?

No. Especificar antes de implementar es una práctica anterior a los LLM. La IA ha hecho que sea más urgente, porque multiplica la velocidad con la que un requisito incompleto puede convertirse en código.

¿Cuándo merece la pena?

Especialmente en funcionalidades con varias reglas de negocio, riesgos de seguridad, integraciones, cambios entre equipos o mantenimiento de un repositorio grande. Para tareas muy pequeñas, basta con una descripción concisa y criterios claros.

¿Qué revisa una persona antes de aprobar?

La intención, el alcance, los casos límite, las decisiones técnicas relevantes y la evidencia de validación. Un agente puede preparar gran parte del material, pero la responsabilidad sobre el cambio sigue siendo del equipo.

Conclusión

Spec Driven Development no promete que un agente de IA acierte siempre. Propone algo más útil: convertir una intención difusa en un contrato que se puede discutir, ejecutar y verificar. Cuanto más autónomo sea el agente, más importante será tener claros el objetivo, los límites y la evidencia requerida.

El mejor primer paso no es instalar una herramienta ni documentar todo el producto. Es tomar el siguiente cambio relevante, escribir una spec breve y comprobar si el equipo vuelve menos veces atrás. Si la respuesta es sí, ya existe una base sólida para ampliar el enfoque.