Cómo hacer vibe coding en proyectos complejos para principiantes
Puedes construir software real y de nivel productivo con IA aunque no seas desarrollador, pero solo si tratas la planificación y la documentación como el trabajo real, y el código como la parte fácil que viene después.
El "vibe coding" tiene mala reputación, y la mayor parte del tiempo se la merece. Alguien abre un chat de IA, escribe "hazme una app", obtiene algo que parece impresionante durante diez minutos y luego lo ve colapsar en el momento en que pide la segunda funcionalidad. El código se contradice. Nada está documentado. La IA olvidó lo que construyó en la sesión anterior. Todo se convierte en un desastre imposible de mantener.
No tiene por qué funcionar así. Existe una forma de construir software genuinamente complejo con la IA como motor, donde el resultado es de nivel productivo, mantenible y no se derrumba bajo su propio peso. No requiere que seas programador. Requiere que seas disciplinado en unas pocas cosas específicas.
Este es el método. No se trata de trucos de prompting. Se trata de estructura.
Las tres piezas que necesitas
Olvídate de la idea de una ventana de chat mágica que lo hace todo. Ese es exactamente el enfoque que colapsa. En cambio, separa el trabajo en tres roles.
Una sesión de chat con Claude donde piensas, planificas, tomas decisiones y produces especificaciones. Traduce tu visión en instrucciones técnicas precisas, revisa el código y señala cuando algo contradice una decisión anterior.
Donde las instrucciones se convierten en 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.
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á confirmado (committed).
El flujo de trabajo es un ciclo: el arquitecto produce un brief, el coder lo ejecuta contra el repositorio, tú revisas, el trabajo aprobado se confirma. El arquitecto puede leer el repositorio para verificar lo que el coder realmente construyó. Separar estos roles es la única decisión estructural que evita que un proyecto complejo colapse.
Por qué falla una sola ventana de chat
Cuando intentas hacer 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 decisiones anteriores. Segundo, cuando esa sesión termina, todo lo que "sabía" desaparece. No hay un registro duradero. La siguiente sesión empieza desde cero, o peor aún, desde un recuerdo confuso a medias.
La solución es que los documentos, no la sesión de chat, sean la capa duradera. Una sesión que produjo un brief ha cumplido su función 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 quedó la última en cuestión de minutos. El chat es desechable. Los documentos son permanentes.
Los seis documentos que sostienen todo
Todo proyecto, independientemente de su tamaño, necesita estos seis archivos. Un proyecto de fin de semana tiene seis archivos cortos. Un sistema complejo tiene seis archivos detallados. La estructura escala en profundidad, no añadiendo 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 coder lo lee primero, siempre. Es el documento de incorporación para un nuevo desarrollador. |
| SCOPE.md | Qué está incluido en esta versión y qué se aplaza explícitamente. | La lista de aplazados detiene el desvío de alcance. "¿Esto está en el alcance?" se responde con un archivo, no con un debate. |
| ARCHITECTURE.md | Cómo está construido el sistema. Componentes, flujo de datos, qué vive dónde. | Le indica al coder dónde pertenece el nuevo código, para que cada tarea no sea una suposición estructural. |
| DECISIONS.md | Decisiones numeradas y bloqueadas con su justificación. | Cada decisión bloqueada es una pregunta que nunca tendrás que volver a responder. |
| CONVENTIONS.md | Estilo de código, nomenclatura, patrones, manejo de errores. | Hace que las miles de micro-decisiones que toma el coder sean consistentes. |
| OPEN_ITEMS.md | Incógnitas registradas y cosas aún no decididas. | Mantiene las incógnitas visibles en lugar de que se pierdan en sesiones de chat muertas. |
Los dos más subestimados son DECISIONS.md y la lista de aplazados de SCOPE.md. Ambos existen para evitar que vuelvas a debatir preguntas ya resueltas. Cuando la IA sugiere algo que ya rechazaste, señalas el número de decisión o la lista de aplazados y sigues adelante. Un proyecto maduro puede tener 30 o 40 decisiones bloqueadas, y eso es saludable. Cada una es una moneda que nunca volverás a lanzar al aire.
Si tu proyecto tiene interfaz de usuario, añade un séptimo: DESIGN.md, con tu paleta de colores, tipografía, espaciado y estilo de componentes. Créalo en el momento en que comience el trabajo de UI. Hace para las decisiones visuales lo que CONVENTIONS.md hace para el código.
La fase de planificación es donde se gana o se pierde
Esta es la idea más importante de todo esto, así que léela dos veces. El tiempo que dedicas a planificar no es un gasto extra. Es el tiempo más barato de todo el proyecto. Cada hora de planificación precisa te ahorra muchas horas de codificación, depuración y corrección.
El coder construye exactamente lo que especificas. Si no especificas algo, llena el vacío con una suposición. A veces la suposición está bien. A menudo no lo está, y no lo descubres hasta que estás probando la app y algo se comporta de una manera que nunca quisiste. Cada detalle no especificado es una moneda al aire. Planificar es la forma de dejar de lanzar monedas.
Un deseo no es una especificación
"Agrega un dashboard que muestre el estado del servidor."
"Agrega un dashboard en /dashboard que muestre 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 último acceso. Ordenar por estado, primero los problemas, luego alfabéticamente. Sin servidores: mostrar un estado vacío con un botón 'Conecta tu primer servidor'. Datos con más de 60 segundos de antigüedad: atenuar la tarjeta y mostrar 'Reconectando...'."
La segunda versión es más larga, pero cada minuto que dedicas a escribirla te ahorra una hora de "eso no era lo que quería decir" después. El coder no puede leer tu mente. La especificación es la lectura de la mente, hecha con anticipación.
Recorre 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 inicio de sesión. ¿Qué ve? Ingresa su correo electrónico y contraseña y hace clic en iniciar sesión. ¿Qué pasa? Estado de carga. Las credenciales son correctas, llega al dashboard. ¿Pero qué pasa si las credenciales son incorrectas? ¿Cómo se ve el error? ¿Y si olvidaron 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 bifurcación, y cada bifurcación es algo que el coder tiene que construir. Recorre el camino durante la planificación y cada bifurcación entra en el brief y se construye correctamente de una vez. Omítelo y descubres las bifurcaciones una a una durante las pruebas, cada una como una sorpresa, cada una como un parche.
"¿Qué pasa si..." es la pregunta que previene errores
La mayoría de los errores viven en los casos que nadie pensó. Todos especifican el camino feliz. Los errores están en los bordes. Para cada funcionalidad, pregunta: ¿Qué pasa si la entrada está vacía? ¿Con formato incorrecto o absurdamente grande? ¿Y si la solicitud de red falla? ¿Y si el usuario hace esto dos veces rápido? ¿Y si dos usuarios lo hacen al mismo tiempo? ¿Y si los datos aún no existen? ¿Y si les falta permiso? ¿Y si un servicio externo está caído?
No necesitas ser programador para hacerlas. Son preguntas de producto, no técnicas. Un recurso útil: cuando termines un brief, devuélvelo a la sesión del arquitecto y pregunta "¿qué casos extremos o modos de fallo no estoy considerando?" Encontrar los vacíos ahora es gratis. Encontrarlos en producción es costoso.
Incorpora escapes de emergencia en cada instrucción
Esta es la configuración con mayor impacto que puedes hacer, y es más importante si no eres programador. Un escape de emergencia es una instrucción permanente que le dice a la IA qué hacer cuando se encuentra con algo incierto, en lugar de adivinar.
El modo de fallo predeterminado de cualquier coder de IA es este: encuentra algo ambiguo, hace una suposición que suena razonable y sigue adelante. La suposición es invisible para ti hasta que aparece más tarde como un error. Los escapes de emergencia convierten esas suposiciones silenciosas en preguntas que tú puedes responder. Ponlos en tu CLAUDE.md y en las instrucciones de tu proyecto para que se apliquen a cada sesión:
"Si no entiendes algo, pregunta. No supongas."
El fundamental. Anula la tendencia del coder a llenar vacíos en silencio. La pregunta te cuesta 30 segundos. La suposición incorrecta te cuesta una sesión de depuración.
"Si hay que tomar una decisión y yo no la he especificado, detente y ponla sobre la mesa. Explica las opciones, los pros y contras, y dame tu recomendación."
Este es el escape de emergencia específico para no programadores. No necesitas entender los detalles técnicos. Necesitas las opciones presentadas, los compromisos en lenguaje claro y una recomendación que puedas aceptar o rechazar. Tú sigues siendo quien toma las decisiones sin necesidad de ser el ingeniero.
"Si una solicitud entra en conflicto con una decisión bloqueada o el alcance actual, señálalo antes de proceder."
Protege tu arquitectura y cronograma del desvío. Si accidentalmente pides algo que contradice una decisión anterior, 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 pedido."
Quieres un colaborador, no un ejecutor de órdenes. Si la IA ve un hueco en tu lógica, quieres que lo señale mientras todavía es barato de corregir.
El patrón en todos estos: 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 necesidad de entender cada línea de código.
El ciclo de desarrollo
Planificar (sesión del arquitecto)
Describes lo que quieres. El arquitecto hace preguntas aclaratorias, verifica las decisiones y el alcance existentes, y produce un brief: una especificación precisa con el comportamiento completo, cada bifurcación de "qué pasa si", los detalles de diseño y lo que NO hay que hacer.
Ejecutar (coder)
Entrega el brief al coder. Lee los documentos, lee el brief e implementa. Un brief por sesión. Los escapes de emergencia demuestran su valor aquí: un coder bien instruido se detiene y pregunta cuando el brief deja algo abierto.
Revisar (de vuelta en la sesión del arquitecto)
Pide al arquitecto que verifique lo construido contra el brief y el documento de arquitectura. "Lee los archivos modificados y confirma que la arquitectura coincide con ARCHITECTURE.md." Las afirmaciones estructurales se verifican contra los archivos reales.
Actualizar los documentos
El paso que la mayoría omite, y el que hace que la siguiente sesión sea productiva en lugar de confusa. Las nuevas decisiones van en 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 arruinan los proyectos de vibe coding
Los documentos toman unas pocas horas. Omitirlos cuesta semanas de retrabajos cuando el coder construye algo que no coincide con una visión que nunca pusiste por escrito.
El coder implementa, no hace arquitectura. Las decisiones arquitectónicas pertenecen a la sesión de planificación donde puedes evaluar compromisos y registrar el resultado. Si el coder se encuentra con una pregunta arquitectónica en mitad de una tarea, debe detenerse y preguntar, no adivinar.
Los documentos desactualizados son peores que ningún documento porque crean una falsa confianza. Si el código diverge de los documentos, la siguiente sesión produce instrucciones basadas en una realidad que ya no existe.
Una sesión que lleva horas ha acumulado contexto, pero también ruido. La relación señal-ruido se degrada. Empieza de nuevo, deja que los documentos lleven el contexto y sigue adelante.
"El coder dice que funciona" no es verificación. Lee los archivos. Revisa la estructura. Detectar problemas en la revisión es mucho más barato que detectarlos en producción.
Si tu brief describe lo que pasa cuando todo funciona y no dice nada sobre fallos o casos extremos, el coder inventa su propio manejo. De cualquier manera, obtienes un comportamiento que no elegiste.
Una nota sobre el costo, y por qué vale la pena
Este flujo de trabajo usa más tokens que un enfoque de sesión única. El arquitecto lee documentos, produce briefs, revisa código. El coder lee documentos, ejecuta, confirma. Hay duplicación inherente.
El compromiso vale la pena. La alternativa, una sola sesión larga intentando hacer todo, produce código que se aleja de tu visión, toma decisiones no documentadas y no puede retomarse cuando la sesión termina. El costo del retrabajo por una mala implementación supera con creces el costo de los tokens adicionales invertidos en planificación y revisión. Y a medida que tus documentos maduran, el costo en tokens por tarea en realidad disminuye, porque los documentos llevan más contexto y las conversaciones requieren menos idas y vueltas.
Empezar en 30 minutos
No necesitas construir toda la estructura perfectamente el primer día. Necesitas el esqueleto. Aquí está el camino más rápido:
- Crea un repositorio de GitHub con una carpeta docs/
- Escribe CLAUDE.md: qué es el proyecto, el stack, reglas básicas y las instrucciones de escape de emergencia (15 min)
- Escribe SCOPE.md: qué es la v1, qué se aplaza (5 min)
- Escribe un ARCHITECTURE.md básico: componentes y cómo se conectan (10 min)
- Crea DECISIONS.md, CONVENTIONS.md y OPEN_ITEMS.md vacíos con un ejemplo de entrada cada uno
- Si tu proyecto tiene UI, pide a la sesión de planificación que proponga una paleta y tipografía, luego guárdala en DESIGN.md
- Crea un proyecto en Claude, pega tus instrucciones (incluidos los escapes de emergencia) y sube los documentos
- Configura tu coder y clona el repositorio
- Inicia tu primera sesión de planificación: "Esto es lo que quiero construir. Recorramos el camino del usuario y luego escribamos el primer brief."
Los documentos serán básicos. Eso está bien. Mejoran con cada sesión, cada decisión, cada hito. La estructura es lo que importa el primer día, no el pulido.
Ese es el secreto completo del vibe coding para construir algo real. No mejores prompts. Una separación disciplinada entre planificación y ejecución, un conjunto duradero de documentos que sobreviven a cualquier sesión individual, e instrucciones permanentes que convierten las suposiciones silenciosas de la IA en decisiones que tú tomas. Haz bien esas tres cosas y podrás construir software mucho más complejo de lo que nadie esperaría, sin escribir el código tú mismo.
¿Construiste algo real? Necesita un lugar confiable donde vivir.
Cuando tu proyecto de vibe coding esté listo para producción, un VPS administrado le da el espacio que necesita para funcionar sin las limitaciones del hosting compartido. Migración gratis, SLA del 500%, totalmente administrado desde 2001. El primer mes desde $2.00.
Ver planes Cloud Cube
