Configuración de Claude Code: guía para principiantes

La configuración de Claude Code toma unos diez minutos, pero entender qué estás instalando realmente cambia cómo lo usas. Esta guía cubre los comandos concretos, el flujo de autenticación y las tres primeras tareas que te enseñarán más que cualquier lista de funciones.

Qué es Claude Code en realidad

Claude Code es una herramienta CLI creada por Anthropic. Se instala globalmente con npm, se ejecuta con claude dentro de un directorio de proyecto y abre una sesión interactiva donde el asistente puede leer archivos, ejecutar comandos de shell, editar código y proponer commits de git.

No es una interfaz de chat. Esa distinción importa: no estás pegando fragmentos de código en una pestaña del navegador. Cuando le pides que corrija un bug, lee el archivo fuente real, hace el cambio y te muestra el diff. Tú decides qué se aplica. La interfaz principal es la terminal, no un plugin de editor, aunque existen integraciones con IDEs si las quieres.

Requisitos previos antes de instalar

Necesitas dos cosas antes de que el primer comando claude funcione.

Node.js 18 o superior

Claude Code se distribuye como un paquete npm. Comprueba tu versión:

node --version

Si estás por debajo de la versión 18, actualiza mediante nvm o el gestor de paquetes de tu sistema. Node 20 LTS es una opción segura.

Una nota para usuarios de Windows: Claude Code no funciona de forma fiable en Windows CMD ni en PowerShell. Usa WSL2. Instala WSL2, configura Ubuntu dentro de él y ejecuta todo desde ahí.

Una cuenta de Claude.ai

Necesitas una cuenta de Claude.ai para autenticarte. Si no tienes una, créala en claude.ai. Una suscripción Pro ($20/mes) cubre el uso de Claude Code como tarifa plana, sin cargos adicionales por token. Si necesitas un uso más intensivo, facturación por equipo o quieres gestionar los costos por token, puedes conectar Claude Code directamente a la API de Anthropic usando una API key desde console.anthropic.com. Para la mayoría de los desarrolladores que empiezan, la suscripción Pro es la opción más sencilla.

Configuración de Claude Code: instalación y primera ejecución

Instala Claude Code de forma global:

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

Verifica que se instaló correctamente:

claude --version

Deberías ver una cadena de versión como 1.x.x. Si obtienes “command not found”, es probable que el directorio bin global de npm no esté en tu PATH. Ejecuta echo $PATH y comprueba si incluye la ubicación del bin global de npm. Puedes encontrar esa ubicación con npm prefix -g: los binarios están en el subdirectorio bin/ de esa ruta. Agrégala a tu perfil de shell si falta.

Ahora navega a un directorio de proyecto real e inicia una sesión:

cd ~/projects/my-laravel-app
claude

La primera ejecución abre una ventana del navegador y te pide que inicies sesión con tu cuenta de Claude.ai. Completa el flujo OAuth, vuelve a la terminal y ya estás dentro. El prompt se parece a un REPL sencillo. Escribe una instrucción y presiona Enter. Para salir en cualquier momento, escribe /exit o presiona Ctrl+C.

Navegar la sesión: los slash commands que usarás cada día

Claude Code tiene slash commands integrados para gestionar la sesión. Estos son los cuatro que realmente necesitas al principio.

/init

Ejecútalo una vez por proyecto, en la raíz del proyecto. Lee la estructura de tu repositorio y genera un archivo CLAUDE.md con lo que encontró: tu stack, los comandos probables y la distribución de carpetas. El archivo generado es un punto de partida, no un producto terminado. Revisa cada línea y corrige lo que esté mal.

/help

Lista los comandos disponibles con una breve descripción de cada uno. Útil cuando olvidas el nombre de un comando o quieres ver qué se ha añadido en una actualización reciente.

/clear

Limpia el historial de conversación de la sesión actual. Úsalo cuando el contexto se ha alargado demasiado y las respuestas empiezan a sentirse dispersas. Comenzar de cero en una nueva subtarea suele ser más efectivo que continuar un hilo sobrecargado.

/compact

Resume la conversación actual en una representación más corta sin perder los datos clave. Es el punto intermedio entre mantener el historial completo y borrarlo del todo, útil en sesiones largas donde todavía estás a mitad de una tarea pero el contexto se está volviendo costoso.

CLAUDE.md: el archivo que hace útil a Claude Code

Cada vez que inicias una sesión de Claude Code en un directorio, lee CLAUDE.md desde la raíz del proyecto si existe. Este archivo es la memoria persistente del agente para tu proyecto. Sin él, pasas los primeros mensajes re-explicando tu stack y tus convenciones cada vez.

Un buen CLAUDE.md responde las preguntas que le responderías a un ingeniero nuevo en su primer día: qué es este proyecto, cómo se ejecuta, dónde vive cada cosa, qué nunca debes tocar. Aquí hay un ejemplo realista para un proyecto Laravel:

# Project: MyApp API

Laravel 11, PHP 8.3, MySQL 8.0, Redis for queues and cache.

## Commands
- `php artisan serve` — local dev server
- `php artisan test` — run Pest test suite
- `./vendor/bin/pint` — code style (PER preset)
- `php artisan migrate` — run pending migrations

## Architecture
- API-only backend, no Blade views
- Controllers in app/Http/Controllers/, thin, delegate to Services
- Business logic in app/Services/
- Jobs in app/Jobs/ for anything async

## Conventions
- Short controller methods, fat service classes
- All DB writes go through a Service, never directly from a Controller
- Feature tests in tests/Feature/, unit tests in tests/Unit/

## Off-limits
- Do not edit files in vendor/
- Do not modify database/migrations/ that have already run in production
- Never commit .env changes

Escríbelo como si estuvieras haciendo un briefing a un contratista. El agente lo usa exactamente igual que lo haría un contratista: como referencia antes de hacer preguntas.

El modelo de permisos: por qué pide confirmación antes de ejecutar comandos

Cuando le pides a Claude Code que haga algo que implica ejecutar un comando de shell o editar un archivo, primero pide confirmación. Esto es intencional y deberías dejarlo activado.

El prompt de confirmación te indica exactamente qué comando quiere ejecutar, o te muestra el diff antes de aplicar una edición. Tu trabajo es leerlo. No ojearlo.

Puedes aprobar una acción específica, rechazarla, o indicarle que siempre permita cierta clase de comandos para la sesión actual, por ejemplo, permitir siempre los comandos php artisan. Sé conservador con la opción “always allow” al principio. Es fácil aprobar una clase amplia de comandos que luego incluye algo que no esperabas.

El modelo de permisos es una de las cosas que Claude Code hace bien. Significa que puedes delegar una tarea sin alejarte de tu terminal. Mantente presente, lee los diffs y trata el paso de aprobación como tu última línea de revisión antes de que algo cambie en el disco.

Tres primeras tareas que enseñan más que cualquier tutorial

Las explicaciones abstractas de lo que Claude Code puede hacer son menos útiles que ejecutar tres tareas reales en un proyecto que conoces. Aquí hay tres puntos de partida, ordenados de menor a mayor riesgo.

Tarea 1: explicar una función

Busca una función en tu codebase que no hayas escrito tú, o una que se haya vuelto compleja con el tiempo. Pregunta:

Explain what the `processInvoice` method in app/Services/BillingService.php does.
Focus on the side effects: what does it write to the database, what events does it fire?

Esta tarea lee archivos pero no escribe nada. Es una forma segura de comprobar qué tan bien el modelo entiende tu codebase. Si la explicación es incorrecta o superficial, probablemente tu CLAUDE.md necesita más contexto sobre tu arquitectura.

Tarea 2: corregir un bug

Elige un bug pequeño y autocontenido: una regla de validación incorrecta, un error de índice, una verificación de nulo que falta. Descríbelo con suficiente contexto:

In app/Http/Controllers/UserController.php, the `update` method does not validate
that `email` is unique before saving. Add the unique validation rule,
but exclude the current user's own email from the uniqueness check.

Revisa el diff con cuidado antes de aprobar. Verifica que cambió exactamente lo que describiste y nada más. Este es el hábito de revisión que debes construir ahora, antes de que las tareas sean más grandes.

Tarea 3: escribir un test

Pídele que escriba un test para una lógica que actualmente no tiene cobertura:

Write a Pest feature test for the POST /api/users endpoint.
Cover: successful creation, validation failure when email is missing,
and a 409 response when the email already exists.

Los tests son un buen objetivo de delegación temprana porque el resultado es fácil de verificar. Ejecuta el test. Si pasa, el código probablemente es correcto. Si falla, lee el mensaje de error y pide una corrección.

Errores comunes de los principiantes

Estos son los patrones que hacen que Claude Code parezca poco fiable cuando el problema es el prompt o el flujo de trabajo, no la herramienta.

Prompts vagos

“Fix the bug in the user service” le dice al modelo casi nada. Sé específico sobre el archivo, el método, el síntoma y cómo debería verse el comportamiento correcto. Cuanto más contexto des, menos tiempo pasas corrigiendo el resultado.

No leer el diff

La forma más común de introducir una regresión con una herramienta de IA es aprobar un cambio sin leerlo. Claude Code te muestra el diff antes de aplicarlo. Ese es el momento de detectar cambios no deseados: saltárselo es el equivalente a hacer merge de un PR sin revisarlo.

Dar permisos amplios demasiado pronto

Si otorgas “always allow” a una clase amplia de comandos en tu primera sesión, pierdes la red de seguridad que hace que delegar sea seguro. Empieza con aprobación sesión por sesión. Una vez que entiendas cómo se comporta la herramienta en tu proyecto, amplía los permisos donde realmente ahorre fricción.

Usarla para tareas que requieren contexto que no puede tener

Claude Code funciona bien para tareas acotadas y describibles. Funciona mal para tareas que requieren contexto organizacional que ningún archivo captura: por qué se añadió un workaround específico para un cliente concreto, o qué implica para el codebase una decisión de producto tomada hace seis meses. Esas tareas quédalas para ti.

Qué leer a continuación

Una vez que hayas ejecutado algunas sesiones y construido un CLAUDE.md sólido, el siguiente paso es entender el flujo de trabajo más amplio: cómo estructurar las tareas para que el agente se mantenga productivo, cómo manejar la revisión de código, qué delegar y qué conservar. Mi guía sobre agentes de IA en el flujo de trabajo de desarrollo cubre eso en detalle, incluyendo las cinco reglas que sigo en cada proyecto.

Cuando estés listo para ir más lejos con subagentes especializados para discovery, planificación y revisión, la guía de subagentes de Claude Code y optimización de tokens continúa desde donde esta se detiene.

Preguntas frecuentes

¿Necesito una API key para usar Claude Code?

No. La configuración por defecto usa login OAuth por navegador con tu cuenta de Claude.ai. Una API key solo es necesaria si quieres conectar Claude Code directamente a la API de Anthropic para facturación personalizada o límites de uso más altos.

¿Claude Code funciona en Windows?

No de forma fiable en Windows CMD o PowerShell nativo. Usa WSL2 con Ubuntu. Instala WSL2, ejecuta todos los comandos desde la terminal de Ubuntu y todo funcionará como se documenta.

¿Cómo salgo de una sesión de Claude Code?

Escribe /exit en el prompt, o presiona Ctrl+C.

¿Qué es CLAUDE.md y lo necesito?

Es un archivo de texto plano en la raíz de tu proyecto que Claude Code lee al inicio de cada sesión. Le da al agente contexto persistente sobre tu stack, comandos y convenciones. No lo necesitas para empezar, pero sin él tendrás que re-explicar tu proyecto en cada sesión. Ejecuta /init para generar un borrador.

¿Claude Code es gratuito?

El uso de Claude Code está incluido en la suscripción Pro de Claude.ai sin cargo adicional por token. Si usas la ruta directa de la API, pagas por token a las tarifas estándar de la API de Anthropic.

¿Cómo accede Claude Code a mis archivos?

Lee y escribe directamente en tu sistema de archivos local, limitado al directorio donde lo ejecutas. Cada edición de archivo y comando de shell requiere tu aprobación explícita antes de ejecutarse.