Cómo hacer vibe coding de proyectos complejos para principiantes

La versión de una oración: puedes construir software real de grado de producción con IA aunque no seas desarrollador, pero solo si tratas la planeación y la documentación como el trabajo de verdad y el código como la parte fácil que viene después.

El “vibe coding” tiene mala reputación, y la mayoría del tiempo se la merece. Alguien abre un chat de IA, escribe “constrúyeme una app”, recibe algo que se ve impresionante durante diez minutos, y luego lo ve colapsar en el momento en que pide la segunda funcionalidad. El código se contradice a sí mismo. Nada está documentado. La IA olvidó lo que construyó la sesión pasada. Todo se convierte en una pila inmantenible.

Así no tiene que funcionar el vibe coding. Hay una forma de construir software genuinamente complejo con la IA como tu motor, donde el resultado es de grado de producción, mantenible, y no se desmorona bajo su propio peso. No requiere que seas programador. Requiere que seas disciplinado con unas cuantas cosas específicas.

Este es el método. No se trata de trucos de prompts. Se trata de estructura.

Las tres piezas que necesitas

Olvida la idea de una ventana de chat mágica que hace todo. Ese es exactamente el enfoque que colapsa. En su lugar, separas el trabajo en tres roles.

Rol 1: El arquitecto

Una sesión de chat de Claude donde piensas, planeas, tomas decisiones y produces especificaciones. Traduce tu visión en instrucciones técnicas precisas, revisa código y te contradice cuando algo choca con una decisión pasada.

Rol 2: El codificador

Donde las instrucciones se vuelven código. Puede ser Claude Code (una herramienta de línea de comandos con acceso directo a archivos), o una sesión de chat separada donde pegas los briefs. Su único trabajo es implementar la especificación. No hace arquitectura.

Rol 3: El registro

Un repositorio de GitHub. Cada decisión, cada línea de código, cada especificación vive aquí. El historial de Git es tu rastro de auditoría. Nada es real hasta que está commiteado.

El flujo es un ciclo: el arquitecto produce un brief, el codificador lo ejecuta contra el repo, tú revisas, el trabajo aprobado se commitea. El arquitecto puede leer el repo para verificar lo que el codificador construyó en realidad. Separar estos roles es la única decisión estructural que evita que un proyecto complejo colapse.

Por qué una sola ventana de chat falla

Cuando intentas hacerlo todo en una sola conversación larga, dos cosas salen mal. Primero, la sesión acumula ruido. Después de unas horas tiene tanto contexto que la señal se degrada y empieza a olvidar o contradecir elecciones anteriores. Segundo, cuando esa sesión termina, todo lo que “sabía” desaparece. No hay registro durable. La siguiente sesión empieza de cero, o peor, desde una media-memoria confundida.

El arreglo es que los documentos, no la sesión de chat, sean la capa durable. Una sesión que produjo un brief hizo su trabajo y puede cerrarse. El brief lleva el resultado hacia adelante. Si tu documentación es buena, una sesión completamente nueva puede retomar exactamente donde la anterior quedó en minutos. El chat es desechable. Los documentos son permanentes.

Los seis documentos que sostienen todo

Cada proyecto, sin importar su tamaño, necesita estos seis archivos. Un proyecto de fin de semana tiene seis archivos cortos. Un sistema complejo tiene seis detallados. La estructura escala por profundidad, no agregando más tipos de documento.

Archivo	Qué es	Por qué importa
CLAUDE.md	El briefing. Qué es el proyecto, el stack, las reglas, qué no hacer.	El codificador lo lee primero, cada vez. Es el documento de onboarding del desarrollador nuevo.
SCOPE.md	Qué entra en esta versión, y qué se difiere explícitamente.	La lista de diferidos detiene el scope creep. “¿Esto está en alcance?” lo responde un archivo, no un debate.
ARCHITECTURE.md	Cómo está armado el sistema. Componentes, flujo de datos, qué vive dónde.	Le dice al codificador dónde va el código nuevo, para que cada tarea no sea una adivinanza estructural.
DECISIONS.md	Decisiones numeradas y bloqueadas con su razonamiento.	Cada decisión bloqueada es una pregunta que nunca tienes que responder de nuevo.
CONVENTIONS.md	Estilo de código, nombres, patrones, manejo de errores.	Hace consistentes las miles de microdecisiones que toma el codificador.
OPEN_ITEMS.md	Incógnitas rastreadas y cosas aún no decididas.	Mantiene las incógnitas visibles en vez de escondidas en sesiones de chat muertas.

Los dos más subestimados son DECISIONS.md y la lista de diferidos de SCOPE.md. Ambos existen para evitar que relitigues preguntas resueltas. Cuando la IA sugiere algo que ya rechazaste, señalas el número de decisión o la lista de diferidos y sigues. Un proyecto maduro puede tener 30 o 40 decisiones bloqueadas, y eso es saludable. Cada una es una moneda que nunca tienes que volver a lanzar.

Si tu proyecto tiene interfaz de usuario, agrega un séptimo: DESIGN.md, con tu paleta de colores, tipografía, espaciado y estilo de componentes. Créalo en el momento en que el trabajo de UI empieza. Hace por las decisiones visuales lo que CONVENTIONS.md hace por el código.

La fase de planeación es donde ganas o pierdes

Esta es la idea más importante de todas, así que léela dos veces. El tiempo que pasas planeando no es sobrecarga. Es el tiempo más barato de todo el proyecto. Cada hora de planeación precisa te ahorra muchas horas de codificar, depurar y rehacer.

El codificador construye exactamente lo que especificas. Si no especificas algo, llena el hueco con una suposición. A veces la suposición está bien. A menudo no, y no te enteras hasta que estás probando la app y algo se comporta de una forma que nunca quisiste. Cada detalle sin especificar es un volado. Planear es cómo dejas de lanzar monedas.

Un deseo no es una especificación

Un deseo:

“Agrega un dashboard que muestre el estado de los servidores.”

Una especificación:

“Agrega un dashboard en /dashboard mostrando los servidores del usuario como tarjetas, tres por fila en escritorio, una por fila en móvil. Cada tarjeta muestra nombre, punto de estado (verde en línea, rojo fuera de línea, amarillo degradado), porcentaje de CPU, porcentaje de memoria, hora de última señal. Ordena por estado, problemas primero, luego alfabético. Sin servidores: muestra un estado vacío con un botón de ‘Conecta tu primer servidor’. Datos de más de 60 segundos: atenúa la tarjeta y muestra ‘Reconectando…’.”

La segunda versión es más larga, pero cada minuto que pasas escribiéndola te ahorra una hora de “eso no es lo que quise decir” después. El codificador no puede leer tu mente. La especificación es la lectura de mente, hecha por adelantado.

Camina el recorrido del usuario en voz alta

Antes de escribir un brief, traza la funcionalidad como si fueras el usuario. El usuario llega a la página de login. ¿Qué ve? Ingresa su correo y contraseña y hace clic en entrar. ¿Qué pasa? Estado de carga. Credenciales correctas, llega al dashboard. Pero ¿y si las credenciales están mal? ¿Cómo se ve el error? ¿Y si olvidó su contraseña? ¿Y si su cuenta está bloqueada? ¿Y si el servidor tarda cinco segundos en responder?

Cada una de esas preguntas es una rama, y cada rama es algo que el codificador tiene que construir. Camina el recorrido durante la planeación y cada rama entra en el brief y se construye correctamente de una vez. Sáltatelo y descubres las ramas una por una durante las pruebas, cada una una sorpresa, cada una un parche.

“¿Qué pasa si…?” es la pregunta que previene los bugs

La mayoría de los bugs vive en los casos que nadie pensó. Todos especifican el camino feliz. Los bugs están en los bordes. Para cada funcionalidad, pregunta: ¿Qué pasa si la entrada está vacía? ¿Malformada o absurdamente grande? ¿Qué pasa si la solicitud de red falla? ¿Qué pasa si el usuario hace esto dos veces rápido? ¿Qué pasa si dos usuarios lo hacen al mismo tiempo? ¿Qué pasa si los datos aún no existen? ¿Qué pasa si no tienen permiso? ¿Qué pasa si un servicio externo está caído?

No necesitas ser programador para hacer estas preguntas. Son preguntas de producto, no técnicas. Una jugada útil: cuando termines un brief, dáselo de vuelta a la sesión de arquitecto y pregunta “¿qué casos límite o modos de falla no estoy contemplando?”. Encontrar los huecos ahora es gratis. Encontrarlos en producción es caro.

Construye válvulas de escape en cada instrucción

Esto es lo de mayor apalancamiento que puedes montar, y es lo que más importa si no eres programador. Una válvula de escape es una instrucción permanente que le dice a la IA qué hacer cuando choca con algo incierto, en vez de adivinar.

El modo de falla predeterminado de cualquier codificador de IA es este: choca con algo ambiguo, hace una suposición que suena razonable, y sigue. La suposición es invisible para ti hasta que aflora después como bug. Las válvulas de escape convierten esas suposiciones silenciosas en preguntas que tú respondes. Pon estas en tu CLAUDE.md y en las instrucciones de tu Proyecto para que apliquen a cada sesión:

“Si no entiendes algo, pregunta. No asumas.”

La fundamental. Anula la tendencia del codificador a llenar huecos en silencio. La pregunta te cuesta 30 segundos. La suposición equivocada te cuesta una sesión de depuración.

“Si hay que tomar una decisión y no la he especificado, detente y muéstramela. Explica las opciones, los pros y contras, y dame tu recomendación.”

Esta es la válvula de escape para los no programadores específicamente. No necesitas entender los detalles técnicos. Necesitas las opciones desplegadas, los intercambios en lenguaje sencillo, y una recomendación que puedes aceptar o anular. Sigues siendo quien decide sin ser el ingeniero.

“Si una solicitud choca con una decisión bloqueada o con el alcance actual, señálalo antes de proceder.”

Protege tu arquitectura y tu cronograma de la deriva. Si accidentalmente pides algo que contradice una decisión pasada, quieres que te lo digan, no que te obedezcan en silencio.

“Si notas un problema con mi plan, dímelo aunque no te lo haya preguntado.”

Quieres un colaborador, no un tomador de órdenes. Si la IA ve un hueco en tu lógica, quieres que aflore mientras todavía es barato arreglarlo.

El patrón detrás de todas: estás convirtiendo los juicios silenciosos de la IA en momentos explícitos donde tú decides. Eso es lo que te mantiene en control de un proyecto técnico sin necesitar entender cada línea de código.

El ciclo de desarrollo

Paso 1: Planear (sesión de arquitecto)

Describes lo que quieres. El arquitecto hace preguntas aclaratorias, verifica contra las decisiones y el alcance existentes, y produce un brief: una especificación precisa con el comportamiento completo, cada rama de “qué pasa si”, los detalles de diseño, y qué NO hacer.

Paso 2: Ejecutar (codificador)

Entrégale el brief al codificador. Lee los documentos, lee el brief, e implementa. Un brief por sesión. Las válvulas de escape se ganan su lugar aquí: un codificador bien instruido se detiene y pregunta cuando el brief deja algo abierto.

Paso 3: Revisar (de vuelta en la sesión de arquitecto)

Pídele al arquitecto que verifique lo construido contra el brief y el documento de arquitectura. “Lee los archivos cambiados y confirma que la arquitectura coincide con ARCHITECTURE.md.” Las afirmaciones estructurales se verifican contra los archivos reales.

Paso 4: Actualizar los documentos

El paso que la mayoría se salta, y el que hace que la siguiente sesión sea productiva en vez de confundida. Las decisiones nuevas van a DECISIONS.md. Las incógnitas resueltas se marcan en OPEN_ITEMS.md. Los documentos deben reflejar la realidad después de cada hito.

Los errores que destruyen los proyectos de vibe coding

Empezar a codificar antes de escribir los documentos

Los documentos toman unas horas. Saltártelos cuesta semanas de retrabajo cuando el codificador construye algo que no coincide con una visión que nunca escribiste.

Dejar que el codificador tome decisiones de arquitectura

El codificador implementa, no hace arquitectura. Las decisiones arquitectónicas pertenecen a la sesión de planeación donde puedes sopesar los intercambios y registrar el resultado. Si el codificador choca con una pregunta arquitectónica a media tarea, debería detenerse y preguntar, no adivinar.

No actualizar los documentos después de los hitos

Los documentos desactualizados son peores que ningún documento porque crean confianza falsa. Si el código diverge de los documentos, la siguiente sesión produce instrucciones basadas en una realidad que ya no existe.

Hacer las sesiones demasiado largas

Una sesión que corre durante horas ha acumulado contexto, pero también ruido. La relación señal-ruido se degrada. Empieza fresco, deja que los documentos carguen el contexto, y sigue.

Saltarse el paso de revisión

“El codificador dice que funciona” no es verificación. Lee los archivos. Revisa la estructura. Atrapar problemas al momento de la revisión es mucho más barato que atraparlos en producción.

Especificar solo el camino feliz

Si tu brief describe lo que pasa cuando todo funciona y no dice nada de las fallas o los casos límite, el codificador inventa su propio manejo. De cualquier forma obtienes un comportamiento que no elegiste.

Una nota sobre el costo, y por qué vale la pena

Este flujo usa más tokens que el enfoque de una sola sesión. El arquitecto lee documentos, produce briefs, revisa código. El codificador lee documentos, ejecuta, commitea. Hay duplicación inherente.

El intercambio vale la pena. La alternativa, una sesión larga intentando hacer todo, produce código que se aleja de tu visión, toma decisiones sin documentar, y no puede retomarse cuando la sesión termina. El costo del retrabajo de una mala implementación excede por mucho el costo de los tokens extra gastados en planeación y revisión. Y conforme tus documentos maduran, el costo de tokens por tarea de hecho baja, porque los documentos cargan más contexto y las conversaciones necesitan menos ida y vuelta.

Cómo empezar en 30 minutos

No necesitas construir toda la estructura perfecta el día uno. Necesitas el esqueleto. Este es el camino más rápido:

Tus primeros 30 minutos

• Crea un repo de GitHub con una carpeta docs/
• Escribe CLAUDE.md: qué es el proyecto, el stack, las reglas básicas y las instrucciones de válvulas de escape (15 min)
• Escribe SCOPE.md: qué es la v1, qué se difiere (5 min)
• Escribe un ARCHITECTURE.md en borrador: los componentes y cómo se conectan (10 min)
• Crea DECISIONS.md, CONVENTIONS.md y OPEN_ITEMS.md vacíos con una entrada de ejemplo cada uno
• Si tu proyecto tiene UI, pídele a la sesión de planeación que proponga una paleta y una tipografía, luego guárdalas en DESIGN.md
• Crea un Proyecto de Claude, pega tus instrucciones (incluyendo las válvulas de escape), sube los documentos
• Monta tu codificador y clona el repo
• Empieza tu primera sesión de planeación: “Esto es lo que quiero construir. Caminemos el recorrido del usuario, luego escribamos el primer brief.”

Los documentos quedarán en borrador. Está bien. Mejoran con cada sesión, cada decisión, cada hito. La estructura es lo que importa el día uno, no el pulido.

Ese es todo el secreto para hacer vibe coding de algo real. No mejores prompts. Una separación disciplinada de la planeación y la ejecución, un conjunto durable de documentos que sobrevive a cualquier sesión individual, e instrucciones permanentes que convierten las adivinanzas silenciosas de la IA en decisiones que tú tomas. Deja esas tres cosas bien y puedes construir software mucho más complejo de lo que cualquiera esperaría, sin escribir el código tú mismo.