Post By
Roberto Murillo
Introducción
Hace unos meses empecé a ver un patrón que se repetía demasiado en equipos y comunidades de desarrollo: alguien abría un chat de IA, pegaba un pedido más o menos detallado y generaba cientos de líneas de código sin un solo documento previo que definiera qué tenía que hacer ese sistema.
Lo llamaban “vibe coding”. Sonaba relajado. Hasta que fallaba.
Cuando tuve que mantener un proyecto donde todos los servicios se habían generado con esa modalidad, entendí el problema de fondo: el contexto se evaporó con el prompt. No había contrato, no había casos de borde documentados y la IA había tomado decisiones arbitrarias que ahora eran deuda técnica visible.
Esa experiencia me terminó de convencer de algo que la comunidad viene formalizando hace rato: Spec-Driven Development con IA no es un catchy phrase, es una forma de no perder el rumbo cuando usas herramientas generativas en serio.
El Problema
Vibe coding sucede cuando usás un LLM como si fuera un developer junior con acceso total al teclado: le pedís algo, aceptás el código y seguís. La velocidad es tentadora al principio. El costo aparece después.
Los riesgos más comunes son:
- Contratos implícitos: nadie sabe qué hace cada servicio porque el prompt que lo generó no quedó registrado.
- Decisiones invisibles: el modelo elige patrones, librerías y formatos sin consultar, y queda documentado solo en el código.
- Falta de trazabilidad: cuando un caso de borde explota en producción, no hay un “spec” que te diga si era un comportamiento esperado o un bug de generación.
- Deuda técnica acelerada: se acumulan soluciones inconsistentes porque cada prompt es un universo separado.
Esto no es un problema de la herramienta. Es un problema de proceso.
Diagnóstico
Cómo saber si tu equipo está en vibe coding puro:
1. Los features se describen en tickets con una o dos oraciones y listo.
2. No existe ningún documento vivo que defina qué debe hacer el sistema.
3. El código generado por IA se mezcla con código escrito a mano sin convenciones claras.
4. Los tests se agregan después, casi como un trámite, no como parte del diseño.
5. Cuando hay que modificar el sistema, nadie sabe si un cambio rompe algo hasta que llega a staging.
Si te suena familiar, no estás solo. La comunidad de ingeniería empezó a reaccionar con un nombre que suena más aburrido, pero mucho más seguro: Spec-Driven Development.
La Solución
Spec-Driven Development (SDD) es una práctica que viene de arquitectura y diseño, y que hoy se adapta perfectamente a la era de la IA generativa. La idea es simple: definir el comportamiento antes de generar el código.
El ciclo se parece a esto:
- Definir contratos del sistema antes de escribir una línea de lógica.
- Escribir especificaciones de cada componente: entradas, salidas, errores, casos borde.
- Usar la especificación como prompt para el modelo de lenguaje. No le pedís “haceme un endpoint de pagos”; le pasás el spec y le pedís implementación alineada.
- Validar contra el spec, no contra tu intuición de si el código se ve bien.
flowchart LR
A[Especificación del sistema] --> B[Spec de componente / endpoint]
B --> C[Prompt estructurado a IA]
C --> D[Generación de código]
D --> E[Tests de validación]
E --> F{¿Cumple el spec?}
F -->|No| B
F -->|Sí| G[Código mergeado]
G --> H[Documentación viva]La clave no es escribir más, es escribir mejor antes. Un spec no es un documento de diseño pesado: puede ser un conjunto de contratos, ejemplos de entrada/salida, diagramas de flujo o definiciones de errores. Cuanto más estructurado sea, menos libertad le das al modelo para decidir por vos.
Procesos Recomendados por la Comunidad
Varios equipos que probaron integrar SDD con IA terminaron convergiendo en un flujo parecido a este:
1. Capturar el comportamiento deseado en forma de specs. No empieces por preguntar “cómo implemento X”. Empezá por definir qué hace X, qué parámetros recibe, qué devuelve y qué errores puede fallar.
2. Revisar el spec como equipo. El spec debería poder leerlo alguien que no escribió el código. Si no, es ambicioso o está incompleto.
3. Generar prompts estructurados a partir del spec. Incluí en el prompt la especificación, los contratos y los ejemplos. No dependas de la memoria del modelo: pasále el documento.
4. Generar código en pasos pequeños. Un spec por endpoint, un spec por servicio. Evitá pedir el sistema entero en una sola llamada.
5. Validar automáticamente. Tests de contrato, schemas de validación, ejemplos que deberían fallar y ejemplos que deberían pasar. Si el spec cambia, los tests cambian con él.
# Ejemplo de flujo local con spec + IA
# 1. Escribir el spec en markdown
cat > spec.md << 'EOF'
- Endpoint: POST /api/checkout
- Input: { cart_id, payment_method }
- Output: 200 { order_id, status }
- Error: 422 si payment_method inválido
EOF
# 2. Usar el spec como contexto en tu herramienta de IA
# (tu CLI o backend de IA preferido)Trabajá con specs versionadas: guardá el .md del spec junto al código, no en un Word o un Notion desconectado. Así cuando el equipo cambie, el contrato del sistema viaja con el repo.
Si tu stack ya usa contratos automáticos (como OpenAPI o AsyncAPI), no te olvides de sincronizarlos con el texto en lenguaje natural del spec. Los documentos escritos y los contratos técnicos suelen divergir rápido si no se actualizan juntos.
Lecciones Aprendidas
- La especificación es el verdadero producto. El código es una consecuencia del spec, no al revés.
- Menos es más en cada spec. Un endpoint por spec, un comportamiento por iteración. Los prompts largos y difusos generan código difuso.
- Los tests son la traducción ejecutable del spec. Si no podés escribir un test que verifique lo que declaraste, tu spec está incompleta.
- La documentación viva vence a la documentación muerta. Guardá el spec en el mismo repo, en la misma carpeta que el código que describe.
- IA y SDD se potencian: la IA te ayuda a escribir specs y código rápido, pero sin spec, la IA pierde el rumbo más rápido que un equipo humano sin líder.
Conclusión
Vibe coding está bien para prototipos y experimentos. Para sistemas que van a vivir meses o años en producción, necesitás un proceso que supervise las decisiones de la IA.
Spec-Driven Development con IA no es un reemplazo de las buenas prácticas tradicionales: es una versión moderna que usa la velocidad de la generación automática sin perder el control del comportamiento del sistema.
Empezá por un spec chico para tu próxima feature. Después contame si no se siente mucho más seguro tocar el código sabiendo qué debería hacer.
