Introducción a Spec-Driven Development

El problema del vibe coding

Los agentes de código IA han transformado la velocidad a la que se puede construir software. Herramientas como Claude Code, GitHub Copilot, Cursor o Gemini CLI permiten describir en lenguaje natural lo que se necesita y obtener implementaciones funcionales en minutos. Esta forma de trabajar, conocida como vibe coding, resulta atractiva por su inmediatez: describes tu idea, el agente genera código, revisas, ajustas y repites.

Sin embargo, esta agilidad tiene un coste que se manifiesta a medida que el proyecto crece. Sin especificaciones explícitas, el código se convierte en la especificación de facto del proyecto. Las decisiones técnicas quedan implícitas, dispersas entre archivos y commits. Los requisitos de negocio viven en hilos de Slack, correos electrónicos o en la cabeza de quien los definió. Cuando un nuevo miembro se incorpora al equipo o cuando hay que modificar una funcionalidad, nadie puede responder con certeza a preguntas como "por qué se eligió esta arquitectura" o "qué requisitos cubre este módulo".

El vibe coding optimiza la velocidad de escritura de código, pero traslada el coste a la fase de depuración, mantenimiento y evolución del proyecto.

Este fenómeno se conoce como intent-to-implementation drift: la desviación progresiva entre lo que el equipo pretendía construir y lo que realmente se ha construido. Con vibe coding, esta desviación se gestiona de forma reactiva. Se detecta cuando algo falla, cuando un test no pasa o cuando un usuario reporta un comportamiento inesperado. A esas alturas, corregir el rumbo puede implicar reescribir componentes enteros.

El problema no es la capacidad del agente IA. Los modelos de lenguaje son excepcionales reconociendo patrones y generando código. El problema es la calidad del contexto que reciben. Un prompt vago como "añade notificaciones a la app" obliga al modelo a asumir miles de decisiones que nadie ha tomado explícitamente: el sistema de transporte, la persistencia, la granularidad de las preferencias del usuario, la integración con servicios externos. Algunas de esas suposiciones serán correctas, otras no. Y las incorrectas suelen descubrirse cuando ya es caro corregirlas.

Qué es Spec-Driven Development

Spec-Driven Development (SDD) es una metodología que invierte la relación tradicional entre especificaciones y código. En lugar de tratar las especificaciones como documentos prescindibles que se redactan al principio y se abandonan una vez que comienza la implementación, SDD las convierte en artefactos ejecutables que generan directamente las implementaciones.

Esta inversión es la idea central de SDD: las especificaciones no guían el código, las especificaciones generan el código.

flowchart LR
    subgraph Tradicional["Enfoque tradicional"]
        direction LR
        A1["Requisitos"] --> A2["Documento<br>(se abandona)"]
        A2 --> A3["Código"]
    end
    subgraph SDD["Spec-Driven Development"]
        direction LR
        B1["Requisitos"] --> B2["Especificación<br>(artefacto vivo)"]
        B2 --> B3["Código generado"]
        B3 -->|Feedback| B2
    end

En el enfoque tradicional, los requisitos se documentan, se entregan al equipo de desarrollo y el documento queda obsoleto en cuestión de días. En SDD, la especificación es un documento vivo que evoluciona junto con el código. Cuando cambian los requisitos, se actualiza la especificación y se regenera la implementación. La especificación mantiene su rol como fuente de verdad durante todo el ciclo de vida del proyecto.

SDD no es planificación waterfall disfrazada. No requiere documentar cada detalle antes de escribir una línea de código. Es un proceso iterativo y ligero donde se capturan las decisiones fundamentales (el "qué" y el "por qué") antes de que el agente IA se encargue del "cómo". La diferencia con el vibe coding no es la velocidad, sino la trazabilidad: cada decisión técnica queda registrada y puede revisarse, cuestionarse o modificarse sin perder contexto.

SDD trata las especificaciones como control de versiones para el pensamiento del equipo: las decisiones arquitectónicas, los requisitos de negocio y las restricciones técnicas quedan documentadas y evolucionan de forma controlada.

La inversión de poder

En el desarrollo de software convencional, el poder reside en el código. Las especificaciones son un paso previo que se tolera por necesidad organizativa, pero la "realidad" del proyecto vive en los archivos fuente. Si la especificación dice una cosa y el código hace otra, se asume que el código tiene razón.

SDD invierte esta dinámica. La especificación se convierte en la fuente de verdad del proyecto. El código es un artefacto derivado, generado a partir de la especificación y validado contra ella. Si el código diverge de la especificación, es el código el que debe corregirse.

Esta inversión tiene implicaciones prácticas:

• Cambiar de dirección es barato: modificar una especificación y regenerar el código es significativamente más rápido que reescribir implementaciones manualmente. Las decisiones se toman a nivel de especificación, donde cambiar de opinión cuesta minutos, no sprints.

• Las suposiciones se hacen explícitas: en lugar de dejar que el agente IA asuma requisitos no declarados, SDD obliga a articularlos antes de la implementación. Esto reduce drásticamente el intent-to-implementation drift.

• La exploración se desbloquea: como la especificación está desacoplada del código, es posible generar múltiples implementaciones paralelas a partir de la misma spec. Se puede, por ejemplo, pedir al agente una versión en Python y otra en Go para comparar rendimiento, sin duplicar el esfuerzo de definición de requisitos.

• La revisión de código cambia de naturaleza: en lugar de revisar miles de líneas de implementación, el equipo puede revisar la especificación. Si la spec es correcta y el agente IA la implementa fielmente, la revisión de código se convierte en validación, no en descubrimiento.

De PRD a especificación ejecutable

Los equipos de producto llevan décadas escribiendo PRDs (Product Requirements Documents) que describen qué se va a construir. El problema histórico es que estos documentos eran artefactos estáticos que el equipo de ingeniería interpretaba libremente. SDD hereda la filosofía del PRD pero la hace ejecutable: la especificación no se interpreta, se ejecuta.

La diferencia fundamental es que un PRD tradicional dice "el usuario debe poder gestionar sus notificaciones" y deja la interpretación al equipo de desarrollo. Una especificación SDD define las user stories concretas, los criterios de aceptación medibles y los requisitos no funcionales, de forma que un agente IA pueda generar una implementación que cumpla exactamente lo especificado.

El flujo de trabajo SDD

SDD estructura el desarrollo en fases secuenciales, cada una con un objetivo claro y un punto de validación antes de avanzar a la siguiente. Este flujo garantiza que las decisiones se toman en el orden correcto: primero el "qué", después el "cómo", y finalmente la ejecución.

flowchart TB
    C["Constitución<br>Principios del proyecto"] --> S["Especificación<br>Qué construir y por qué"]
    S --> P["Planificación<br>Cómo construirlo"]
    P --> T["Tareas<br>Desglose ejecutable"]
    T --> I["Implementación<br>Ejecución por el agente IA"]
    I -->|Feedback| S

Las fases principales del flujo SDD son:

• Constitución: se establecen los principios inmutables del proyecto. Son las reglas de gobernanza que guían todas las decisiones posteriores: convenciones de código, restricciones tecnológicas, patrones arquitectónicos obligatorios. La constitución se define una vez y se actualiza de forma controlada.

• Especificación: se define qué construir y por qué, sin entrar en detalles técnicos. La especificación describe user stories, criterios de aceptación y requisitos no funcionales. No menciona frameworks, bases de datos ni lenguajes de programación.

• Planificación: se traducen los requisitos de negocio en decisiones técnicas. Aquí se elige el stack tecnológico, se define la arquitectura, se diseñan los contratos de API y el modelo de datos. El plan respeta los principios de la constitución.

• Tareas: el plan se descompone en unidades de trabajo accionables con dependencias explícitas, paths de archivos y checkpoints de validación. Cada tarea es lo suficientemente pequeña para que un agente IA la implemente y verifique de forma aislada.

• Implementación: el agente IA ejecuta las tareas siguiendo el orden definido. Cada tarea implementada se valida contra los criterios de la especificación original.

El flujo incluye otros pasos de refinamiento opcionales (clarify, analyze, checklist) que se verán más adelante.

Este flujo no es rígido. SDD permite iterar hacia atrás: si durante la planificación se descubre una ambigüedad en la especificación, se vuelve a la fase de especificación para resolverla. Si durante la implementación se identifica un problema con el plan, se ajusta el plan. La clave es que cada iteración queda registrada en los documentos de especificación, manteniendo la trazabilidad completa.

SDD frente a otras metodologías

SDD no reemplaza a otras metodologías de desarrollo, sino que las complementa en el contexto del trabajo con agentes IA.

| Aspecto | Vibe coding | TDD | SDD | |---|---|---|---| | Punto de partida | Prompt en lenguaje natural | Test que falla | Especificación estructurada | | Gestión del drift | Reactiva | Preventiva (a nivel de tests) | Preventiva (a nivel de requisitos) | | Fuente de verdad | El código | Los tests | La especificación | | Cuándo funciona mejor | Prototipos, exploración | Lógica de negocio, regresiones | Proyectos con equipos, producción | | Coste de cambio de dirección | Alto a escala | Medio | Bajo |

TDD (Test-Driven Development) y SDD comparten la filosofía de definir el comportamiento esperado antes de implementarlo. La diferencia es el nivel de abstracción: TDD opera a nivel de código (un test define el comportamiento de una función), mientras que SDD opera a nivel de requisitos (una especificación define el comportamiento de una funcionalidad completa). En la práctica, ambos enfoques son complementarios: una especificación SDD puede incluir como criterio de aceptación que los tests unitarios pasen.

Vibe coding sigue siendo válido para ciertos escenarios: prototipos rápidos, proyectos personales, exploraciones donde los requisitos son fluidos y el coste de reescritura es bajo. SDD brilla cuando el proyecto involucra múltiples personas, tiene requisitos de producción o necesita mantenerse a medio y largo plazo.

La clave no es elegir una metodología u otra de forma exclusiva, sino aplicar el nivel de estructura adecuado al contexto. Muchos equipos adoptan un enfoque híbrido: vibe coding para explorar ideas, SDD para llevarlas a producción.