Primeros pasos con Claude Code

Llevas un tiempo oyendo hablar de Claude Code: que si un agente en la terminal, que si edita ficheros por su cuenta, que si ejecuta comandos. Pero cuando te sientas a probarlo no sabes muy bien por dónde empezar ni en qué se diferencia del chat que ya usas o del autocompletado del editor. Esta guía te lleva de cero a tu primera sesión productiva, explicando los conceptos justos para que no vayas a ciegas.

Qué es Claude Code (y qué no es)

Claude Code es la CLI agéntica de Anthropic para tareas de ingeniería de software. Vive en tu terminal, entiende tu proyecto leyendo los ficheros que necesita y trabaja mediante lenguaje natural: le describes lo que quieres y él explora el código, propone cambios, edita ficheros y ejecuta comandos.

La palabra clave es agéntico. Para ver la diferencia con lo que ya conoces:

Un autocompletado te ayuda a escribir esta línea. Un chat te ayuda a pensar, pero luego copias y pegas tú. Claude Code cierra el bucle: encuentra el fichero adecuado, hace el cambio, corre los tests y te enseña el resultado. Tú revisas y apruebas. Ese ciclo de "explorar, actuar, verificar" es lo que se llama el bucle agéntico, y es la razón por la que se siente más como delegar en un compañero que como pedir sugerencias a un plugin.

También es multiplataforma: además de la CLI de terminal que cubre esta guía, existe versión web, app de escritorio, extensiones para VS Code y JetBrains, e integración con GitHub Actions para CI/CD. Aquí nos centramos en la terminal, que es donde vive el flujo principal.

Requisitos e instalación

Necesitas una cuenta con acceso a Claude Code: un plan de suscripción Claude Pro, Max, Team o Enterprise, o una cuenta de Claude Console con créditos de API. Ojo: el plan gratuito de Claude.ai no incluye Claude Code.

En cuanto a sistema, los requisitos son modestos: macOS 13+, Windows 10 (1809+) o Linux (Ubuntu 20.04+, Debian 10+), 4 GB de RAM y conexión a internet.

La instalación recomendada usa el instalador nativo. En macOS, Linux o WSL:

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

En Windows PowerShell:

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

Si prefieres gestores de paquetes, tienes alternativas: brew install --cask claude-code en macOS, winget install Anthropic.ClaudeCode en Windows, o el paquete de npm (requiere Node.js 22+):

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

Una diferencia importante: el instalador nativo se actualiza solo en segundo plano; las instalaciones vía Homebrew, WinGet o npm hay que actualizarlas a mano. Cuando termine, comprueba que todo está en orden:

claude --version

Debería imprimir un número de versión seguido de (Claude Code). Si algo falla, claude doctor te da un diagnóstico de la instalación sin arrancar una sesión.

Iniciar sesión y abrir el proyecto

Claude Code necesita una cuenta para funcionar. La primera vez que lo arrancas te pide iniciar sesión en el navegador. Ve a la carpeta de tu proyecto y ejecútalo:

cd /ruta/a/tu/proyecto
claude

Sigue las indicaciones del navegador para autenticarte. Si usas una cuenta de Console, se crea automáticamente un workspace "Claude Code" para el control de costes. Una vez dentro, tus credenciales quedan guardadas y no tendrás que repetir el login. Si algún día necesitas cambiar de cuenta, escribe /login dentro de la sesión.

Al arrancar verás el prompt interactivo con la versión, el modelo y el directorio de trabajo. Esto es el modo interactivo: una conversación en la terminal donde tú escribes instrucciones y Claude responde y actúa. No hace falta añadir ficheros a mano al contexto; Claude los lee según los va necesitando.

El flujo básico de trabajo

La mejor forma de empezar es dejar que Claude entienda el proyecto antes de tocar nada. Prueba a preguntar en lenguaje natural, en el idioma que quieras:

¿qué hace este proyecto?

explícame la estructura de carpetas

Claude analiza los ficheros y te resume. A partir de ahí puedes pedir un cambio concreto:

añade validación al formulario de registro para que no se pueda enviar vacío

El ciclo que sigue Claude es siempre parecido:

1. Localiza los ficheros relevantes.
2. Te muestra los cambios propuestos (un diff).
3. Te pide aprobación antes de escribir, según tu modo de permisos.
4. Aplica la edición y, si hay tests, los ejecuta.

Y como entiende Git, las operaciones de control de versiones se vuelven conversacionales:

crea una rama llamada feature/validacion-formulario

¿qué ficheros he cambiado?

haz commit de mis cambios con un mensaje descriptivo

Conceptos clave para no ir a ciegas

Permisos y aprobaciones

Este es el concepto que más tranquilidad te va a dar. Claude no hace cambios a tus espaldas: en el modo por defecto te pide aprobación antes de cada edición de fichero o comando. Con Shift+Tab cambias de modo de permisos:

Al principio, quédate en el modo por defecto. Ver cada diff antes de aceptarlo es la mejor forma de coger confianza y de entender cómo razona la herramienta. El modo plan es genial cuando quieres que te proponga una estrategia para una tarea grande sin que empiece a editar todavía.

CLAUDE.md: darle contexto al proyecto

CLAUDE.md es un fichero markdown en la raíz de tu repo donde escribes las instrucciones que Claude debería tener presentes en cada sesión: comandos de build y test, convenciones de estilo, arquitectura, decisiones del proyecto. Se carga automáticamente al empezar cada conversación, así que no tienes que repetir lo mismo una y otra vez.

No hace falta escribirlo desde cero. El slash command /init analiza tu código y te genera un CLAUDE.md inicial con los comandos y convenciones que detecta. A partir de ahí lo refinas. Un buen CLAUDE.md es específico y conciso; apunta a menos de 200 líneas y da instrucciones verificables:

## Comandos
- `pnpm dev` — servidor de desarrollo
- `pnpm test` — ejecuta los tests antes de hacer commit

## Convenciones
- Indentación de 2 espacios
- Los handlers de API viven en `src/api/handlers/`

Regla práctica: cada vez que corriges a Claude sobre algo del proyecto por segunda vez, esa corrección debería vivir en el CLAUDE.md.

Slash commands básicos

Dentro de la sesión, los comandos que empiezan por / controlan la herramienta. Escribe / para ver la lista completa; estos son los imprescindibles para empezar:

Un detalle útil: /clear empieza una conversación limpia. Cuando cambias de tarea, limpiar el contexto ayuda a que Claude no arrastre información irrelevante de lo anterior.

Consejos para sacarle partido desde el primer día

• Sé específico. "Arregla el bug" da resultados pobres. "Arregla el bug de login donde el usuario ve una pantalla en blanco tras meter credenciales incorrectas" le da a Claude lo que necesita para acertar a la primera.
• Trabaja en ramas. Pídele que cree una rama antes de una tarea grande. Así aíslas su trabajo y puedes descartarlo con un git checkout si no te convence, sin tocar tu rama principal.
• Revisa los diffs. No aceptes cambios en piloto automático. Leer cada diff no solo evita sorpresas: es la forma más rápida de aprender qué hace bien la herramienta y dónde necesita más contexto.
• Deja que explore primero. Antes de una tarea compleja, pídele que analice el código relevante. Un "analiza el esquema de la base de datos" previo mejora mucho el cambio que venga después.
• Divide en pasos. Para tareas grandes, numera los pasos en tu petición. Claude los aborda en orden y el resultado es más predecible que con una instrucción monolítica.

Conclusión y siguientes pasos

Claude Code no es un autocompletado más listo ni un chat con acceso a tu repo: es un agente que cierra el bucle de "entender, cambiar y verificar" dentro de tu terminal, siempre con tu aprobación de por medio. Con instalarlo, arrancar claude en un proyecto y hacer tu primera pregunta ya tienes lo esencial para empezar.

Desde aquí, los siguientes pasos son naturales: crea un CLAUDE.md con /init para que conozca tu proyecto, prueba el modo plan en una tarea mediana y ve soltando responsabilidad a medida que cojas confianza. La curva es corta y el salto de productividad se nota desde el primer día. Abre una terminal en tu próximo proyecto y pídele algo real: es la mejor forma de entenderlo.