Vibe coding sin sistema: por qué tu proyecto con IA se rompe
DominicodeLa primera semana fue increíble.
Abriste Claude Code, describiste la idea a grandes rasgos, y el proyecto arrancó. En dos horas tenías rutas funcionando. En cuatro tenías la autenticación. En un día, un prototipo que podías enseñar. Sentiste que habías desbloqueado algo — que la IA era la ventaja que llevabas buscando.
La segunda semana empezaron las grietas. Añadiste una feature nueva y rompiste una que ya funcionaba. Pediste al modelo que corrigiera el bug y generó código con una convención de nombres distinta a la del resto del proyecto. Abriste el archivo equivocado porque en una sesión le pusiste un nombre y en otra, otro.
La tercera semana dejaste de entender tu propio proyecto.
Esto no es un problema de la IA. Es el resultado predecible del vibe coding sin sistema — y hay una salida que no implica empezar desde cero.
El ciclo que reconocerás si llevas más de dos semanas con IA
El vibe coding tiene un patrón muy concreto. Arranca con energía, avanza rápido, y luego se convierte en deuda que nadie quiere pagar.
Semana 1 — La euforia del prototipo. El modelo genera código que funciona. Tú describes lo que quieres, él lo construye. Cada sesión termina con algo nuevo encima de la mesa. Sientes que puedes construir cualquier cosa.
Semana 2 — Los primeros síntomas. Añadir una feature empieza a costar más de lo esperado. El modelo genera código que no encaja del todo con lo que ya existe — naming diferente, estructura diferente, patrones distintos. Cada sesión nueva es ciega respecto a las decisiones de la anterior.
Semana 3 — El colapso. El proyecto tiene capas que se contradicen entre sí. No puedes explicarle a nadie la arquitectura — ni siquiera a la IA que lo construyó. Cada sesión nueva te exige re-explicar el contexto desde cero. Y cuando lo haces, el modelo entiende una versión diferente de lo que tienes.
Aquí hay dos salidas que la mayoría elige: abandonar el proyecto o empezar desde cero con la promesa de “esta vez lo haré mejor”. Ninguna funciona porque el problema no es el punto de partida. Es la ausencia de sistema.
Por qué el vibe coding escala mal
Por defecto, la IA no carga el estado de sesiones anteriores. Aunque herramientas como Claude Projects permiten persistir algo de contexto entre conversaciones, ese contexto no es estructurado — no sabe que decidiste usar repositorios en lugar de servicios directos, ni recuerda que el módulo de usuarios tiene una estructura específica, ni que descartaste la opción B el martes porque tenía un problema de concurrencia.
Lo que el modelo construye en cada sesión es una respuesta razonable al contexto que le das en ese momento. Sin especificación, sin arquitectura documentada, sin contexto persistente, ese contexto siempre es incompleto. Y el modelo completa los huecos con sus propias suposiciones — razonables para un proyecto genérico, incorrectas para el tuyo.
El resultado es código construido sobre arena. Cada sesión añade una capa nueva que puede o no ser compatible con lo que ya existe. Con el tiempo, la incoherencia se acumula hasta que el proyecto es incomprensible — no porque sea complejo, sino porque nadie tomó decisiones explícitas.
Esto no es un defecto del modelo. Es una consecuencia directa de cómo usamos el modelo.
Los 3 síntomas de que tu proyecto está en modo vibe
Antes de hablar de la solución, vale la pena identificar dónde estás. Estos tres síntomas aparecen en orden: si tienes los tres, el proyecto ya necesita intervención.
Naming inconsistente entre archivos. Un archivo se llama user-service.ts, otro usersService.ts, otro UserManager.ts. Las variables que representan el mismo concepto tienen nombres distintos según la sesión en que se crearon. El proyecto habla idiomas distintos en cada carpeta.
Tests que no prueban lo que dicen. Los tests existen — el modelo siempre los genera cuando se los pides — pero prueban el código tal como fue escrito en ese momento, no el comportamiento que el sistema debería tener. Cuando el código cambia, los tests se rompen de formas que no esperabas. O peor: siguen en verde porque prueban implementación, no contrato.
No puedes explicar la arquitectura de tu propio proyecto. Este es el síntoma definitivo. Si le preguntas al modelo “¿cuál es la arquitectura de este proyecto?” y la respuesta que genera no coincide con lo que tienes, tienes un problema de contexto. Si tú mismo no puedes describir en dos párrafos cómo fluyen los datos de principio a fin, el proyecto ya está en modo vibe terminal.
Si reconoces los tres, no significa que tengas que tirar el código. Significa que tienes que añadir lo que falta: sistema.
El sistema que reemplaza al vibe
Pasar del vibe coding al desarrollo con sistema no es abandonar la IA. Es usarla de forma diferente — con estructura que la hace más efectiva, no más lenta.
El sistema tiene cuatro piezas. No son opcionales entre sí.
1. Spec antes de código (SDD)
La especificación no es un documento burocrático. Es la respuesta a: ¿qué estoy construyendo exactamente, para quién, y cómo fluye la información?
Con Spec-Driven Development, la spec se escribe antes de abrir el editor. No porque sea una regla, sino porque un modelo que recibe una spec bien escrita genera código diez veces más coherente que uno al que le describes la idea de viva voz. La spec define los contratos. El modelo los implementa. El espacio de decisión se reduce y el output es predecible.
2. Contexto persistente (CLAUDE.md)
El CLAUDE.md en la raíz del proyecto es el system prompt que Claude Code lee al inicio de cada sesión. Contiene el stack, las convenciones de naming, las restricciones explícitas y el estado actual del proyecto. No es documentación — es la memoria estructurada que el modelo necesita para ser consistente. En otros entornos como Cursor o Windsurf, el concepto equivalente existe con distintos nombres (.cursor/rules/, AGENTS.md).
Sin este archivo, cada sesión es ciega. Con él, cada sesión arranca desde el mismo punto de partida. Las decisiones tomadas en día 1 siguen vigentes en día 30. Aquí tienes cómo estructurar este archivo paso a paso si quieres implementarlo hoy.
3. Tareas pequeñas (chunking)
“Implementa el sistema de autenticación completo” es el tipo de prompt que genera código plausible pero incoherente con tu proyecto. El modelo toma demasiadas decisiones implícitas porque el scope es demasiado amplio.
La regla es: una tarea por sesión, un contrato por tarea. En lugar de pedir la autenticación completa, pides el esquema de usuario, luego el endpoint de login, luego el middleware de validación. Cuatro sesiones. Cuatro piezas que encajan porque cada una tiene un contexto explícito y un alcance controlado.
4. Validación continua
Al final de cada sesión, pides al modelo un resumen: qué se implementó, qué decisiones se tomaron, qué queda pendiente. Ese resumen va a un session-log.md con fecha. La sesión siguiente empieza con ese log como contexto. No empiezas desde cero — empiezas desde donde lo dejaste.
El context engineering es la disciplina que une estas cuatro piezas. No es un concepto teórico — es la práctica concreta de gestionar qué información recibe el modelo en cada momento.
Cómo hacer la transición sin empezar desde cero
Este es el punto donde la mayoría para: “mi proyecto ya es un caos, tendría que reescribirlo todo”. No.
La transición tiene cinco pasos y los puedes empezar hoy con el código que tienes.
Paso 1 — Audita lo que existe. Antes de añadir nada, entiende el estado real del proyecto. Pídele al modelo que lea tu estructura de carpetas y te describa la arquitectura que ve. Compara esa descripción con lo que creías que habías construido. La brecha entre las dos es tu deuda de contexto.
Paso 2 — Genera la spec retroactiva. No necesitas escribir la spec desde cero — puedes generarla a partir del código existente. Dale al modelo el contexto actual y pídele que genere una spec de lo que existe: entidades, contratos, flujos. Esa spec se convierte en la verdad oficial del proyecto, no el código.
Paso 3 — Crea el CLAUDE.md. Con la spec en mano, crea el archivo de contexto persistente. Incluye el stack real (no el ideal), las convenciones que ya están en el código aunque no estuvieran documentadas, y las restricciones que te habría gustado tener desde el principio. Esto es lo que normaliza el naming y la estructura en todas las sesiones futuras.
Paso 4 — Divide lo que queda en tareas pequeñas. El backlog de features pendientes deja de ser una lista de ideas y pasa a ser una lista de contratos. Cada tarea tiene una descripción concreta: qué recibe, qué devuelve, cómo interactúa con lo existente. El modelo implementa contratos, no ideas.
Paso 5 — Valida antes de seguir. Antes de añadir la siguiente feature, escribe o genera los tests del contrato de la feature actual. No para cubrir el código — para verificar el comportamiento. Si el test falla cuando cambias algo que no debería afectarlo, el test te está diciendo que el contrato no estaba claro.
Son cinco pasos que se pueden hacer en una tarde si el proyecto no es demasiado grande. El resultado no es un proyecto perfecto — es un proyecto con el que puedes volver a trabajar con confianza.
La diferencia que importa en producción
El vibe coding no es malo. Es la herramienta correcta para el momento incorrecto.
Para validar una idea en 48 horas, el vibe coding es insuperable. Para construir algo que tendrás que mantener en semanas 4, 8 y 16, es un problema en espera de ocurrir.
La diferencia entre un developer que usa IA con efectividad y uno que acaba atascado no es el modelo que usan, ni el IDE, ni los prompts. Es si tienen sistema o no. Si cada sesión nueva añade coherencia al proyecto o añade caos.
El sistema no frena la velocidad de la IA. La mantiene en el tiempo.
Si quieres ver esto aplicado en proyectos reales — desde la spec inicial hasta el producto funcionando, con CLAUDE.md, SDD y Claude Code — el curso Construye con IA: de la idea al producto cubre exactamente ese flujo. Y si quieres trabajar la transición con proyectos concretos y feedback en comunidad, en Dominicode Labs hacemos exactamente eso.
FAQ
¿El vibe coding sirve para algo?
Sí, y mucho. El vibe coding es la herramienta perfecta para prototipar ideas rápido — para validar si algo es técnicamente posible, para hacer demos, para explorar una API que no conoces. El problema no es el vibe coding en sí, sino usarlo para construir algo que vas a mantener durante semanas o meses. En ese contexto, la ausencia de sistema convierte la velocidad inicial en deuda que pagas después con intereses.
¿Cuándo está bien improvisar?
Siempre que el objetivo sea explorar, no construir. Si abres una sesión nueva para entender cómo funciona un nuevo framework, para probar una librería, o para validar si tu idea de arquitectura tiene sentido — improvisa sin culpa. El momento en que decides que algo va a producción o que tendrás que volver a ello en una semana, el sistema tiene que entrar.
¿Tengo que empezar desde cero si mi proyecto ya es un caos?
No. La spec retroactiva y el CLAUDE.md te permiten añadir estructura al código existente sin reescribirlo. El código puede quedarse como está mientras añades el sistema que le da coherencia hacia adelante. Lo que sí tendrás que hacer es tomar las decisiones que no tomaste al principio — naming, arquitectura, convenciones — y documentarlas. Eso es trabajo que tarda horas, no semanas.
¿El sistema con IA hace el desarrollo más lento?
La percepción de velocidad que da el vibe coding es real — pero es velocidad a corto plazo. El sistema hace que la semana 3 sea igual de rápida que la semana 1, porque el contexto no se degrada. Sin sistema, la velocidad cae semana a semana conforme la deuda de contexto se acumula. Quien usa sistema tiene el mismo ritmo en el sprint 8 que en el sprint 1. Quien usa vibe coding puro, no.
¿Qué es lo primero que debo hacer si reconozco los síntomas?
Crea el CLAUDE.md. Puedes tenerlo en quince minutos: descripción del proyecto, stack real con versiones, convenciones de naming que ya existen en el código (aunque estén implícitas), y las tres o cuatro restricciones que te habría gustado tener desde el principio. Ese archivo solo ya reduce la inconsistencia en las sesiones futuras. El resto del sistema puedes añadirlo gradualmente.
¿En qué se diferencia el vibe coding del agentic engineering?
El vibe coding es un flujo de trabajo donde el developer describe ideas y el modelo decide cómo implementarlas. El agentic engineering es una disciplina donde el developer diseña el sistema — la spec, el contexto, los contratos, los límites — y delega la implementación de forma controlada. La diferencia no es la IA que usas sino quién toma las decisiones de diseño: tú o el modelo.
*Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.*