Apariencia
La Guía Completa de Spec Driven Development (SDD)
A medida que los agentes AI se vuelven más capaces, ha emergido un problema fundamental: los agentes son rápidos, pero el trabajo es cada vez más difícil de controlar.
Un agente AI generará código con confianza independientemente de si ha entendido correctamente los requisitos. Tomará decisiones arquitectónicas sin saber qué decisiones se tomaron la semana pasada. Completará una fase de una feature mientras contradice silenciosamente el diseño de otra fase.
Spec Driven Development (SDD) es una metodología que aborda esto. Proporciona la capa de estructura que falta para que el desarrollo asistido por AI sea fiable a escala.
Qué es Spec Driven Development
SDD es una metodología de desarrollo de software donde las especificaciones estructuradas se crean y mantienen como artefactos de primera clase — antes de que empiece la codificación, no como una idea tardía.
Una spec en SDD no es un documento de requisitos tradicional. Es un artefacto vivo que:
- Define cómo se ve "hecho" en términos de criterios de aceptación específicos y verificables
- Captura las restricciones clave y las decisiones arquitectónicas
- Rastrea el estado de implementación conforme se construye la feature
- Sirve como fuente de verdad para los agentes AI que trabajan en la feature
La distinción crucial respecto a las specs tradicionales: las specs SDD están diseñadas para ser leídas por agentes AI, no solo por humanos. Están estructuradas para proporcionar el contexto que un agente necesita al inicio de cada sesión, y son verificables — puedes comprobar si la implementación coincide con la spec.
El Problema que SDD Resuelve
Para entender por qué importa SDD, considera qué pasa sin él.
Pérdida de contexto entre sesiones. Cada sesión AI empieza desde cero. Un agente que te ayudó a diseñar un sistema de autenticación ayer no tiene memoria de esas decisiones hoy. Sin una spec, o re-explicas todo (lento e inconsistente) o el agente inventa el contexto que no tiene (peligroso).
Spec drift. Incluso cuando una feature empieza correctamente, la implementación puede desviarse de la intención original conforme crece. Aparecen nuevos casos límite, diferentes agentes gestionan partes distintas, las pequeñas decisiones se acumulan. Sin una spec con la que comparar, el drift a menudo no se detecta hasta que la feature se lanza.
Conflictos entre agentes paralelos. Cuando varios agentes trabajan simultáneamente — uno en el frontend, otro en el backend, otro en los tests — toman decisiones de forma independiente. Sin specs compartidas, toman decisiones incompatibles. La interfaz que diseñó el agente frontend no coincide con lo que construyó el agente backend.
Scope creep sin visibilidad. Los agentes quieren ayudar. Cuando encuentran una ambigüedad, la resuelven. Cuando ven una mejora adyacente, la hacen. Sin specs, este comportamiento útil es invisible hasta que revisas el código — y para entonces, la feature puede haber crecido mucho más allá de lo que se pretendía.
SDD crea una fuente de verdad persistente y compartida que previene todos estos problemas.
Conceptos Fundamentales
Specs
Una spec es un documento estructurado que describe una unidad de trabajo — típicamente una historia de usuario o feature. En SDD, las specs viven en tu repositorio junto a tu código.
Una spec SDD bien formada contiene:
- Historia de usuario — quién necesita esto y por qué ("Como desarrollador, quiero...")
- Criterios de aceptación — condiciones específicas y verificables que definen "hecho"
- Restricciones — qué no debe hacer esta feature, límites, dependencias
- Decisiones técnicas — decisiones arquitectónicas que se han tomado y no deben revisarse
- Estado de implementación — qué criterios están completos, en progreso o pendientes
Criterios de Aceptación
Los criterios de aceptación son la parte más importante de una spec. Responden a la pregunta: "¿Cómo sabremos que esta feature está hecha?"
Los buenos criterios de aceptación son:
- Específicos — "Los resultados de búsqueda se actualizan en 200ms desde la tecla pulsada", no "La búsqueda es rápida"
- Verificables — puedes escribir un test (automatizado o manual) que verifica el criterio
- Completos — cubren el camino feliz, los casos de error y los casos límite
Los criterios de aceptación vagos son la causa raíz de la mayoría de fallos en SDD. Si un agente puede interpretar un criterio de varias maneras, elegirá la incorrecta.
Detección de Drift
La detección de drift es el proceso de comparar la implementación actual con la spec para identificar divergencias. En un flujo de trabajo SDD bien implementado, la detección de drift se ejecuta automáticamente — ya sea en CI/CD o como parte del flujo del agente.
Formas comunes de drift:
- Una feature se implementó, pero un criterio de aceptación específico nunca se verificó
- La implementación maneja un caso de forma diferente a como lo describe la spec
- La spec se actualizó, pero el código no
Detectar el drift pronto es mucho más barato que detectarlo en producción.
El Registro de Decisiones Técnicas
Más allá de la spec en sí, SDD fomenta mantener un registro ligero de decisiones arquitectónicas. Cuando tu equipo (o tus agentes AI) decide usar un patrón, estructura o librería concretos, esa decisión se registra.
Esto previene que la misma decisión se tome de forma diferente en distintas sesiones, y evita que los agentes "deshagan útilmente" decisiones que se tomaron deliberadamente.
El Flujo de Trabajo SDD
SDD sigue un ciclo de cinco pasos para cada feature:
1. SPEC → Escribe la historia de usuario y los criterios de aceptación
2. APROBAR → El humano revisa y aprueba la spec antes de empezar a codificar
3. IMPLEMENTAR → El agente implementa contra la spec
4. VALIDAR → Verifica la implementación contra los criterios de aceptación
5. MERGEAR → Integra cuando todos los criterios pasanPaso 1: Escribe la Spec
Antes de escribir ningún código, crea la spec. Incluye:
- La historia de usuario
- Todos los criterios de aceptación (apunta a la especificidad sobre la brevedad)
- Restricciones y dependencias conocidas
- Cualquier decisión arquitectónica que ya hayas tomado
La spec no necesita ser exhaustiva en esta fase — puedes refinarla — pero debe ser lo suficientemente clara como para que un agente AI pueda empezar a implementar sin necesitar inventar requisitos.
Paso 2: Aprueba la Spec
Este paso no es negociable en SDD. Un humano revisa la spec antes de que empiece la implementación.
La revisión responde tres preguntas:
- ¿La spec captura lo que realmente queremos construir?
- ¿Los criterios de aceptación son completos y suficientemente específicos?
- ¿Hay restricciones o decisiones que necesitemos añadir?
La aprobación es el contrato entre el humano y el agente AI. Sin ella, los agentes están adivinando los requisitos.
Paso 3: Implementa
Con una spec aprobada, empieza la implementación. El agente lee la spec al inicio de cada sesión y trabaja para satisfacer los criterios de aceptación.
En la práctica, esto significa:
- El agente referencia criterios específicos conforme trabaja ("Implementando criterio 3: el usuario puede filtrar por categoría")
- Cuando el agente tiene dudas, resuelve las ambigüedades de formas que se alinean con la spec
- El agente marca los criterios conforme los va completando
Paso 4: Valida
Después de la implementación, se verifica cada criterio de aceptación. Algunos se pueden verificar automáticamente (ejecutando tests), otros manualmente.
Este paso es donde se detecta el drift. Si la implementación no satisface un criterio, el trabajo no está hecho — independientemente de si el código "parece bien."
Paso 5: Mergea
Solo después de que todos los criterios estén verificados se mergea la feature. Este es un listón más alto que la revisión de código tradicional, que típicamente se centra en la calidad del código en lugar de en la corrección del comportamiento.
SDD vs Otras Metodologías
SDD vs TDD (Test Driven Development)
TDD y SDD son complementarios, no competidores.
TDD es sobre el ciclo de implementación: escribe un test que falla, escribe código para que pase, refactoriza. Opera a nivel de código.
SDD es sobre el ciclo de requisitos: escribe una spec, obtén aprobación, implementa, verifica contra la spec. Opera a nivel de feature.
En la práctica, las specs SDD informan los tests que usa TDD. Un criterio de aceptación como "los resultados de búsqueda se actualizan en 200ms" se convierte en un test de rendimiento. Las dos metodologías funcionan juntas de forma natural.
Para una comparación más profunda, ver SDD vs TDD: Por Qué el Spec Driven Development Cambia las Reglas.
SDD vs BDD (Behavior Driven Development)
BDD es la metodología más cercana a SDD. Ambas se centran en describir el comportamiento en lugar de la implementación, y ambas usan criterios de aceptación estructurados.
La diferencia clave: BDD se expresa típicamente en sintaxis formal Given/When/Then (Gherkin) y está diseñado para ejecutarse como tests. Los criterios de aceptación de SDD son más flexibles — no necesitan seguir una sintaxis específica y pueden describir comportamientos difíciles de automatizar.
SDD también tiene un enfoque más fuerte en el caso de uso de agentes AI — mantener a los agentes en spec entre sesiones es un desafío que BDD no aborda específicamente.
SDD vs Documentos de Spec Tradicionales
Los documentos de spec tradicionales (PRDs, specs funcionales) se escriben para humanos y a menudo se abandonan una vez que empieza el desarrollo. Son demasiado largos para compartir con agentes AI, demasiado vagos para la verificación automatizada y raramente se actualizan conforme evoluciona la feature.
Las specs SDD son más cortas, más estructuradas y diseñadas para mantenerse actuales. Están pensadas para ser leídas tanto por humanos como por agentes AI, y rastrean el estado de implementación para que siempre sepas dónde está la feature.
Herramientas para SDD
Planu
Planu es un servidor MCP que implementa el flujo de trabajo SDD completo como 32 tools enfocadas accesibles para cualquier agente AI. Gestiona:
- Crear y almacenar specs en un formato estructurado
- Compartir specs con agentes AI al inicio de cada sesión
- Rastrear el estado de implementación por criterio de aceptación
- Ejecutar detección de drift para detectar cuando la implementación se desvía de la spec
- Gestionar specs paralelas para prevenir conflictos entre agentes simultáneos
Planu es agnóstico al lenguaje — funciona con TypeScript, Python, Go, Rust, Java y cualquier otro lenguaje que use tu proyecto. Se integra con Claude Code, Cursor, Windsurf, Cline y cualquier otra herramienta AI compatible con MCP.
SDD Manual (Sin Herramientas)
SDD no requiere software especializado. Puedes implementar el flujo de trabajo central con:
- Archivos Markdown en tu repositorio para las specs
- Una plantilla compartida para los criterios de aceptación
- Una convención para marcar los criterios como hechos (p. ej., checkboxes)
- Checklists de revisión de código que verifican la implementación contra las specs
Así es como empieza la mayoría de equipos. La sobrecarga es baja y el valor es inmediato.
Primeros Pasos con SDD
Si empiezas desde cero, aquí hay una primera semana práctica:
Día 1: Escribe tu primera spec
Elige una feature que estás a punto de construir. Antes de escribir ningún código, escribe una spec breve:
- Historia de usuario en una frase
- 3-5 criterios de aceptación (sé específico)
- Cualquier restricción conocida
Días 2-3: Implementa contra la spec
Empieza cada sesión de agente AI compartiendo la spec. Referencia criterios específicos conforme trabajas. Nota cómo se comporta de forma diferente el agente cuando tiene criterios de aceptación claros frente a instrucciones vagas.
Día 4: Valida
Repasa cada criterio y verifica que está satisfecho. Casi con certeza encontrarás al menos uno que está incompleto o implementado de forma diferente a lo que se pretendía.
Día 5: Reflexiona
¿Qué funcionó? ¿Qué criterios de aceptación eran demasiado vagos? ¿Qué restricciones deberías haber especificado de antemano? Usa estas observaciones para mejorar la siguiente spec.
Usando Planu para automatizar esto
Si quieres el flujo de trabajo automatizado desde el primer día, instala Planu y usa create_spec para crear tu primera spec. La herramienta te guía a través de la estructura y almacena todo en un formato que tu agente AI puede leer directamente.
Errores Comunes
Criterios demasiado vagos. "La UI debe ser responsiva" no es un criterio útil. "El layout se renderiza correctamente a 320px, 768px y 1440px" sí lo es.
Saltarse el paso de aprobación. Cuando los desarrolladores se saltan la aprobación y van directamente de escribir specs a implementar, a menudo descubren que la spec estaba mal a mitad de la implementación. El paso de aprobación lo detecta pronto.
Specs que describen implementación en lugar de comportamiento. "Usa una función debounce con delay de 200ms" describe implementación. "Los resultados de búsqueda se actualizan no más de una vez cada 200ms de escritura del usuario" describe comportamiento. El segundo le da más flexibilidad al agente mientras especifica lo que importa.
No actualizar las specs cuando cambian los requisitos. Una spec que no refleja los requisitos actuales es peor que ninguna spec — activamente confunde a los agentes AI. Cuando cambian los requisitos, actualiza primero la spec, luego implementa.
Demasiados criterios por spec. Las specs con 30+ criterios de aceptación son difíciles de implementar en una sola sesión y difíciles de validar. Divide las features grandes en specs más pequeñas. Un buen objetivo es 5-15 criterios por spec.
Conclusión
SDD no hace el desarrollo con AI más lento — hace el desarrollo con AI fiable a escala. La inversión inicial en specs claras se recupera rápidamente cuando ya no estás depurando features que implementaron algo diferente a lo que se pretendía.
La metodología es deliberadamente simple: escribe cómo se ve "hecho" antes de empezar, apruébalo, impleméntalo, verifícalo. La complejidad que existe está en ejecutar estos pasos de forma consistente, especialmente bajo presión de lanzar rápido.
Empieza con una feature. Escribe una spec. Mira qué cambia.
Lecturas Adicionales
- SDD vs TDD: Por Qué el Spec Driven Development Cambia las Reglas — comparativa detallada
- Por Qué los Agentes AI Necesitan Specs — el problema en profundidad
- El Vibe Coding Mola Hasta Que Se Rompe — cuándo añadir estructura
- Primeros Pasos con Planu — implementa SDD con soporte de herramientas
- Guía de Flujo de Trabajo SDD — la implementación del flujo de trabajo SDD de Planu