Serie: Spec Driven Development (SDD)
- Spec Driven Development: el antídoto al vibe coding
- OpenSpec y el desarrollo guiado por especificaciones: de una imagen a código funcional en minutos
- De prototipo a producción: cómo convertimos capturas de Lovable en una app Angular + FastAPI con IA
- SDD a lo largo del ciclo de vida: del PRD a los tests, con la IA de copiloto (este artículo)
Los posts anteriores de esta serie explicaron qué es el Spec Driven Development y cómo funciona en un cambio concreto. Este aborda una pregunta diferente: ¿qué pasa cuando el proyecto no es un botón de exportar a Excel, sino una aplicación entera? La respuesta corta: el SDD escala. Y cuando escala, la diferencia entre tener un procedimiento establecido y no tenerlo se mide en semanas de retrabajo.
El problema que aparece cuando el proyecto crece
Con un cambio pequeño, el caos se nota poco. Tienes la feature en la cabeza, le das contexto al agente y, si hay suerte, funciona al primer intento. Con un proyecto de verdad —modelo de datos, backend, frontend, tests, integraciones— el caos se acumula. El agente implementa algo en la fase 3 que contradice una decisión de la fase 1. El frontend asume una estructura de API que el backend nunca tuvo. Los tests verifican una especificación que cambió tres veces sin que nadie lo escribiera en ningún sitio. El problema no es la IA. Es la ausencia de un proceso.
Sin especificaciones, el proyecto no tiene memoria. Y un proyecto sin memoria está condenado a repetir sus propios errores.
El PRD: el contrato antes del código
Todo proyecto guiado por especificaciones empieza por el mismo sitio: el PRD (Product Requirements Document). No tiene que ser un documento de 80 páginas. Tiene que responder tres preguntas con precisión: ¿qué hay que construir? (alcance, módulos, roles de usuario), ¿por qué? (el problema que resuelve y el valor que aporta) y ¿cómo se verifica? (los criterios de aceptación de cada funcionalidad principal). Sin ese PRD, cada agente trabaja con una versión diferente del proyecto que tiene en la cabeza —o en el chat, que viene a ser lo mismo.
En proyectos con metodologías más estructuradas como BMAD (Be My AI Developer), el PRD es el input de un arquitecto de IA que genera un plan de proyecto completo: épicas, historias de usuario, criterios de aceptación formales y dependencias entre fases. El resultado es exhaustivo y de alta calidad, pero la curva de aprendizaje es pronunciada y el overhead puede ser excesivo para equipos pequeños o proyectos medianos. Para proyectos de tamaño moderado, OpenSpec ofrece un equilibrio más práctico: el PRD se traduce directamente en una carpeta de especificaciones con cambios ordenados y secuenciados, sin necesidad de orquestar múltiples agentes especializados.
Los artefactos intermedios: el hilo de Ariadna del proyecto
La diferencia real entre SDD y el desarrollo sin disciplina no está en el documento inicial. Está en los artefactos intermedios: los ficheros Markdown que se generan entre el PRD y el código, y que actúan como el hilo conductor de todo el proceso. Cada cambio significativo genera al menos cuatro.
1. Propuesta — el «por qué». Describe el problema a resolver, el contexto actual y el impacto esperado. Es el momento de cuestionar si el cambio tiene sentido antes de invertir tiempo en diseñarlo.
2. Diseño técnico — el «cómo». Documenta las decisiones de arquitectura con sus alternativas descartadas. ¿Por qué esta librería y no aquella? ¿Por qué este patrón y no el otro? Es la parte más infrautilizada del proceso y la que más valor aporta a largo plazo: dentro de seis meses, alguien del equipo entenderá por qué se tomó esa decisión sin excavar en el historial de commits.
3. Especificaciones — el «qué exactamente». Requisitos formales en formato WHEN/THEN. Cada uno es un criterio de aceptación y, potencialmente, un caso de test. Sin ambigüedad. Sin margen para interpretaciones.
4. Tareas — el desglose ejecutable. La especificación traducida a unidades de trabajo atómicas con checkbox. Cada tarea es completable en minutos, no en horas. Cuando el agente trabaja sobre tareas atómicas, el output es predecible y verificable.
Estos artefactos no son documentación que se escribe después del desarrollo. Son el proceso mismo. Y esa diferencia lo cambia todo.
Cómo el SDD estructura todo el ciclo de vida
Diseño y maquetación
Cuando el diseñador entrega una captura o un Figma, el primer paso no es abrir el editor. Es generar la propuesta: ¿qué entidades implica este diseño? ¿Qué estados tiene cada componente? ¿Qué reglas de negocio están implícitas en los flujos? Con SDD, ese análisis queda escrito en un fichero Markdown antes de que el agente genere una sola línea de código. El diseñador y el desarrollador se ponen de acuerdo sobre el modelo, no sobre el pixel.
Desarrollo backend
El diseño técnico de cada endpoint documenta el contrato de la API antes de implementarla: nombre, método, parámetros, respuesta esperada, códigos de error. Ese contrato es exactamente lo que necesita el agente de backend para implementar sin adivinar, y exactamente lo que necesita el frontend para construir sus mocks sin esperar. El resultado: backend y frontend pueden desarrollarse en paralelo sobre la misma especificación. Cuando llega el momento de conectarlos, las discrepancias son mínimas porque ambos partieron del mismo documento.
Desarrollo frontend
El componente más complejo de validar en frontend es el comportamiento: cuándo está deshabilitado un botón, qué pasa si la llamada falla, cómo se comporta el formulario ante entradas inválidas. Las specs en formato WHEN/THEN definen exactamente esos casos antes de que el componente exista. Cuando el agente implementa el componente, las specs son su guía. Cuando otro agente genera los tests, las specs son su fuente de verdad. No hay interpretación. No hay suposiciones.
Testing
Aquí es donde el SDD se amortiza de la forma más visible. Los escenarios WHEN/THEN de las especificaciones son, literalmente, casos de test. La cobertura no es una métrica que se persigue al final del desarrollo: es una consecuencia natural del proceso. En el proyecto recientemente desarrollado —descrito con detalle en el artículo anterior de esta serie— 88 tests de backend y 1.035 tests de frontend no nacieron de una decisión de «vamos a escribir tests». Nacieron de especificaciones que definían los criterios de aceptación de cada funcionalidad. Los tests fueron la traducción directa de esas specs al lenguaje de la máquina.
Documentación y cierre de fase
El último artefacto del ciclo es la documentación de lo que se ha construido. No lo que se planeó construir: lo que realmente se construyó, incluyendo las decisiones que cambiaron sobre la marcha y por qué. Ese documento de cierre es lo que permite verificar que los objetivos de la fase se han cumplido, es la base para el onboarding de cualquier persona nueva y es la fuente de verdad para el agente en la siguiente fase.
La documentación generada tras cada fase no es un trámite. Es la memoria del proyecto. Sin ella, cada nueva fase empieza desde cero.
BMAD vs OpenSpec: cuándo usar cada uno
La elección del framework depende principalmente del tamaño del proyecto y de la tolerancia al proceso formal del equipo.
| BMAD | OpenSpec | |
|---|---|---|
| Ideal para | Proyectos grandes y complejos | Proyectos medianos o equipos ágiles |
| Modelo | Multi-agente (arquitecto, analista, dev, QA) | Agente único con flujo secuencial |
| Setup | 20-30 minutos, varios ficheros de configuración | npm install -g openspec, listo |
| Tamaño de specs | Exhaustivo (800+ líneas por épica) | Conciso (~250 líneas por cambio) |
| Flexibilidad | Fases rígidas y bien definidas | Cualquier artefacto modificable en cualquier momento |
| Curva de aprendizaje | Pronunciada | Suave |
| Mejor combinación | Claude Code o Cursor en proyectos enterprise | Cursor o cualquier IDE con IA |
BMAD brilla cuando la complejidad del proyecto justifica el overhead: sistemas con muchas integraciones, equipos distribuidos, requisitos regulatorios que obligan a tener trazabilidad completa de las decisiones. OpenSpec brilla cuando necesitas rigor sin fricción: el flujo propuesta → diseño → specs → tareas cubre el 90% de los casos con el 20% del esfuerzo de configuración, y su diseño para proyectos existentes —no solo para arranques desde cero— lo hace especialmente útil en el día a día de un equipo que ya tiene una base de código en marcha.
Lo que de verdad aporta tener un procedimiento
Más allá de las herramientas concretas, el SDD aporta algo que ningún framework puede darte por sí solo: un procedimiento compartido. Un conjunto de pasos que todo el equipo conoce, en el que cualquier persona puede incorporarse en cualquier punto y entender qué está pasando y por qué. Sin un procedimiento, la IA produce código más rápido de lo que el equipo puede verificar que es correcto. Con un procedimiento, cada línea de código tiene una especificación detrás que la justifica y un criterio de aceptación que la valida.
La diferencia no se nota en la primera semana. Se nota en la semana doce, cuando hay que modificar algo que se construyó en la semana dos y resulta que alguien escribió exactamente por qué se hizo así.
Las especificaciones son la diferencia entre un proyecto que crece de forma controlada y uno que crece de forma orgánica. Lo orgánico es bonito en los jardines. En el software, es deuda técnica.
¿Aplicaís alguna variante de SDD en vuestros proyectos? ¿Qué habéis encontrado que funciona y qué no? Lo leemos en los comentarios.
