Guía de Vibe Coding v1.0: Un manual completo para el desarrollo asistido por IA

Este documento es una guía diseñada para ayudar no solo a programadores experimentados, sino también a no programadores a desarrollar aplicaciones/servicios usando 'Vibe Coding'. Los desarrolladores junior con poca experiencia en programación y los planificadores también pueden obtener resultados estables siguiendo estos pasos.

Principio fundamental: En lugar de hacer que la IA escriba código inmediatamente, es mejor hacer que cree documentos (Design.md, ToDo.md) primero antes de comenzar el desarrollo.

0. Resumen del Flujo General

[1] Solicitar la creación de Concept.md

↓

[2] Crear Design.md (documento de referencia de UI/UX)

↓

[3] Determinar el Stack Tecnológico (Consultar el árbol de decisión a continuación)

↓

[4] Crear ToDo.md (especificaciones técnicas a nivel de módulo + plan de desarrollo)

↓

[5] Crear el repositorio de GitHub y hacer el commit inicial

↓

[6] Pasar la descripción de la app + Design.md + ToDo.md a Claude Code o Grok Build para iniciar el desarrollo

↓

[7] Repetir: Implementar por módulo → Probar → commit/push

1. Concept.md — Prompt para empezar con una idea simple

Comienza describiendo brevemente la aplicación o servicio que quieres hacer en 2-3 líneas, tal como se te ocurra, en el formato: "Quiero hacer algo como esto; por favor, crea un documento Concept.md que detalle los procedimientos y métodos para implementarlo."

Descarga el documento generado y guárdalo como Concept.md.

2. Design.md — Crear documentos de referencia de UI/Diseño primero

Si la aplicación tiene una interfaz de usuario, es bueno escribir Design.md primero. Es decir, si hay un servicio o aplicación que quieras usar como referencia, o si ya sabes cómo diseñar la UI tú mismo, puedes solicitarlo proporcionando imágenes de los diseños trabajados en Figma, etc.

Método

• Elige un sitio web realmente implementado que te guste. (por ejemplo, linear.app, stripe.com, toss.im, etc.)
• Indica a Claude o Grok que "Analice la estructura de diseño, paleta de colores, tipografía, márgenes/espaciado y estilos de componentes de ese sitio y lo organice en Design.md."

Ejemplo de Prompt

Analiza el diseño de https://linear.app y escribe un documento Design.md. Debes incluir los siguientes elementos: 1. Estructura general del diseño (ubicación de Header/Sidebar/Body/Footer) 2. Paleta de colores (colores Primario, Secundario, Fondo, Texto en códigos HEX) 3. Tipografía (tipos de fuente, sistema de tamaños, pesos) 4. Reglas de márgenes y espaciado (escala de espaciado) 5. Estilos para componentes principales como botones, tarjetas y formularios de entrada 6. Soporte para modo oscuro y mapeo de colores

Consejos

• Si tienes sentido del diseño, como el contenido del Design.md generado está todo descrito en lenguaje natural, puedes leerlo y modificarlo/refinarlo directamente en la dirección que desees. Este documento se convierte en el estándar para todas las implementaciones de UI posteriores.
• Si solo dices "Hazlo como este sitio", los resultados variarán cada vez. Debes fijarlo con un documento para mantener la consistencia.

2. Árbol de Recomendación para la Decisión del Stack Tecnológico

Determina el stack primero según el tipo de servicio que intentas crear.

Principios Comunes del Servidor (Backend)

• Debe ser posible instalar y ejecutar directamente desde la CLI en cualquier entorno local.
• El lenguaje/entorno de ejecución debe ser Node.js o Python.
• Utiliza herramientas verificadas para una implementación y soporte estables en todos los SO para paquetes/entornos de ejecución:
• Python → uv
• Node.js → npm

Criterios de Selección de Base de Datos

Instrucciones Detalladas del Prompt (Si tienes conocimientos de desarrollo)

Este proyecto es una aplicación web. Configura el Frontend con React, y debe ser posible probarlo inmediatamente con npm run dev de forma local, con una estructura que permita una implementación estable. Configura el Backend con Node.js, y como se necesita una base de datos relacional, usa MariaDB. Incluye un script de configuración que se pueda instalar/ejecutar directamente a través de la CLI en el entorno de desarrollo local. Revisa este contenido y el documento Concept.md para escribir un documento ToDo.md para la implementación técnica detallada.

• Procede adjuntando el documento Concept.md con este prompt o copiando y pegando el contenido del documento Concept.md.

¿Pero qué pasa si soy un no desarrollador que no sabe lo anterior?

Simplemente da instrucciones integradas como esta:

No estoy seguro de cómo ejecutar este proyecto, así que por favor recomienda una forma. Recomienda si es mejor una aplicación web, si un método de instalación en el SO es más fácil de verificar durante el desarrollo, o si es mejor construirla como una aplicación móvil. Si se puede mostrar en un navegador web, configura el Frontend con React; si necesita servirse como una aplicación móvil, configura el Frontend con Flutter. Si es un método que necesita instalarse localmente, configúralo usando npm o uv, que se pueden implementar e instalar fácilmente a través de la CLI. Establece una estructura que permita una implementación estable. No estoy seguro si se necesita un Backend, pero establece una estructura estable para Node.js o implementación/instalación. Si se necesita una BD, usa MariaDB si se requiere una relacional, y si es solo una BD de clave-valor, usa AWS DynamoDB localmente para el desarrollo y configúralo para una fácil implementación en AWS. Si es un formato que se puede instalar/ejecutar directamente a través de la CLI en un entorno de desarrollo local, incluye todos los scripts de configuración. Recomienda un stack técnico tan detallado, revisa este contenido y el documento Concept.md, y escribe un documento ToDo.md para la implementación técnica detallada.

3. Panel de Administración — Esencial si hay un servidor

Puede que no sepas si es un servicio con servidor, pero generalmente es bueno construir uno para que el desarrollador pueda comprender personalmente el estado operativo y el progreso de toda la aplicación.

• Los proyectos con servidor deben incluir la implementación de un panel de administración como valor predeterminado.
• Elementos mínimos a incluir en el panel:
• Verificación de estado del servidor
• Estado de datos clave (métricas principales como número de suscriptores, número de casos procesados, etc.)
• Errores/registros recientes
• Progreso del procesamiento de tareas principales (lotes, colas, etc.)

Ejemplo de Prompt

Si este servicio incluye un servidor, incluye un panel de administración en el plan de desarrollo. El panel debe permitir verificar el estado del servidor, las métricas clave y los registros/errores recientes. Establece la cuenta de administrador predeterminada como 'admin' con contraseña '12345', e incluye la capacidad de cambiar la contraseña en el panel de administración. Revisa ToDo.md e incluye esto en el plan de desarrollo si se considera necesario.

4. Finalización de ToDo.md — Plan de Desarrollo a Nivel de Módulo

La base de la programación es la modularización. Si agregas contenido a ToDo.md para subdividir en módulos antes de escribir código, se puede crear una buena arquitectura para el mantenimiento futuro.

Ejemplo de Prompt

Revisa el documento ToDo.md y verifica si está bien escrito según la guía a continuación, y modifica/complementa cualquier parte que falte. Requisitos de ToDo.md: 1. Diseña todo el sistema para que esté modularizado con diseño orientado a objetos. 2. Especifica claramente el rol, la entrada/salida y la estructura de datos de cada módulo para garantizar el máximo encapsulamiento. 3. Crea una secuencia de implementación como una lista de casillas de verificación (comenzando desde los módulos sin dependencias). 4. Incluye el diseño del esquema de la base de datos. 5. Describe cuándo y cómo las personas no técnicas pueden probar fácilmente.

Elementos a verificar en el ToDo.md completado:

1. Resumen del Proyecto (un párrafo)
2. Stack Tecnológico Confirmado (Resultado del árbol de decisión en el paso 2)
3. Lista de módulos y especificaciones técnicas detalladas para cada módulo (Las personas no técnicas pueden encontrar esto difícil de entender)
4. Nombre y rol del módulo
5. Entrada/Salida (puntos finales de API y formatos de solicitud/respuesta)
6. Estructura de datos utilizada / diseño de tabla (o colección) de BD
7. Relaciones de dependencia con otros módulos
8. Secuencia de implementación (en forma de casilla de verificación, en orden de dependencia)
9. Verifica si cada método de prueba está escrito a un nivel que pueda entender.

Importante

• No es necesario que leas y revises el ToDo.md generado tú mismo. Aunque parece que las cosas saldrán bien si te preparas perfectamente, el núcleo de Vibe Coding es el proceso de crear un resultado primero y luego modificarlo gradualmente para obtener lo que deseas—esa es la parte más valiosa y divertida.

Parte Práctica: Configuración del Entorno → GitHub → Inicio del Desarrollo con Claude Code

Escrito para que incluso aquellos que instalan herramientas de desarrollo por primera vez puedan seguirlo.

• Sin embargo, si parece demasiado complejo y no sabes por qué deberías usarlo y te aburres hasta morir, por favor ve a escuchar una conferencia gratuita en el siguiente enlace primero.

https://nomadcoders.co/git-for-beginners

5. Preparación del Entorno de Desarrollo (Instala solo 2 cosas)

Instalaremos dos cosas.

Y necesitas una cuenta de GitHub. Regístrate gratis en https://github.com (completa la verificación por correo electrónico). Usar Claude Code o Grok Build requiere un plan pago de Claude (Pro/Max/Team) o una cuenta paga de Grok.

5-1. 🪟 Pasos de Instalación para Usuarios de Windows

① Instalar Git

1. Ve a https://git-scm.com/download/win en tu navegador → La descarga comienza automáticamente.
2. Ejecuta el instalador descargado.
3. Aparecen muchas opciones de instalación; sigue haciendo clic en "Siguiente" con todos los valores predeterminados.
4. Sin embargo, cuando aparezca la pantalla "Elegir el editor predeterminado", es bueno seleccionar "Usar Visual Studio Code como editor predeterminado de Git" (si no has instalado VS Code aún, el valor predeterminado está bien).
5. Verifica la instalación: Ejecuta PowerShell desde el menú Inicio y escribe:

git --version

→ Si aparece una versión como git version 2.xx.x, es un éxito. Si no, intenta cerrar y volver a abrir PowerShell.

② Instalar VS Code

1. Ve a https://code.visualstudio.com → Haz clic en Descargar para Windows.
2. Ejecuta el instalador → Sigue haciendo clic en "Siguiente". Sin embargo, marca estas dos en la pantalla de opciones:
3. "Agregar a PATH"
4. "Agregar acción 'Abrir con Code' a los menús contextuales de archivo/directorio"
5. Ejecuta VS Code después de la instalación. Si aparece una notificación de instalación del paquete de idioma coreano en la primera pantalla, puedes instalarlo.

5-2. 🍎 Pasos de Instalación para Usuarios de Mac

① Instalar Git

1. Abre Terminal: Cmd + Espacio → Escribe "Terminal" → Enter.
2. Escribe:

git --version

1. Si la versión aparece inmediatamente, ya está instalado → Ve a ②. Si aparece una ventana emergente de guía de instalación ("Herramientas de desarrollo de línea de comandos..."), haz clic en "Instalar" y espera. (Esta es la instalación de Git).
2. Verifica nuevamente con git --version después de completar.

② Instalar VS Code

1. Ve a https://code.visualstudio.com → Haz clic en Descargar para macOS.
2. Descomprime el archivo descargado y arrastra Visual Studio Code.app a la carpeta Aplicaciones. (¡Importante! No lo uses directamente desde la carpeta Descargas).
3. Ejecuta VS Code desde Aplicaciones.

5-3. (Común) Registrar Mi Nombre en Git — Solo la Primera Vez

Esta configuración es para dejar un registro de "quién trabajó en ello" en los commits. En PowerShell (Windows) o Terminal (Mac):

git config --global user.name "Tu Nombre" git config --global user.email "tu-correo-de-github@ejemplo.com"

Ingresa el mismo correo electrónico que usaste para registrarte en GitHub.

6. Crear un Repositorio de GitHub y Conectarlo a Mi PC con VS Code

Piensa en un "Repositorio" como una carpeta en la nube que contiene un proyecto. El flujo es: Crear un repositorio vacío en el sitio web de GitHub → Clonarlo a mi PC con VS Code → Subir documentos de planificación → Conectar ese repositorio a Claude Code web.

6-1. Crear un Repositorio en el Sitio Web de GitHub

1. Inicia sesión en https://github.comhttps://github.com/).
2. Haz clic en el botón + en la esquina superior derecha → Nuevo repositorio.
3. Ingresa lo siguiente:
4. Nombre del repositorio: Nombre del proyecto (en inglés, guiones en lugar de espacios. ej., mi-primera-app)
5. Selecciona Privado (¡Los proyectos de empresa deben ser Privados!)
6. Marca la casilla "Agregar un archivo README" ✅ ← Los principiantes deben marcar esto. Esto hace que el siguiente paso (clonar) sea más simple.
7. Haz clic en Crear repositorio.
8. En la página del repositorio creado, haz clic en el botón verde <> Código → Copia la dirección en la pestaña HTTPS.

6-2. Clonar a Mi PC con VS Code

1. Ejecuta VS Code.
2. Ctrl + Shift + P (Cmd + Shift + P en Mac) → Se abre la paleta de comandos.
3. Escribe clone → Selecciona "Git: Clonar".
4. Pega la dirección del repositorio copiada y presiona Enter.
5. También puedes seleccionar "Clonar desde GitHub" → Si el navegador se abre y solicita inicio de sesión/autorización de GitHub, aprueba. (Solo la primera vez).
6. Selecciona una ubicación para guardar el proyecto (por ejemplo, es bueno crear una carpeta Documentos/Proyectos).
7. Cuando la clonación termine, aparece una notificación "Abrir" en la esquina inferior derecha → Haz clic en ella.
8. Si ves README.md en el explorador de archivos a la izquierda, ¡éxito! 🎉 Esta carpeta es ahora la carpeta de trabajo conectada entre mi PC y GitHub.

6-3. Subir Documentos de Planificación — Concept.md, Design.md, ToDo.md

Claude Code web puede leer archivos dentro del repositorio. Por lo tanto, poner documentos de planificación en el repositorio es lo mismo que "subir documentos".

1. Haz clic derecho en un espacio vacío en el explorador de archivos de VS Code → Nuevo archivo → Ingresa el nombre Concept.md.
2. Pega la descripción de la aplicación que preparaste y guarda (Ctrl+S / Cmd+S).
3. Crea e inserta los archivos Design.md (si hay UI) y ToDo.md de la misma manera.
4. Ahora súbelo a GitHub (commit & push) — usando el método en 6-4.

6-4. Hacer Commit y Push en VS Code — Solo con el Ratón

1. Cuando guardas un archivo, aparece una insignia numérica en el icono con forma de rama (Control de código fuente) a la izquierda de VS Code.
2. Haz clic en ese icono → Verás una lista de archivos modificados.
3. En el cuadro de entrada de mensaje en la parte superior, escribe una línea sobre lo que hiciste. (ej., Documentos de planificación añadidos).
4. Haz clic en el botón ✔ Commit → Guardado completado en mi PC.
5. Si aparece una ventana emergente "No hay cambios preparados", haz clic en "Sí" para hacer commit de todo.
6. Luego haz clic en el botón Sincronizar cambios → Subida (push) a GitHub completada.
7. Actualiza el repositorio en el sitio web de GitHub para ver el Concept.md que acabas de subir. Ahora Claude Code web también puede leer este documento.

Hacer Pull (descargar) también se hace en la misma pantalla: Si hay cambios que Claude subió en la nube, el botón Sincronizar cambios manejará tanto la descarga como la subida.

7. Conectar el Repositorio a Claude Code Web e Iniciar el Desarrollo

Ahora abre Claude Code web en tu navegador y conecta el repositorio de GitHub que acabas de hacer.

7-1. Conectar Claude Code Web ↔ Repositorio de GitHub (Solo la Primera Vez)

1. Accede a https://claude.ai/code → Inicia sesión con tu cuenta de Claude.
2. Cuando accedas por primera vez, aparece una guía Conectar GitHub → Sigue la guía.
3. Serás redirigido a la página de GitHub, y aparecerá la pantalla de instalación de la Aplicación de GitHub de Claude:
4. Selecciona tu cuenta de GitHub (u organización).
5. Selecciona el rango de acceso: Se recomienda seleccionar "Solo repositorios seleccionados" y especificar el repositorio creado en 6-1.
6. Haz clic en Instalar / Autorizar.
7. Regresar a Claude completa la conexión. Si aparece la pantalla de configuración del Entorno, déjalo en Predeterminado.
8. Al iniciar una nueva sesión (tarea), selecciona tu repositorio de la lista de selección de repositorios, ingresa un prompt y la tarea comienza.

7-2. Entender Cómo Funcionan Claude Code y Grok Build Web (¡Importante!)

Claude Code y Grok Build web funcionan en una computadora virtual en la nube, no en mi PC. El flujo es:

① Yo ingreso un prompt

↓

② Claude Code/Grok Build clona mi repositorio en la nube y escribe código

↓

③ Sube el resultado a GitHub como una "nueva rama de tarea"

↓

④ Yo hago pull de esa rama a mi PC para probar, o verifico los cambios a través de una Pull Request en GitHub

↓

⑤ Si me gusta, fusiono en main.

• Como siempre sube los resultados a una nueva rama sin tocar la rama principal directamente, no hay preocupación de que el código existente se rompa. (Grok Build trabaja en la rama principal, pero se puede deshacer, así que no te preocupes por los errores).

7-4. Prompt de Inicio del Desarrollo

Una vez que los tres documentos (Concept.md / Design.md / ToDo.md) estén listos en main, finalmente inicia el desarrollo en una nueva sesión.

Desarrolla este proyecto. Procede basándote en los siguientes documentos en el repositorio: - Concept.md: Descripción de la aplicación a realizar - ToDo.md: Plan de desarrollo a nivel de módulo (implementar en este orden) - Design.md: Estándares de diseño (toda la UI sigue este documento)

Reglas de Trabajo: 1. Procede un módulo a la vez según el orden de implementación en ToDo.md. 2. Cuando se complete una unidad comprobable, házmelo saber cómo ejecutarla/probarla en mi PC local a través de README o respuesta. Como soy un no desarrollador, explícalo bien como si enseñaras a un principiante. 3. Marca los elementos completados con una marca de verificación en ToDo.md. 4. Dime el nombre de la rama de tarea y haz push con un mensaje de commit fácil de recordar. 5. Si hay partes poco claras, no adivines; pregúntame.

7-5. Ciclo Repetido Durante el Desarrollo

① Claude Code web implementa un módulo en una rama de tarea → push

↓

② Haz pull de esa rama de tarea a mi PC (VS Code) y ejecútala/pruebala directamente

↓

③ Si hay un problema → Copia todo el mensaje de error y pégalo en la sesión web

Si no hay problema → "Bien, continúa con el siguiente desarrollo"

↓

Regresa a ① para el siguiente módulo

↓

④ Una vez que todas las funciones estén completas y las pruebas pasadas

→ Fusiona en la rama main a través de una Pull Request

→ La implementación siempre se basa en main

8. Rama — Probar en Ramas de Tarea y Fusionar a main para Implementación

8-1. ¿Qué es una rama?

• Rama main = La vitrina del producto terminado que siempre funciona bien. La implementación siempre se basa en main.
• Rama de tarea (ej., claude/feature-login) = Un sitio de construcción hecho copiando main. Puedes construir y romper cosas aquí tanto como quieras; main está a salvo.

Claude Code web siempre crea una nueva rama de tarea y sube los resultados. Por lo tanto, solo hay tres cosas que necesitas saber:

1. Cómo verificar en qué rama está actualmente mi carpeta.
2. Cómo hacer pull de la rama de tarea subida por Claude a mi PC para probar.
3. Cómo fusionar en main e implementar cuando termines.

8-2. Verificar en Qué Rama Estás

• Mira la barra de estado en la parte inferior izquierda de la pantalla de VS Code. El nombre de la rama se muestra junto al icono de rama. (ej., main o claude/feature-login).

8-3. Hacer Pull de las Ramas de Tarea Creadas por Claude Code/Grok Build a Mi PC para Probar

Cuando Claude Code web dice "He subido a la rama OO", trae esa rama a mi PC para probar. Grok Build tiene un botón 'Push to Github' en la esquina superior derecha de la pantalla web, así que presiona este botón para subir.

Con VS Code (Solo con el Ratón):

1. Haz clic en el nombre de la rama en la parte inferior izquierda → Se abre la lista de ramas.
2. Si la nueva rama no es visible, ejecuta el menú ... → Fetch en la pestaña Control de código fuente e inténtalo de nuevo.
3. Selecciona la rama de tarea de Claude que comienza con origin/claude/... de la lista → Tu carpeta cambia al estado de esa rama.

8-4. Fusionar en main Cuando Termines — Pull Request

Si las funciones están completas y las pruebas pasaron en la rama de tarea, fusiona en main a través de una Pull Request (PR) en el sitio web de GitHub.

1. Accede a tu repositorio en GitHub → Haz clic en la pestaña Pull requests.
2. Haz clic en la PR que Claude hizo. Si no hay ninguna, New pull request → base: main, compare: selecciona la rama de tarea → Create pull request.
3. Haz clic en Merge pull request → Confirm merge → ¡Reflejado en main!
4. Actualiza tu PC con la última versión de main:
5. Haz clic en el nombre de la rama en la parte inferior izquierda de VS Code → Selecciona main → Sincronizar cambios en la pestaña Control de código fuente.

9. Consejos para Prompts (Comunes)

La calidad de Vibe Coding es proporcional a la calidad de los prompts.

1. Especifica lo que NO hacer — "No modifiques el código arbitrariamente hasta que lo apruebe", "No agregues librerías, usa solo el stack existente."
2. Un módulo a la vez — La calidad disminuye si pides toda la aplicación en un solo prompt. Pide en partes pequeñas según el orden de ToDo.md.
3. Pega los errores tal como están — No resumas los mensajes de error; copia toda la salida del terminal.
4. Deja que Claude pregunte si es ambiguo — Incluye "Si hay partes poco claras, no adivines; pregúntame" en el prompt.
5. Comunícate basándote en documentos — "Como dije antes" ❌ → "Según el diseño de Design.md" ✅. Los documentos en el repositorio son mucho más estables que la memoria de la conversación.

Fin.

Como dijo el antiguo Morfeo:

"Neo. Solo puedo mostrarte la puerta. Tú eres el que tiene que atravesarla."