Tu app funciona, pero no sabes por qué
El vibe coding te da velocidad. El Spec-Driven Development te da control. Así es como se complementan.
Hola, soy Pol Marzà. Cada semana escribo una nueva edición de Con Criterio, la newsletter sobre construir productos digitales con IA, con planificación, método y sin atajos. Si te han reenviado este email, puedes suscribirte aquí:
El próximo miércoles 25 de marzo, a las 19:00 (hora española), daré una charla en directo en TecnoFor sobre esto que llevo tiempo dándole vueltas: qué pasa cuando el vibe coding deja de ser suficiente. Es gratuita y abierta. Si te interesa, aquí tienes el enlace para apuntarte:
Esta newsletter es una introducción a lo que contaré allí. Si el tema te interesa, el miércoles lo desarrollo en profundidad.
El problema que nadie quiere ver
El vibecoding funciona. Escribes un prompt, la IA genera código, iteras, y en un rato tienes algo que se parece a lo que querías. Para prototipos rápidos, pruebas de concepto o proyectos pequeños, es un método válido.
El problema aparece cuando quieres ir más allá. Cuando el proyecto crece, cuando necesitas que varias partes encajen, cuando hay autenticación, base de datos, roles de usuario, lógica de negocio real. En ese punto, el vibe coding se convierte en una conversación caótica con un modelo que no tiene contexto suficiente para tomar buenas decisiones.
No porque la IA sea mala. Sino porque tú no le has dado un mapa de lo que estás construyendo.
Spec-Driven Development: primero el qué, después el cómo
El Spec-Driven Development (SDD) parte de una idea sencilla: antes de escribir una sola línea de código, defines con precisión qué vas a construir. Requisitos, flujos, decisiones técnicas, restricciones, casos límite. Todo queda documentado en una especificación que sirve como fuente de verdad tanto para la IA como para ti.
No es un concepto nuevo. Los ingenieros de software llevan décadas escribiendo especificaciones. Lo que cambia ahora es que esa especificación no es solo documentación para humanos, es el input que determina la calidad del código que genera la IA.
La diferencia práctica es directa: en lugar de ir ajustando sobre la marcha (“no, esto no era así, cámbialo”), empiezas con un documento que describe exactamente lo que necesitas. La IA trabaja con un contexto completo y produce resultados más coherentes desde el primer intento.
Los 5 documentos que sostienen un proyecto SDD
En la práctica, una especificación no es un solo archivo enorme. Son documentos separados, cada uno con una función clara:
1. Propósito. Qué resuelve el producto, para quién lo resuelve y (igual de importante) qué no resolverá nunca. Este documento te obliga a tomar decisiones de alcance antes de escribir código.
2. Usuarios y flujos. El camino concreto de cada tipo de usuario dentro del producto. No hablamos de personas abstractas, sino de secuencias reales: “el usuario llega, hace esto, ve aquello, el sistema responde así”.
3. Arquitectura básica. Stack tecnológico, tablas de base de datos y sus relaciones. No hace falta un diagrama de 50 páginas. Con que quede claro qué tecnologías usas y cómo se conectan los datos, es suficiente.
4. CLAUDE.md (o AGENTS.md). Este es el archivo que mantiene el contexto vivo entre sesiones. Cuando cierras una conversación con la IA y abres otra, este documento le dice dónde estabas y qué decisiones ya se tomaron. Sin él, cada sesión empieza de cero.
5. Changelog. Un registro de cada decisión que modifica la especificación. No es un log de commits, es un historial de “por qué” cambiaron las cosas, no solo “qué” cambió.
No son cosas opuestas
El SDD no sustituye al vibe coding. Son etapas de madurez distintas.
Si estás explorando una idea, validando si algo tiene sentido o construyendo un prototipo rápido para enseñar a alguien, el vibe coding es perfecto. Es rápido, es flexible y el coste de equivocarte es bajo.
Pero cuando decides que ese proyecto va en serio (que necesita escalabilidad, mantenibilidad, que otras personas van a usarlo), necesitas pasar a un modo de trabajo más estructurado. Ahí es donde entra el SDD.
En mi caso, llevo casi tres años trabajando así sin que existiera el término. Lo que yo llamo “clarificación” (esa fase larga de conversación y planificación antes de tocar código) es esencialmente SDD en versión artesanal. La industria ha formalizado lo que muchos product makers ya hacíamos por necesidad.
El miércoles, en directo
Esto ha sido un primer vistazo. El miércoles 25 a las 19:00 en TecnoForo hablaré en detalle sobre cómo aplicar SDD en la práctica: qué documentos generar, cómo estructurar la especificación y cómo conectar todo esto con las herramientas que ya usas.
Si quieres profundizar, apúntate aquí (es gratuito):
— Pol