¿Qué es cada cosa?
Antes de instalar nada, conviene entender qué hace cada herramienta y para qué sirve. Esta parte es teoría en palabras simples — no hay pasos que seguir todavía.
Node.js
Node.js es un programa que le permite a la computadora entender y ejecutar código JavaScript fuera de un navegador web. En la práctica, casi nunca van a "usar" Node.js directamente: es una pieza que otras herramientas necesitan para funcionar por debajo, entre ellas Claude Code, los paquetes de npm y los Skills.
Piénsalo como el motor de un auto: no interactúas con el motor directamente, pero sin él el auto no arranca.
Claude Code
Es el asistente de inteligencia artificial con el que van a escribir y modificar código. Se le puede hablar en español normal — por ejemplo "agrégale un formulario de contacto a esta página" — y él escribe el código, instala lo que haga falta, y puede conectarse a otras herramientas por ustedes.
Se puede usar de dos formas: desde la Terminal o como una extensión dentro de Visual Studio Code — que es como lo está usando el equipo actualmente.
Visual Studio Code (VS Code)
Es el programa donde se ve y se edita el código. Es gratuito y es el estándar de la industria. Dentro de VS Code se instala la extensión de Claude Code, se abre la terminal, y se ven los cambios que se van haciendo al proyecto en el panel de Source Control.
Git
Es un sistema que guarda un historial de todos los cambios que se hacen a un proyecto, como un "control de cambios" muy detallado. Permite que varias personas trabajen en el mismo proyecto sin pisarse el trabajo, y permite regresar a una versión anterior si algo se rompe. Git funciona en la computadora de cada quien (localmente).
GitHub
Es "la nube" del proyecto: un lugar en internet donde vive una copia del código y de todo su historial de cambios (el repositorio, o "repo"). Cada quien tiene una copia del proyecto en su computadora (clonada desde GitHub) y, cuando termina un cambio, lo sube (push) a GitHub para que los demás lo vean y lo bajen (pull) a su propia copia.
Tip: Repositorio (o "repo") es simplemente el nombre que se le da a la carpeta del proyecto una vez que está siendo controlada por Git.
Los Skills (habilidades) de Claude Code
Son paquetes de conocimiento especializado que se le instalan a Claude Code para que haga mejor una tarea específica. Por ejemplo, el Skill UI/UX Pro Max le da a Claude Code una base de datos de estilos visuales, paletas de colores y buenas prácticas de diseño, para que las páginas que construya se vean más profesionales.
Un Skill no reemplaza a Claude Code: es un complemento que se activa automáticamente cuando la tarea lo amerita.
Vercel
Es la plataforma donde se publica el sitio web para que cualquier persona pueda visitarlo desde internet, usando el mismo repositorio que está en GitHub. Cada vez que se sube un cambio a GitHub, Vercel puede actualizar automáticamente la versión publicada.
Importante: Vercel no tiene habilitado el protocolo SMTP (el que se usa para enviar correos). Si el sitio necesita un formulario que envíe correos, hace falta un dominio propio con SMTP habilitado, o un servicio externo como Brevo API. Ver sección 3.12.
Variables de entorno y el archivo .env
Cuando un proyecto necesita una contraseña, una clave de API o cualquier dato sensible, esa información nunca se escribe directamente dentro del código HTML o JavaScript, porque cualquier persona que vea el código la vería también.
En su lugar, esos datos se guardan en un archivo aparte
llamado .env, que no se
sube a GitHub. El código simplemente "pregunta" por esos datos cuando los necesita, sin mostrarlos nunca.
SMTP y servicios de correo (Brevo)
SMTP es el protocolo que usan los servidores para enviar correos electrónicos. Cuando un sitio tiene un formulario de contacto que debe enviar un correo, necesita conectarse a un servicio que hable SMTP, ya sea a través de un dominio propio o de un proveedor externo como Brevo, que ofrece esto mediante su propia API.
Instalación y configuración
Esta parte se hace una sola vez por computadora. Está pensada para Mac. Conviene seguir el orden: cada paso depende un poco del anterior.
Antes de empezar: una carpeta por proyecto
Claude Code y Git leen y escriben archivos dentro de la carpeta donde se abren. Por eso conviene crear una carpeta distinta para cada proyecto (cada cliente, cada campaña, cada sitio).
~/Proyectos
├─ ClienteA-Landing
├─ ClienteB-Rebranding
└─ Turbo-Websites-App
Instalar Node.js
- 1
Entrar a nodejs.org desde el navegador.
- 2
Descargar la versión LTS — es un archivo
.pkg. - 3
Abrir el archivo descargado y seguir el instalador, igual que con cualquier otro programa de Mac.
- 4
Confirmar en la Terminal escribiendo
node -v. Si aparece un número comov22.x.x, quedó instalado.
Instalar Claude Code (y el problema de permisos)
La primera vez que probamos instalar Claude Code con el comando clásico de npm, la instalación falló: Node parecía "no detectar permisos". Esto tiene nombre y es un problema muy común en Mac — se llama error EACCES.
¿Por qué pasa y sí tiene solución? Pasa porque
npm install -g intenta escribir en una
carpeta del sistema que la cuenta de usuario no tiene permiso de modificar. No es algo que hayan hecho
mal — no hace falta usar sudo para
"forzarlo": eso puede complicar más las cosas.
Opción A — Recomendada (la que usa el equipo hoy): instalar la extensión de Claude Code dentro de VS Code (sección 2.4). La extensión gestiona su propia instalación por dentro y no depende de permisos de npm.
Opción B — Alternativa, por si alguna vez necesitan Claude Code fuera de VS Code, usar el instalador nativo de Anthropic:
curl -fsSL https://claude.ai/install.sh | bash
Después, cerrar y reabrir la Terminal (o source ~/.zshrc) y confirmar con:
claude doctor
Importante: nunca agreguen la palabra
sudo antes de un comando de instalación.
Instalar VS Code + extensión de Claude Code
- 1
Entrar a code.visualstudio.com → "Download for Mac".
- 2
Abrir el
.zipy arrastrar VS Code a Aplicaciones. - 3
Abrir VS Code desde Aplicaciones.
- 4
Ir a Extensiones (Cmd+Shift+X).
- 5
Buscar "Claude Code" e instalar la extensión oficial de Anthropic.
- 6
Iniciar sesión con la cuenta de Claude cuando lo pida (se abre el navegador, 30 segundos).
Crear cuenta de GitHub
- 1
Entrar a github.com.
- 2
Clic en "Sign up" y seguir los pasos.
- 3
Confirmar el correo cuando GitHub lo pida.
Configurar Git por primera vez
Antes de hacer cualquier commit, Git necesita saber el nombre y el correo de la persona que está trabajando. Esto se hace una sola vez por computadora:
git config --global user.name "Tu Nombre"
git config --global user.email "tu-correo@ejemplo.com"
El correo debe ser el mismo con el que se creó la cuenta de GitHub.
Crear un proyecto nuevo
- 1
Crear una carpeta nueva y vacía en el Finder, con el nombre del proyecto.
- 2
Abrir VS Code.
- 3
Arrastrar la carpeta directamente sobre la ventana de VS Code — se abre automáticamente como proyecto activo.
Clonar un proyecto existente desde GitHub
- 1
En GitHub, copiar la URL desde el botón verde "Code" → HTTPS.
- 2
En VS Code, abrir una terminal dentro del proyecto.
- 3
Escribir
git cloney pegar la URL.
Importante — Xcode Command Line Tools: en Mac,
la primera vez que se usa git puede
aparecer una ventana pidiendo instalarlas. Es normal — basta con aceptar, o correr
xcode-select --install, esperar (puede
tardar varios minutos) y reintentar el git clone.
Si alguien cambia de cuenta
Hay que actualizar la sesión en tres lugares:
- En GitHub.com (cerrar sesión y entrar con la otra cuenta).
- En VS Code (ícono de cuenta, abajo a la izquierda).
- En la configuración de Git, repitiendo el comando de la sección 2.6.
Cómo se trabaja, día a día
Con todo instalado, esta es la parte que van a usar todos los días: escribir pedidos a Claude Code, subir cambios a GitHub y publicar el sitio en Vercel.
Cómo escribir prompts para Claude Code
Un "prompt" es la instrucción que se le escribe a Claude Code en su chat. Mientras más clara y específica sea, mejor va a ser el resultado.
- Decir qué se quiere lograr, no solo qué archivo tocar.
- Si algo no debe cambiar, decirlo explícitamente.
- Pedir que explique lo que hizo, o un concepto antes de aplicarlo.
- Si el resultado no es el esperado, corregirlo en el mismo chat.
Prompt vago
"edita el archivo index.html"
Prompt claro
"agrega un formulario de contacto que envíe el mensaje por correo, sin tocar los colores del navbar"
Instalar y usar un Skill (ej. UI/UX Pro Max)
Se instala en dos pasos: instalación global (una sola vez por computadora) e inicialización por proyecto (una vez por cada proyecto nuevo).
Paso 1 — instalación global
npm install -g ui-ux-pro-max-cli
Paso 2 — inicializar en el proyecto
uipro init --ai claude
El comando del Paso 2 se repite cada vez que quieran usar el Skill en un proyecto nuevo. El del Paso 1 no se vuelve a repetir.
Si npm da error de permisos (el mismo EACCES de la sección 2.3), pidan directamente a Claude Code: "instala el skill UI/UX Pro Max".
Instalar paquetes de npm a través de Claude Code
No hace falta saber el comando exacto: basta con pedírselo a Claude Code, por ejemplo "instala framer-motion en este proyecto", y él corre el comando necesario.
Subir un proyecto nuevo a GitHub por primera vez
- 1
Inicializar Git:
git init - 2
Guardar el primer cambio.
git add .
git commit -m "Primer commit"
- 3
En VS Code, panel de Source Control → botón "Publish Branch". Se recomienda publicarlo como repositorio privado.
Subir cambios del día a día desde VS Code
El ícono de Source Control en la barra lateral parece una rama que se bifurca — es distinto del ícono de archivos:
- 1
Clic en Source Control. Ahí se ve la lista de archivos que cambiaron.
- 2
Escribir un mensaje corto, o usar el ícono de GitHub Copilot para generarlo automáticamente.
- 3
Clic en "Commit" (✓).
- 4
Clic en "Sync Changes" o "Push".
Recomendaciones para nombrar los commits
- Modo imperativo y presente: "agrega formulario de contacto", no "agregado".
- Ser específico: "corrige contraste del botón de menú" en vez de "fix".
- Un commit, un cambio.
- Si el mensaje de GitHub Copilot ya describe bien el cambio, está perfecto usarlo tal cual.
Push y Pull: lo local contra la nube
Cada persona tiene una copia del proyecto en su computadora (lo local). GitHub guarda la copia compartida en internet (la nube).
- Pull: bajar los cambios que otra persona ya subió.
- Push: subir los cambios que se hicieron en la computadora.
Regla de oro: hacer pull antes de empezar a trabajar, y push apenas se termine un cambio.
Añadir colaboradores al repositorio
- 1
Entrar al repositorio en GitHub.com → Settings.
- 2
Ir a "Collaborators".
- 3
"Add people" y escribir el usuario o correo de GitHub.
- 4
La persona invitada acepta la notificación.
Cómo evitar y resolver conflictos
Un conflicto ocurre cuando dos personas modificaron la misma parte del mismo archivo antes de sincronizar. No es grave, pero hay que resolverlo antes de seguir.
Para evitarlos:
- Comunicarse antes de tocar el mismo archivo o sección.
- Pull antes de empezar, push apenas se termine.
- Ser claras con Claude Code sobre qué archivo toca cada quien.
Si ya ocurrió uno: pídanle directamente a Claude Code — "tengo un conflicto de Git en este archivo, resuélvelo de la mejor manera posible".
Comandos de Git a mano
Si los botones de VS Code no funcionan, esto casi siempre alcanza (el equipo no trabaja con ramas distintas):
| Comando | ¿Cuándo se usa? |
|---|---|
| git pull | Bajar los cambios más recientes de GitHub |
| git push -u origin main | Subir cambios la primera vez desde una rama nueva |
| git push | Subir cambios las siguientes veces |
Publicar el sitio en Vercel
- 1
Entrar a vercel.com e iniciar sesión (misma cuenta de GitHub).
- 2
"Add New" → "Project".
- 3
Elegir el repositorio y hacer clic en "Import".
- 4
Cambiar el campo "Root Directory": clic en "Edit" y navegar a la carpeta donde esté el
index.html— no lo dejen en la raíz por defecto si el sitio vive en una subcarpeta. - 5
Clic en "Deploy". Desde ahí, cada push a GitHub vuelve a publicar la versión más reciente.
Importante — no se lo salten: Vercel siempre
propone ./ (la raíz del repositorio) como
Root Directory. Eso solo funciona si el index.html
está justo ahí. Si el sitio está dentro de una subcarpeta (por ejemplo
website/), hay que cambiar el Root
Directory sí o sí antes de darle Deploy — si no, Vercel no va a encontrar el sitio y el deploy va a
fallar o va a mostrar una página en blanco.
Formularios que envían correo (SMTP, dominio propio o Brevo)
Vercel no incluye SMTP. Si un formulario necesita enviar un correo, hay dos caminos:
- Usar un dominio propio con SMTP habilitado.
- Usar un servicio externo como Brevo, a través de su API.
En cualquiera de los dos casos, se le puede pedir a Claude
Code que lo resuelva de punta a punta: que cree un archivo .env
para las credenciales (nunca en el HTML/JS principal), que configure el envío, y que lo pruebe.
Si cambia la clave o el correo, solo hay que actualizar el
.env — el resto del código no se toca.
Resumen de una página
Secuencia de instalación (una vez)
- 1
Descargar e instalar Node.js desde nodejs.org
- 2
Instalar VS Code + extensión "Claude Code"
- 3
Crear cuenta de GitHub
- 4
Configurar
git config --global user.name / user.email
Uso diario
- 1
Abrir el proyecto en VS Code
- 2
Hacer
pullantes de empezar - 3
Trabajar con Claude Code en el chat
- 4
Commit + Push apenas se termine el cambio
| Comando | ¿Qué hace? |
|---|---|
| node -v | Verifica que Node.js está instalado |
| git config --global user.name/email | Registra quién hace los commits |
| git init | Empieza a llevar historial en una carpeta nueva |
| git clone [URL] | Trae una copia de un repositorio de GitHub |
| git add . / git commit -m "..." | Guarda un cambio localmente |
| git pull | Baja los cambios más recientes de GitHub |
| git push / git push -u origin main | Sube los cambios a GitHub |
Si algo no queda claro en la práctica, siempre se le puede pedir a Claude Code que explique el paso específico con el que se está trabajando en ese momento.