Guía de Vibe Coding v1.0: 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 utilizando 'Vibe Coding'. Los desarrolladores junior con poca experiencia en codificación y los planificadores también pueden producir 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 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 crear en 2-3 líneas, tal como se te ocurra, con 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 interfaz de usuario tú mismo, puedes solicitarlo proporcionando imágenes de 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 de 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 ser servida como una aplicación móvil, configura el Frontend con Flutter. Si es un método que necesita ser instalado 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 de 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 tecnológico detallado de este tipo, 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 un servidor deben incluir la implementación de un panel de administración como opción predeterminada.
• Elementos mínimos a incluir en el panel:
• Verificación de estado del servidor
• Estado de los 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 principales 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 BD. 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 del módulo y su función
5. Entrada/Salida (endpoints de API y formatos de solicitud/respuesta)
6. Estructura de datos utilizada / diseño de tabla (o colección) de la 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 parezca 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 aburre hasta la muerte, 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 de pago de Claude (Pro/Max/Team) o una cuenta de pago 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 aún no has instalado VS Code, 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 opciones en la pantalla de opciones:
3. "Agregar a PATH"
4. "Agregar acción 'Abrir con Code' a los menús contextuales de archivos/directorios"
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 un mensaje 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 de nuevo 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 sirve para dejar un registro de "quién trabajó" en los commits. En PowerShell (Windows) o Terminal (Mac):

git config --global user.name "Tu Nombre" git config --global user.email "tu-email-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 en 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, con 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 marcarla. 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 <> Code → Copia la dirección en la pestaña HTTPS.

6-2. Clonar en 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, apruebalo. (Solo la primera vez).
6. Selecciona una ubicación para guardar el proyecto (por ejemplo, es bueno crear una carpeta Documentos/Proyectos).
7. Cuando termine la clonación, aparecerá 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 ahora es 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 los documentos de planificación en el repositorio es lo mismo que "subir documentos".

1. Haz clic derecho en un espacio vacío del 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.

Traer (pull) 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 crear.

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 Claude GitHub:
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. Al regresar a Claude, la conexión estará completa. 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 tu 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 traigo 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 main directamente, no hay preocupación de que el código existente se rompa. (Grok Build trabaja en la rama main, 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 crear - 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

↓

② Traigo esa rama de tarea a mi PC (VS Code) y la ejecuto/pruebo directamente

↓

③ Si hay un problema → Copio todo el mensaje de error y lo pego en la sesión web

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

↓

Vuelvo a ① para el siguiente módulo

↓

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

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

→ La implementación siempre se basa en main

8. Ramas — Probar en Ramas de Tarea y Fusionar a main para la 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á mi carpeta actualmente.
2. Cómo traer la rama de tarea que Claude subió 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 la rama. (ej., main o claude/feature-login).

8-3. Traer 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 tu 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 ... menú → Obtener (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 el main de tu PC a la última versión:
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 yo 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 son — 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 quien tiene que cruzarla."