Empezar con Claude Code: de la instalación a tu primer commit en 30 minutos

Escribes claude en la terminal y pulsas Enter.

Ves que algo arranca, eso está claro. Pero la primera vez que lo hice, lo único que apareció en pantalla fue un “inicia sesión” y me quedé bloqueado unos cinco minutos. ¿Iniciar sesión dónde? ¿Esto cuesta dinero? ¿Me va a leer todo mi código? Al final, ese día cerré la terminal sin tocar una sola línea.

Visto en retrospectiva, el primer muro no fue la instalación ni el inglés: fue no saber qué pedirle una vez arrancado. Así que en este artículo vamos directo a cruzar esa barrera por el camino más corto. Instalación → login en el navegador → primer prompt → primer commit, todo en 30 minutos. Y por el camino te dejo, antes de que tropieces, los tres baches con los que me caí yo (dar todos los permisos, las conversaciones que se vuelven lentas y la primera línea del CLAUDE.md).

La intención de búsqueda es simple: “cómo empezar con Claude Code”, “cómo se usa para principiantes”. Voy a responder solo eso, sin rodeos.

Puntos clave

• La instalación es un único instalador oficial. En macOS/Linux con curl ... | bash, en Windows con irm ... | iex. Si prefieres instalarlo con Node.js, usa npm i -g @anthropic-ai/claude-code (Node 18 o superior).
• La autenticación es por navegador. Al lanzar claude te lleva al login. Necesitas un plan Claude Pro/Max o una cuenta de Console (el plan gratuito de Claude.ai no sirve).
• Los primeros 30 minutos: que no modifique nada. Primero que lea, luego que explique, después revisa un solo archivo. Así te acostumbras.
• La meta es llegar al primer commit. Desde el día uno, cógele el hábito de revisar el diff con tus propios ojos antes de confirmar.
• Las tres minas con las que tropiezan los principiantes: no dar todos los permisos / comprimir la conversación cuando se vuelve lenta / escribir en el CLAUDE.md una línea con “cómo correr los tests”.

Vamos por orden. Todo el código que pongo está pensado para copiar, pegar y que funcione.

Primero, el mapa: los 30 minutos de un vistazo

Antes de meternos en los pasos concretos, te muestro el mapa hasta la meta. Cuesta mucho menos perderse así.

Tiempo	Qué hacer	Para qué
0–5 min	Instalar + login en el navegador	Dejar claude listo para arrancar
5–10 min	Crear una rama de práctica	Tener un terreno al que volver si algo sale mal
10–20 min	Que lea y que explique	Entender en qué se basa para responder
20–25 min	Pedir un cambio pequeño	Vivir el flujo de editar → revisar el diff
25–30 min	El primer commit	Coger el hábito de confirmar tú la decisión

La clave es esta: el primer día no hagas refactorizaciones grandes. Encargos del tipo “ponme bonito todo este proyecto” déjalos para cuando ya tengas práctica. Al principio, pequeño y dentro de un rango al que puedas volver.

Paso 1: instalar (0–3 min)

Hasta hace poco lo habitual era “instalarlo con npm”, pero la opción oficial número uno hoy es un instalador propio. Entra sin que tengas que preocuparte de si tienes Node.js o no.

En macOS / Linux / WSL, esto:

curl -fsSL https://claude.ai/install.sh | bash

En PowerShell de Windows, esto:

irm https://claude.ai/install.ps1 | iex

Si eres de los que dicen “yo prefiero gestionarlo con Node.js”, también puedes instalarlo con npm como hasta ahora. Necesitas Node.js 18 o superior.

npm install -g @anthropic-ai/claude-code

Comprueba que entró. Si sale un número de versión, listo.

claude --version

Si aquí te aparece command not found, claude doctor te dice cuál es la causa.

claude doctor

Solo un aviso. Aunque salga un error de permisos, no recurras por reflejo a sudo npm install -g. La propia documentación oficial dice expresamente que lo evites “porque puede derivar en problemas de permisos y riesgos de seguridad”. Sin agobiarte, seguir las indicaciones de claude doctor es más rápido.

Paso 2: iniciar sesión en el navegador (3–5 min)

Una vez instalado, arráncalo.

claude

La primera vez salta automáticamente a la pantalla de login. Se abre el navegador, así que solo tienes que iniciar sesión siguiendo las indicaciones de pantalla. Una vez que pasas, guarda las credenciales y no te lo vuelve a preguntar.

Aquí los principiantes suelen atascarse con un “vale, ¿pero con qué cuenta?”. Ordenado, queda así:

• Plan Claude Pro / Max / Team / Enterprise… si empiezas por tu cuenta, es lo más cómodo (recomendado).
• Anthropic Console (API, crédito de prepago)… para quien quiera operar con API key y centralizar el control de costes.
• Amazon Bedrock / Google Vertex AI / Microsoft Foundry… cuando la empresa ya tiene definida su política de nube.

Un aviso importante. Con el plan gratuito de Claude.ai no se puede usar Claude Code. Mucha gente se queda dándole vueltas a un “no puedo iniciar sesión” sin saber esto, así que te lo adelanto.

Si más adelante quieres cambiar de cuenta, escribe /login en la sesión activa y vuelves a autenticarte.

Paso 3: crear un sitio al que volver si algo sale mal (5–10 min)

Esto es poco vistoso pero importante: no juegues directamente en tu repositorio de producción. Abre un repositorio pequeño de práctica o un proyecto personal que no pase nada si se rompe.

Si vas a probar con código del trabajo, crea siempre una rama de trabajo.

git status
git switch -c try-claude-code

Mirar primero git status es para no arrastrar cambios sin confirmar. Si lo usas con un estado previo confuso, luego no sabrás distinguir “¿este diff lo hizo la IA o lo hice yo?”. Esto me pasó de verdad mi primer día.

Arranca Claude Code en esa carpeta.

cd /ruta/a/tu/proyecto
claude

Al arrancar, en la parte de arriba se muestran la versión, el modelo en uso y el directorio de trabajo. Con /help ves la lista de comandos.

Paso 4: al principio, solo que “lea” (10–20 min)

Aquí empieza lo bueno. Pero todavía no le dejamos modificar nada. Primero que lea y que explique. Solo con esto coges la intuición de “en qué se basa Claude Code para responder”.

En el modo interactivo basta con hablarle en lenguaje natural. No hace falta ninguna sintaxis complicada.

Lee solo el README.md y el package.json, y explícame en español
el objetivo de este proyecto y cómo se arranca.

La clave está en acotar el rango con un “lee solo”. Si dejas que empiece a leer un montón de archivos cuando aún eres principiante, pierdes el rastro de dónde sale la respuesta. Esto enlaza directamente con el problema de “la conversación se vuelve lenta” que veremos luego.

Cuando vayas cogiendo confianza, pídele que revise un único archivo.

Lee solo src/utils/date.ts y señálame, en como máximo 3 puntos,
qué podría convertirse en un bug. Todavía no edites nada.

Si añades “todavía no edites nada”, no se te mezclan la revisión y la implementación. Primero el ejercicio de leer las propuestas; meter mano viene después.

Por cierto, cuando quieras lanzar una investigación o una tarea rutinaria una sola vez y rápido, el modo de una sola pasada (one-shot) va de maravilla sin entrar al modo interactivo. Con -p te devuelve el resultado y termina.

claude -p "Ejecuta git log --oneline -10 y resúmeme en español qué cambió."

Mi criterio para elegir es simple: la implementación en la que vas probando, en modo interactivo; las consultas y los resúmenes, en one-shot. Al principio, con aprender estos dos te sobra.

Paso 5: el primer cambio pequeño (20–25 min)

Cuando ya tienes el ejercicio de leer, por fin le dejas modificar. Empieza siempre en la unidad de “un archivo, una función”.

En el modo interactivo, pídeselo así:

Añade un test unitario a la función getUserById de src/api/users.ts.
Ajústalo a cómo están escritos los tests existentes.

Aquí Claude Code siempre te pregunta “¿aplico este cambio?”. No reescribe archivos por su cuenta. Mira el diff propuesto y, cuando lo veas claro, lo apruebas. Ese es el seguro de serie.

La primera mina está justo aquí. Como me daba pereza pulsar Enter en cada confirmación, enseguida me pasé al modo “permitir todo”. Y entonces me “organizó de paso” hasta archivos que no le había pedido, y me quedé blanco. La lección es que al principio, aprobar de uno en uno es lo que sale más rápido a la larga. Cuando quieras afinar los permisos al detalle, sigue con el artículo dedicado que enlazo más abajo.

Cuando aceptes el cambio, revisa siempre el diff con tus propios ojos.

git diff
npm test

“Parece que funciona” y “solo contiene el diff que yo quería” no son lo mismo. El diff y los tests van juntos, en pareja.

Paso 6: el primer commit (25–30 min)

Revisaste el diff y los tests pasan. Si llegaste hasta aquí, la meta está al alcance de la mano.

El commit también puedes pedirlo con lenguaje natural.

Revisa los cambios y haz commit con un mensaje claro y comprensible.

Claude Code lee el git diff, piensa el mensaje y, antes de confirmar, vuelve a preguntarte. Por supuesto, también puedes hacerlo a mano.

git add src/api/users.ts
git commit -m "test: añade test unitario de getUserById"

Con esto cerraste el círculo “instalar → login → que lea → cambiar algo pequeño → commit”. En 30 minutos has dado una vuelta completa al bucle mínimo de Claude Code con tus propias manos. El primer día, con esto basta. Cierra la terminal con la cabeza bien alta.

Listo para copiar y pegar: los 30 minutos en un único script de arranque

Como me da pereza acordarme de los comandos cada vez, tengo guardado un script de shell que “empieza una sesión de práctica de forma segura”. Crea la rama y deja lanzado hasta el encargo de lectura, todo de un tirón. No necesita Node.js: funciona solo con bash.

#!/usr/bin/env bash
# start-claude-practice.sh — empieza a practicar con Claude Code de forma segura
set -euo pipefail

# 1) Comprobar que no quedan cambios sin confirmar (evita arrastrarlos por accidente)
if [ -n "$(git status --porcelain)" ]; then
  echo "Aviso: hay cambios sin confirmar. Haz commit o stash antes de seguir."
  git status --short
  exit 1
fi

# 2) Crear la rama de práctica (con fecha; si ya existe, solo cambia a ella)
BRANCH="try-claude-$(date +%Y%m%d)"
git switch -c "$BRANCH" 2>/dev/null || git switch "$BRANCH"
echo "OK: trabajando en la rama $BRANCH"

# 3) Lanzar primero, en one-shot, el encargo de "solo leer"
claude -p "Si hay README, léelo; si no, lee los archivos principales y
explícame en español, en 3 líneas, el objetivo del proyecto, cómo se arranca
y qué archivo conviene leer después. No edites absolutamente nada."

Usarlo es así de simple.

chmod +x start-claude-practice.sh
./start-claude-practice.sh

Al ejecutarlo, si hay cambios sin confirmar te frena, y si no los hay, crea la rama de práctica y te saca un resumen del proyecto. Reúne en un solo archivo el “evitar arrastrar cambios por accidente”, el “crear un sitio al que volver” y el “primero, que lea”. Es justo lo que me habría gustado entregarle a mi yo del primer día.

Los tres baches con los que tropecé al principio

A partir de aquí van las cosas que no suelen aparecer en los manuales pero que, si te pillan el primer día, son las que más amargan.

1. Dar todos los permisos desde el principio

Como ya dije, si por pereza con las confirmaciones lo pones todo en “permitir todo”, te llevas un accidente. Al principio lo seguro es usarlo con escrituras y commits confirmados cada vez, y borrados y force push prohibidos. En .claude/settings.json puedes dejarlo decidido así:

{
  "permissions": {
    "allow": ["Read(**)", "Grep(**)", "Bash(npm test*)", "Bash(git status*)", "Bash(git diff*)"],
    "ask": ["Write(**)", "Edit(**)", "Bash(git commit*)", "Bash(git push*)"],
    "deny": ["Bash(rm -rf*)", "Bash(git push --force*)"]
  }
}

“Lectura y tests automáticos, escritura y commit con confirmación, borrados peligrosos prohibidos”. Solo con este esquema de tres niveles evitas casi todos los accidentes. Las operaciones que con el uso compruebas que son seguras, las vas ascendiendo después a allow. El diseño fino lo dejé resumido en la guía de configuración de permisos de Claude Code; si lo quieres apurar en serio, sigue por ahí.

2. La conversación se vuelve lenta (saturación del contexto)

Según vas usándolo, a partir de cierto punto se pone de pronto pesado. No es una avería: es la señal de que la conversación se alargó y el “contexto” que carga Claude Code se hinchó demasiado. Es lo mismo que la encimera de la cocina cuando se va llenando con los platos que vas usando.

Hay dos remedios. Cuando llegues a un punto de corte, comprime la conversación o déjala en blanco.

/compact

/clear

/compact comprime dejando lo esencial; /clear reinicia entero. En cuanto notes “antes iba fluido y ahora no”, tira de uno de los dos sin dudar. Lo que dije al principio, “acotar el rango de lectura”, también ayuda aquí: cuantos menos archivos sobrantes le hagas leer, menos se ensucia la encimera. Para separar bien las causas de la lentitud, la guía de optimización de velocidad de Claude Code lo explica al detalle.

3. No escribir la primera línea del CLAUDE.md

Esto es del tipo “qué bien que lo hice”. Claude Code lee automáticamente el CLAUDE.md que esté en la raíz del proyecto. Si dejas ahí escrita la información del proyecto, te ahorras explicarla cada vez.

De lo que me arrepiento es de no haberlo escrito al principio. Acabé teniendo que explicar una y otra vez “este proyecto es TypeScript, los tests se corren con npm test”. La única línea que deberías escribir primero es esta:

## Comandos habituales
- Tests: npm test
- Servidor de desarrollo: npm run dev

Con solo dejar escrito “cómo se corren los tests”, Claude Code intenta lanzarlos por su cuenta después de un cambio. Y al revés: si escribes desde el principio un CLAUDE.md enorme, entonces cuesta que se respeten las instrucciones. Qué escribir y qué no, dónde está la línea, lo dejé aparte en las mejores prácticas para CLAUDE.md.

El siguiente paso: de la tarea suelta a “delegar”

Cuando ya domines el bucle de 30 minutos, el siguiente nivel es pasar de “la instrucción suelta” a “delegar un trabajo medianamente cerrado”. Eso sí, no saltamos de golpe al modo totalmente automático.

El orden es siempre el mismo: ① acotar bien el rango de lectura → ② dejar clarísima la meta (el entregable) → ③ dejar las comprobaciones en manos de comandos siempre que se pueda → ④ las operaciones peligrosas, al principio todas “que pregunte al humano”. Esta idea de montarle un “andamio” a la IA la dejé resumida con detalle en cómo montarle a la IA el andamio (harness) para delegarle trabajo. Si lo lees justo después de esta introducción, el paisaje cambia de golpe.

La forma de dar las instrucciones también cambia el resultado cuando le coges el truco. Solo tres trucos:

1. Escribe el nombre del archivo (y si puedes, el número de línea) — reduce el trabajo de exploración.
2. Describe en concreto el comportamiento esperado — “hazlo apañado” no funciona.
3. Añade las restricciones — “ajústate al patrón existente”, “no toques otros archivos”.

Añade a la función login de src/api/auth.ts una comprobación que devuelva 400
cuando la contraseña esté vacía. El texto del error, ajústalo al patrón de
src/utils/errors.ts. No toques otros archivos.

Preguntas frecuentes

P. ¿Se puede usar gratis? R. Claude Code en sí no funciona con el plan gratuito de Claude.ai. Necesitas un plan Claude Pro / Max o una cuenta de Console con crédito de prepago. Si te preocupa el coste, en la guía de gestión de costes de Claude Code y la API explico cómo fijar un presupuesto.

P. ¿En Windows funciona igual que en Mac? R. Funciona. Lo único que cambia es la instalación, que pasa a ser irm https://claude.ai/install.ps1 | iex (en PowerShell); el arranque y el uso son iguales. Tener Git Bash instalado hace que la ejecución de algunos comandos vaya más fina.

P. ¿Hace falta una API key? R. Si empiezas por tu cuenta, no. Lanzar claude e iniciar sesión en el navegador es lo más cómodo. La configuración con la API key en variables de entorno ya la verás cuando la política de autenticación del equipo o el entorno de nube estén definidos.

P. ¿No me subirá todo mi código? R. Claude Code lee solo los archivos necesarios en cada momento. No tienes que pasárselos todos a mano y, como norma básica, no pegues el .env ni claves de producción ni datos de clientes. El mínimo imprescindible de seguridad lo dejé resumido en las medidas de seguridad de Claude Code.

P. Me da la sensación de que el modelo por defecto es pesado y caro. R. Para tareas sencillas puedes cambiar a un modelo más ligero durante la sesión. Con /model eliges el modelo, así que usa uno ligero para consultas y uno potente para implementaciones difíciles, y trabajarás mucho más a gusto.

Conclusión: dar una vuelta completa al “bucle mínimo” en 30 minutos

Cómo empezar con Claude Code, llevado a su esencia, es una sola línea: instalar → login en el navegador → que lea → cambiar algo pequeño → mirar el diff y hacer commit. Cuando das una vez esta vuelta de 30 minutos con tus propias manos, el “no sé por dónde empezar” desaparece.

Lo que más fácil es fastidiar el primer día son solo tres cosas: no dar todos los permisos, comprimir la conversación cuando se vuelve lenta y escribir en el CLAUDE.md una línea con “cómo correr los tests”. Si las evitas, la primera experiencia te saldrá bastante más suave.

Este sitio (claudecode-lab.com) mueve cada día la generación de artículos, la traducción y el despliegue con Claude Code. Y eso lo digo yo, que al principio dudaba con un “¿en serio se puede hacer eso?”. Tú también, hoy: primero 30 minutos. Escribe claude y prueba a llegar hasta tu primer commit.

Cuando te vuelvas a atascar, puedes elegir hacia dónde seguir según cómo te hayas atascado. Si quieres tener a mano los comandos y las formas seguras de pedir las cosas, la chuleta gratuita de Claude Code; si quieres dejar montados de una vez la configuración y la operativa, el catálogo de material es el atajo.

Los pasos más actuales también puedes consultarlos en el Quickstart oficial de Claude Code (en inglés). La instalación y la autenticación pueden cambiar, así que, ante la duda, mira siempre la fuente original.

El resultado real de probar lo que cuento en este artículo

Este bucle de 30 minutos se lo hice probar al lado a un conocido, desarrollador front-end y poco habituado a la línea de comandos. Lo que más efecto tuvo fue lo de “al principio que no modifique nada”. Si te saltas la fase de que lea y explique, te quedas bloqueado ante la primera propuesta de edición. En cambio, quien metió en medio el explicar → revisar un archivo, llegó a su primer commit de verdad en poco menos de 30 minutos.

Otra cosa que noté en carne propia es el efecto de la “línea de los tests” en el CLAUDE.md. Con eso escrito, después de un cambio Claude Code corre npm test por su cuenta, se da cuenta solo de los fallos y empieza a arreglarlos. Sin ello, eres tú quien tiene que decir “haz los tests” una y otra vez. La diferencia de apenas dos líneas redujo de forma clara el número de idas y venidas posteriores. Antes de salir a buscar un modelo más listo, ordena un peldaño del andamio: incluso en una introducción, al final eso es lo que más efecto tiene.