Hace unas semanas estaba viendo trabajar a un desarrollador senior con bastante experiencia. Usaba una de las mejores herramientas de IA del mercado.
Su flujo era este: escribía un prompt en el chat ("Agrégame la autenticación con OAuth y guarda el token en cookies HTTP-only"), la IA generaba 150 líneas de código, el código fallaba, le volvía a pedir que corrigiera el error, la IA cambiaba tres archivos sin avisar, se rompía el tipo de una interfaz… y de repente llevaba dos horas haciendo el famoso "prompt ping-pong".
Tenía la sensación de ir rapidísimo porque la IA escribía texto a toda velocidad. Pero al final de la jornada, la mitad de su tiempo lo había pasado arreglando las suposiciones que la IA había tenido que inventar porque nadie se las definía.
El problema no era la IA. El problema es que estaba intentando construir una casa pidiéndole al albañil que pusiera ladrillos sin enseñarle los planos. Aquí es donde Spec-Driven Development (SDD) transforma la forma en que los desarrolladores senior trabajan con los agentes de IA.
El espejismo del "Vibe Coding" sin rumbo
Nos han vendido que programar con IA consiste en hablarle en lenguaje natural como si fuera un colega y dejar que el LLM deduzca todo lo demás.
Para un script de 20 líneas o un prototipo que vas a tirar mañana, funciona. Para software en producción con arquitecturas reales, es una trampa.
Cuando no defines las reglas del juego antes de pedir código, obligas al agente de IA a tomar decenas de decisiones implícitas:
- ¿Qué nombres le da a las variables y modelos?
- ¿Cómo maneja los casos de borde y errores?
- ¿Qué contrato sigue la API?
- ¿Qué dependencias o utilidades existentes en el proyecto debe reutilizar?
Si el agente adivina mal una sola de esas cosas, el código generado es basura técnica que tendrás que mantener tú. Como explicamos en nuestro artículo sobre por qué tu spec falla con un agente de IA, la falta de claridad en las restricciones es la causa número uno de código roto.
¿Qué es Spec-Driven Development (SDD)?
Spec-Driven Development no es burocracia ni escribir documentación de 50 páginas que nadie lee.
SDD consiste en invertir el flujo de trabajo: en lugar de usar la IA para que redacte código directamente desde tu cabeza, utilizas la IA para definir una especificación estructurada y verificable ANTES de escribir la primera línea de código.
En nuestro workflow de producción, una especificación SDD se divide en tres piezas muy concretas:
1. spec.md (La Especificación Funcional y Técnica)
Define el QUÉ y el POR QUÉ.
- Contexto del problema y objetivo.
- Requisitos funcionales explícitos.
- Contratos de datos, tipos e interfaces.
- Reglas de negocio y lo que NO debe hacer el sistema.
2. plan.md (La Arquitectura e Impacto)
Define el CÓMO.
- Qué archivos se modifican, cuáles se crean y cuáles se eliminan.
- Estrategia de testing y verificación.
- Modificaciones en dependencias o firmas de API.
3. tasks.md (El Plan de Ejecución)
Define el ORDEN.
- Lista de tareas atómicas e independientes que el agente de IA puede ejecutar paso a paso sin perder contexto ni alucinar.
Eso sí, ten en cuenta que no siempre necesitas cargar con toda la estructura: en nuestra guía sobre cuándo NO usar Spec-Driven Development detallamos los escenarios donde un enfoque más directo resulta más eficiente.
El cambio mental: De programador a Director de Arquitectura
Mira lo que ocurre cuando le das a un agente (como Claude Code, AGY o Cursor) una especificación bien acotada:
# Spec: Interceptor de Telemetría HTTP
## Requisitos
- Interceptar todas las peticiones salientes HttpClient.
- Añadir el header X-Correlation-ID usando un UUID v4 si no existe previamente.
- Si la petición responde con status 401, reintentar una sola vez tras renovar el token vía AuthService.refreshToken().
- NO interceptar peticiones hacia /api/v1/auth/login.
## Contrato
- Firma de error devuelta: ApiErrorResponse { code: string; message: string; timestamp: number }.
Cuando un agente lee este archivo antes de tocar el código:
- El contexto entra limpio: El LLM no necesita adivinar el nombre del header ni la estrategia de reintento.
- Las respuestas son deterministas: El código generado encaja al primer intento con la arquitectura de tu aplicación.
- El tiempo de revisión tiende a cero: En lugar de leer 300 líneas de diff intentando adivinar qué pretendía hacer la IA, solo verificas que el código cumple los puntos de la spec.
Cómo empezar con SDD hoy mismo
No necesitas instalar un framework complejo ni cambiar la estructura de tu empresa.
La próxima vez que vayas a pedirle una funcionalidad a tu agente de IA, haz esto:
- Escribe un archivo
.mdrápido en tu proyecto describiendo qué quieres lograr, qué archivos se verán afectados y cuáles son los tipos/interfaces involucrados. - Pásale la spec al agente y pídele: "Revisa esta especificación. Identifica ambigüedades o contradicciones antes de proponer cambios".
- Una vez alineados en la especificación, pídele que genere la solución siguiendo las tareas definidas.
Te aseguro una cosa: escribir esa spec te llevará 4 minutos. Te ahorrará 45 minutos de depuración descontrolada.
Programar rápido con IA no consiste en teclear prompts más deprisa. Consiste en pensar con claridad antes de pedir el código.
Si quieres llevar tus habilidades al siguiente nivel, explora los Cursos de Dominicode donde profundizamos en arquitecturas modernas y herramientas de desarrollo. Además, en Dominicode Labs acompañamos a developers a construir productos reales y workflows autónomos asistidos por IA.
Preguntas frecuentes
¿SDD reemplaza a TDD (Test-Driven Development)?
No, se complementan. SDD define el contrato y las expectativas de alto nivel antes de construir, mientras que TDD asegura la corrección del código a nivel unitario durante la implementación.
¿Cuánto tiempo lleva escribir una especificación SDD?
Para una tarea típica de feature, redactar una spec básica toma entre 3 y 8 minutos. Ese pequeño esfuerzo inicial ahorra habitualmente horas de refactorización y depuración.
¿Qué herramientas son ideales para trabajar con Spec-Driven Development?
SDD es agnóstico a la herramienta, pero brilla especialmente con agentes CLI como Claude Code y AGY, o entornos con contexto profundo como Cursor y Windsurf.
¿Es necesario usar SDD para correcciones de bugs pequeñas?
Para bugs triviales o cambios de una sola línea no es necesario crear una spec completa. SDD es más valioso en tareas que involucran múltiples archivos, lógica de negocio o contratos de interfaz.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
Leave a Reply