Seguro que te suena esta escena. Abres tu editor de código inteligente, le tiras un prompt casual de tres líneas comentando por encima una nueva funcionalidad que necesitas, y en cinco segundos te quedas mirando la pantalla con cara de asombro mientras la IA te escupe doscientas líneas de código TypeScript impecable. Le das a aceptar con un chute de dopamina brutal. Sientes que vas diez veces más rápido. Todo parece ir como la seda.
Pero pasan dos semanas y el invento empieza a ratear. Esa velocidad inicial era un espejismo. Resulta que el agente tomó atajos que no viste, se saltó las reglas de arquitectura limpia que tanto te costó montar, dejó advertencias de compilación silenciosas y llenó el repositorio de pequeñas incoherencias lógicas. Intentas arreglarlo tirándole más prompts de "parche sobre parche", pero la IA empieza a tener amnesia, alucina y te toca meterle mano al código manualmente durante horas para deshacer el entuerto.
Acabas de chocar de frente contra el muro del "Vibe Coding" (programar por vibras o intuición).
Hoy vamos a hablar de por qué esta inercia de programar "por sensaciones" es insostenible si se está montando algo serio, y de cómo se aplica el Spec-Driven Development (SDD) en el día a día. No te lo tomes como otra moda metodológica aburrida; es el único chasis de gobernanza real que funciona cuando dejas que las IA metan mano en el código.
1. El Ferrari en el camino de cabras: Por qué el Vibe Coding te va a explotar en la cara
Una forma muy visual de entender la productividad con IA ahora mismo es pensar en la paradoja de comprarse un Ferrari y conducirlo por un camino de cabras lleno de barro. El motor es una bestia indomable, pero tu hora de llegada la va a decidir el estado del terreno.
El motor (los modelos de lenguaje) ha cambiado por completo, pero nuestras carreteras (cómo validamos, probamos y organizamos los repositorios) siguen siendo las de siempre. Programar "por vibras" consiste en pisar el acelerador a fondo sin asfaltar la carretera. Es un caos donde el desarrollador acepta cualquier código que "parezca funcionar" sin un contrato de diseño riguroso por detrás.
Esto genera tres dolores de cabeza reales que acaban por romper cualquier proyecto mediano:
- Deuda cognitiva y pérdida de control: El código no es solo sintaxis que compila, es el reflejo de un modelo de negocio que el equipo tiene que entender. Cuando un agente genera código a velocidad de vértigo, mete nuevas abstracciones, interfaces y términos a un ritmo que los humanos no podemos digerir. La base de código se vuelve gigante y compleja, mientras que el equipo entiende cada vez menos cómo funciona su propio sistema.
- Vulnerabilidades coladas sin querer: Fiarte de que una IA escribe código seguro por defecto es tener mucha fe. Los análisis de seguridad demuestran que más del 70% de las vulnerabilidades generadas por IA suelen ser de nivel crítico o bloqueante si no se supervisan. Dejar que la IA codifique libremente sin un arnés que controle lo que sube es, estadísticamente, jugar a la ruleta rusa con la producción.
- Velocidad de mentira: En proyectos reales, que piques código más rápido en tu pantalla no significa que el equipo entregue antes. Lo único que se consigue es llenar el repositorio de advertencias, código acoplado y complejidad ciclomática que luego alguien (probablemente nosotros mismos) tendrá que limpiar en el siguiente sprint de refactorización. En resumen: vas muy rápido, pero hacia el precipicio.
Para parar esta locura, hay que mover el control un paso a la izquierda. Tenemos que dejar de ser "picadores de teclas" interactivos y empezar a actuar como Ingenieros de Contratos. Y ahí es donde entra el SDD.
2. ¿Qué es Spec-Driven Development (SDD)?
El SDD aporta una bofetada de realidad que hace ver las cosas de otra forma: el código fuente ya no es el rey.
Durante décadas, hemos tratado el código como la "Única Fuente de Verdad" (SSOT). La documentación, los diagramas de arquitectura y las especificaciones eran meros papeles que escribíamos al principio con mucha ilusión y que luego tirábamos a la basura en cuanto el código real empezaba a desviarse.
En el SDD le damos la vuelta a la tortilla: las especificaciones en Markdown dejan de ser texto muerto y se convierten en contratos ejecutables de primera clase que gobiernan la implementación.
┌─────────────────────────────────────────────────────────────┐
│ El Flujo SDD │
├─────────────────────────────────────────────────────────────┤
│ │
│ Especificación Escrita (Contrato de Diseño en Markdown) │
│ │ │
│ ▼ │
│ Arnés de Agentes de IA ◄─── Restringidos por Gobernanza │
│ │ │
│ ▼ │
│ Código Fuente (Subproducto Efímero y Regenerable) │
│ │
└─────────────────────────────────────────────────────────────┘Bajo este enfoque, el código fuente pasa a ser un subproducto efímero, transitorio y continuamente regenerable. Si el comportamiento del sistema falla o tenemos que cambiar algo, la regla de oro es estricta: nunca tocamos el código a mano. Modificamos la especificación en Markdown, dejamos que el agente entienda el nuevo contrato y regeneramos la implementación completa.
3. Las tres altitudes del SDD (Cómo de profundo quieres llegar)
Esto del SDD no es blanco o negro. Se puede aplicar en diferentes niveles según lo que necesite el equipo y el tipo de proyecto que se tenga entre manos:
Altitud 1: Spec-First (Para empezar sin complicarte)
- La regla: La especificación es tu guía inicial.
- Cómo funciona: Escribes un archivo Markdown súper detallado explicando la lógica de negocio, las APIs y los casos de prueba que quieres antes de pedirle nada a la IA. El agente lee este archivo en una sesión limpia, te genera el código y listo. Una vez que el código está funcionando y en producción, suele dar igual si la especificación se queda desactualizada. Ha cumplido su papel de andamio.
- Cuándo usarlo: Si estás solo, para prototipos rápidos, refactorizaciones de una tarde o si quieres empezar a probar este flujo sin cambiar la forma de trabajar de todo tu equipo.
Altitud 2: Spec-Anchored (El estándar de producción)
- La regla: La especificación y el código coevolucionan y viven juntos en Git.
- Cómo funciona: La especificación Markdown vive permanentemente en el repositorio junto al código. Si el negocio pide un cambio o si se descubre un límite técnico mientras se avanza, lo primero que se hace es actualizar la especificación. Los pipelines de integración continua (CI) validan que el código no se haya desviado del original.
- Cuándo usarlo: Para proyectos profesionales, APIs de cara al cliente, arquitecturas de microservicios o equipos medianos donde varias personas tocan el mismo repositorio. Evita que el proyecto se convierta en un monstruo ingobernable con el paso de los meses.
Altitud 3: Spec-As-Source (El horizonte radical "AI-First")
- La regla: El humano tiene prohibido tocar el código de producción.
- Cómo funciona: El único archivo que se toca, edita y versiona es la especificación lógica o matemática en un formato ultra estructurado. Un compilador agéntico aislado lee esa especificación y genera el código base al 100%. De hecho, si abres cualquier archivo de código, verás un comentario gigante que dice:
// GENERATED FROM SPEC - DO NOT EDIT. - Cuándo usarlo: Microservicios con lógica matemática o de negocio muy aislada, APIs fuertemente tipadas o motores de procesamiento de datos puros. Es el nivel más limpio, pero requiere un nivel de madurez técnica brutal para controlar que la IA no meta la pata en la compilación.
4. Cara a cara: SDD frente a lo tradicional
Para ver claro de qué estamos hablando, se puede comparar el SDD con las herramientas y metodologías tradicionales que se suelen usar en los proyectos.
El documento de requisitos: PRD clásico vs. Diseño Técnico vs. Especificación SDD
| Criterio | Documento de Requisitos (PRD) | Documento de Diseño Técnico | Especificación SDD (Contrato Ejecutable) |
|---|---|---|---|
| ¿Quién lo lee? | Humanos (Product Managers, Ingenieros) | Ingenieros del equipo para ponerse de acuerdo | El agente de IA y tus herramientas de validación |
| ¿Cómo se resuelven las dudas? | Con reuniones interminables, cafés o asunciones del desarrollador | Discusiones en el documento o comentarios sueltos | Con reglas lógicas explícitas y pruebas automatizadas |
| ¿Cada cuánto se actualiza? | Casi nunca. Suele quedarse desfasado el primer día de desarrollo | Es estático. Es una foto fija de cómo pensabas hacer las cosas | Es un archivo vivo. Cambia de forma continua según avanza el proyecto |
| ¿Dónde vive? | En el Confluence, Notion o similar | En carpetas compartidas de Drive o en un PDF aislado | Versionado en Git, al lado del código del repositorio |
Metodologías de desarrollo: TDD vs. BDD vs. Vibe Coding vs. SDD
Aquí tienes el contraste real de cómo se trabaja en el día a día según la metodología que se elija:
| Dimensión | Test-Driven Development (TDD) | Behavior-Driven Development (BDD) | Vibe Coding (Programar por vibras) | Spec-Driven Development (SDD) |
|---|---|---|---|---|
| Artefacto Primario | Pruebas unitarias de bajo nivel | Escenarios conversacionales (Dado/Cuando/Entonces) | Prompts libres en el chat del IDE | Especificación en Markdown de alta fidelidad |
| Foco Técnico | Que una clase o función haga lo que debe | El comportamiento de la app desde el punto de vista del usuario | Modificar código directamente según parece | Contratos de integración y consistencia arquitectónica |
| Cómo se valida | Ejecutando la suite de tests en consola | Pruebas manuales o automatizadas por encima | "A mí me funciona en local" | Validadores estáticos e inyección continua de reglas de negocio |
| Gobernanza IA | Ninguna (un humano escribe el test) | Ninguna (las specs de usuario no frenan al agente) | Inexistente (la IA decide cómo resolver el problema) | Restricciones constitucionales y bucles de feedback de errores |
| Fuente de Verdad | La suite de tests | Las reuniones de diseño y el código de integración | El historial de chat que se borra al cerrar la sesión | La especificación técnica versionada en Git |
Conclusión: Tu nuevo rol como Diseñador de Contratos
Adoptar el Spec-Driven Development no significa que vayamos a volver a los tiempos oscuros del modelo en cascada (Waterfall) donde nos tirábamos meses escribiendo documentación antes de programar. Es justo lo contrario: es ponerle una columna vertebral de hierro a la velocidad absurda que nos dan los agentes autónomos.
Como el coste de traducir una especificación detallada a código funcional ahora es prácticamente cero gracias a la IA, el trabajo como desarrollador cambia por completo: dejas de pelearte con la sintaxis para convertirte en un diseñador de decisiones lógicas.
El día a día ya no consistirá en depurar un punto y coma que falta o en picar por enésima vez un servicio CRUD repetitivo. Ahora el valor está en diseñar contratos lógicos impecables, proteger el repositorio con una Constitución inviolable y auditar las decisiones que proponen los agentes antes de darles permiso para tocar la base de código.
En el siguiente artículo, El Chasis de la Gobernanza: Constitución vs. AGENTS.md (Y cómo no ahogarte en deuda de sincronización) nos meteremos de lleno en el barro para ver cómo estructurar el repositorio de forma que se separe de forma limpia la Constitución del Proyecto (las reglas inmutables de la arquitectura) de las configuraciones específicas del agente como AGENTS.md o CLAUDE.md. Además, analizaremos un bug real del ecosistema de Spec Kit que nos dejó una lección de oro: qué pasa cuando la herramienta agéntica se olvida de leer su propia constitución antes de implementar. ¡Nos vemos en la siguiente entrega!
📚 Serie Spec-Driven Development (SDD)
- Spec-Driven Development (SDD): Gobernanza de Agentes IA y el Fin del 'Vibe Coding'
- El Chasis de la Gobernanza: Constitución vs. AGENTS.md (Y cómo no ahogarte en deuda de sincronización)
- El Pipeline SDD en la Práctica: De la Sintaxis EARS a las Tareas Atómicas
- La Entrevista de Requisitos y el Bucle "SpecOps": Cómo usar la IA de Sparring y rehacer código sin dolor
- El Reto del Código Existente (Brownfield) y la Gestión de Múltiples Specs con Jira/Git
- Google Antigravity y MCP: Sandboxing, Autocorrección y la Nube