Guía interna · Turbo Websites

Claude Code, Git,
GitHub y Vercel

Cómo instalar, configurar y trabajar en equipo todos los días — explicado sin tecnicismos, paso a paso, para quienes nunca han programado.

Empezar a leer

3

Partes

30

Subsecciones

0

Experiencia previa

Mac

Enfocada en

Este documento tiene tres partes. La Parte 1 explica qué es cada herramienta, la Parte 2 cómo instalarlas y configurarlas la primera vez (una sola vez por computadora), y la Parte 3 cómo se usan en el día a día.

Parte 1

¿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.

1.1

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.

1.2

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.

1.3

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.

1.4

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).

1.5

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.

1.6

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.

1.7

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.

1.8

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.

1.9

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.

Parte 2

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.

2.1

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
2.2

Instalar Node.js

  1. 1

    Entrar a nodejs.org desde el navegador.

  2. 2

    Descargar la versión LTS — es un archivo .pkg.

  3. 3

    Abrir el archivo descargado y seguir el instalador, igual que con cualquier otro programa de Mac.

  4. 4

    Confirmar en la Terminal escribiendo node -v. Si aparece un número como v22.x.x, quedó instalado.

2.3

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.

2.4

Instalar VS Code + extensión de Claude Code

  1. 1

    Entrar a code.visualstudio.com → "Download for Mac".

  2. 2

    Abrir el .zip y arrastrar VS Code a Aplicaciones.

  3. 3

    Abrir VS Code desde Aplicaciones.

  4. 4

    Ir a Extensiones (Cmd+Shift+X).

  5. 5

    Buscar "Claude Code" e instalar la extensión oficial de Anthropic.

  6. 6

    Iniciar sesión con la cuenta de Claude cuando lo pida (se abre el navegador, 30 segundos).

Extensión Claude Code en VS Code
1 Busquen "claude" en Extensiones. 2 Instalen el resultado publicado por Anthropic.
2.5

Crear cuenta de GitHub

  1. 1

    Entrar a github.com.

  2. 2

    Clic en "Sign up" y seguir los pasos.

  3. 3

    Confirmar el correo cuando GitHub lo pida.

Sign up GitHub
1 Botón "Sign up" arriba a la derecha.
Formulario de registro GitHub
1 Datos de la cuenta. 2 "Create account".
2.6

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.

2.7

Crear un proyecto nuevo

  1. 1

    Crear una carpeta nueva y vacía en el Finder, con el nombre del proyecto.

  2. 2

    Abrir VS Code.

  3. 3

    Arrastrar la carpeta directamente sobre la ventana de VS Code — se abre automáticamente como proyecto activo.

2.8

Clonar un proyecto existente desde GitHub

  1. 1

    En GitHub, copiar la URL desde el botón verde "Code" → HTTPS.

  2. 2

    En VS Code, abrir una terminal dentro del proyecto.

  3. 3

    Escribir git clone y pegar la URL.

Botón Code de GitHub
1 Botón verde "Code". 2 Ícono para copiar la URL de HTTPS.

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.

2.9

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.
Parte 3

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.

3.1

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"

3.2

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".

3.3

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.

3.4

Subir un proyecto nuevo a GitHub por primera vez

  1. 1

    Inicializar Git: git init

  2. 2

    Guardar el primer cambio.

git add .
git commit -m "Primer commit"
  1. 3

    En VS Code, panel de Source Control → botón "Publish Branch". Se recomienda publicarlo como repositorio privado.

3.5

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. 1

    Clic en Source Control. Ahí se ve la lista de archivos que cambiaron.

  2. 2

    Escribir un mensaje corto, o usar el ícono de GitHub Copilot para generarlo automáticamente.

  3. 3

    Clic en "Commit" (✓).

  4. 4

    Clic en "Sync Changes" o "Push".

Mensaje de commit VS Code
1 Cuadro de mensaje. 2 Botón "Confirmación".
Sincronizar cambios VS Code
2 Botón "Sincronizar cambios" (Sync/Push).
3.6

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.
3.7

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.

3.8

Añadir colaboradores al repositorio

  1. 1

    Entrar al repositorio en GitHub.com → Settings.

  2. 2

    Ir a "Collaborators".

  3. 3

    "Add people" y escribir el usuario o correo de GitHub.

  4. 4

    La persona invitada acepta la notificación.

Collaborators GitHub
1 "Collaborators" en Settings. 2 Botón "Add people".
3.9

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".

3.10

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 pullBajar los cambios más recientes de GitHub
git push -u origin mainSubir cambios la primera vez desde una rama nueva
git pushSubir cambios las siguientes veces
3.11

Publicar el sitio en Vercel

  1. 1

    Entrar a vercel.com e iniciar sesión (misma cuenta de GitHub).

  2. 2

    "Add New" → "Project".

  3. 3

    Elegir el repositorio y hacer clic en "Import".

  4. 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. 5

    Clic en "Deploy". Desde ahí, cada push a GitHub vuelve a publicar la versión más reciente.

Add New en Vercel
1 Botón "Add New..." → "Project".
Import Git Repository en Vercel
1 Ubicar el repositorio y hacer clic en "Import".

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.

Root Directory en Vercel
1 Campo "Root Directory" + botón "Edit": ahí se navega y se elige la carpeta exacta donde está el index.html.
3.12

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.

Referencia rápida

Resumen de una página

Secuencia de instalación (una vez)

  1. 1

    Descargar e instalar Node.js desde nodejs.org

  2. 2

    Instalar VS Code + extensión "Claude Code"

  3. 3

    Crear cuenta de GitHub

  4. 4

    Configurar git config --global user.name / user.email

Uso diario

  1. 1

    Abrir el proyecto en VS Code

  2. 2

    Hacer pull antes de empezar

  3. 3

    Trabajar con Claude Code en el chat

  4. 4

    Commit + Push apenas se termine el cambio

Comando¿Qué hace?
node -vVerifica que Node.js está instalado
git config --global user.name/emailRegistra quién hace los commits
git initEmpieza 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 pullBaja los cambios más recientes de GitHub
git push / git push -u origin mainSube 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.