Configuración de Claude Code CLI 2026: Inicio rápido en 5 minutos

¿Cómo configuras Claude Code? Instala el CLI globalmente con npm install -g @anthropic-ai/claude-code, autentícate a través de tu navegador y luego crea un archivo CLAUDE.md en la raíz de tu proyecto con los detalles del stack y las convenciones de código. Configura los permisos en .claude/settings.json y agrega un hook de formato para corregir automáticamente el estilo después de cada edición. Toda la configuración toma menos de cinco minutos. {.answer-block}

Más de 29.000 desarrolladores en ServiceNow usan Claude Code a diario¹, y Allianz lo implementó a nivel de toda la empresa a principios de 2026². La curva de adopción de la herramienta refleja un patrón: una vez que los desarrolladores prueban la programación agéntica en su propia terminal, no vuelven a copiar y pegar desde ventanas de chat. Este inicio rápido es parte de mi serie sobre ingeniería de IA: guías prácticas para desarrolladores que construyen con Claude. El siguiente recorrido te lleva de cero a una sesión funcional de Claude Code en unos cinco minutos, con una configuración real que puedes seguir usando después.

TL;DR: Instala Claude Code mediante npm install -g @anthropic-ai/claude-code, autentícate a través de tu navegador, crea un archivo CLAUDE.md con el contexto de tu proyecto y configura los permisos en .claude/settings.json. Agrega un hook de Prettier para formatear archivos automáticamente después de cada edición. Toda la configuración toma menos de cinco minutos y persiste a través de las sesiones.

Puntos clave

• Desarrolladores en solitario: CLAUDE.md y un hook de formato cubren el 80% de lo que necesitas. Empieza con los permisos predeterminados y preaprueba herramientas a medida que construyes confianza.
• Líderes de equipo: Hacé commit de .claude/settings.json a tu repositorio para que todo el equipo comparta las mismas listas de permisos y hooks.
• Ingenieros de seguridad: El modelo de permisos de tres niveles⁴ (Preguntar, Permitidos, --dangerously-skip-permissions) se corresponde directamente con los niveles de confianza. El modo Preguntar requiere aprobación explícita para cada escritura y cada comando.

Requisitos previos

Necesitas tres cosas antes de instalar Claude Code:

Node.js 18 o posterior. Claude Code se distribuye como un paquete de npm³. Verifica tu versión:

node --version
# v18.0.0 or higher

Si necesitas instalar o actualizar Node.js, usa nvm o descárgalo directamente desde nodejs.org.

Una cuenta de Anthropic con acceso a la API. Crea una clave de API en console.anthropic.com en Settings > API Keys. Claude Code factura por token contra tu saldo de API, o puedes usar el plan de suscripción Max (100 USD/mes individual, 200 USD/mes para equipos, vigente a marzo de 2026)⁶. Mantén la clave disponible para el paso de autenticación.

Una terminal. Claude Code se ejecuta en cualquier emulador de terminal: Terminal.app, iTerm2, Windows Terminal, Alacritty o la terminal integrada en VS Code. Recomiendo una terminal con al menos 120 columnas de ancho, ya que Claude Code muestra diffs de archivos y salidas de herramientas que se benefician del espacio horizontal.

Instalación

Instala Claude Code globalmente mediante npm:

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

Verifica que la instalación haya tenido éxito:

claude --version

Deberías ver un número de versión impreso en stdout. Si obtienes un error de “command not found”, tu directorio bin global de npm no está en tu PATH. Ejecuta npm config get prefix y agrega el subdirectorio /bin al PATH de tu shell. En macOS con Node instalado por Homebrew, el prefijo suele ser /usr/local, así que agrega /usr/local/bin si no está ya ahí.

Problema común de instalación: Si te encuentras con errores de permisos EACCES durante npm install -g, no uses sudo. En su lugar, configura npm para usar un directorio con permisos de escritura de usuario⁷:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
# Add to your shell profile (~/.zshrc or ~/.bashrc):
export PATH="$HOME/.npm-global/bin:$PATH"

En el primer inicio, Claude Code abre tu navegador a la consola de Anthropic para la autenticación OAuth. Inicias sesión, autorizas y Claude Code almacena el token localmente en ~/.claude/. Alternativamente, puedes establecer la variable de entorno ANTHROPIC_API_KEY antes de iniciar. De cualquier manera, las credenciales permanecen en tu máquina y solo autentican solicitudes a la API.

Primera sesión

Navega a cualquier directorio de proyecto y ejecuta:

cd ~/Projects/my-app
claude

Claude Code inicia una sesión REPL interactiva. En el primer inicio en un proyecto nuevo, Claude hace varias cosas automáticamente:

1. Escanea la estructura del directorio para entender la disposición del proyecto
2. Lee los archivos de configuración como package.json, pyproject.toml o Cargo.toml para identificar el stack tecnológico
3. Busca un archivo CLAUDE.md en la raíz del proyecto para instrucciones específicas del proyecto

Prueba un prompt simple para confirmar que todo funciona:

> Explain the structure of this project

Claude lee tus archivos, sintetiza la arquitectura y responde en la terminal. Verás las llamadas a herramientas en tiempo real (cada archivo leído, cada comando ejecutado) junto con una solicitud de permiso antes de cualquier operación de escritura.

Qué observar en tu primera sesión. Presta atención a dos cosas: las llamadas a herramientas (mostradas en tiempo real antes de cada acción) y las solicitudes de permisos. Las llamadas a herramientas revelan cómo Claude navega por tu base de código. Notarás que lee archivos que quizás no habrías pensado en revisar, lo que a menudo saca a la luz contexto útil. Las solicitudes de permisos te muestran exactamente lo que Claude pretende cambiar antes de que algo toque el disco. Si una edición propuesta se ve mal, recházala y proporciona una aclaración. Claude ajusta su enfoque según tus comentarios dentro de la sesión⁸.

Configurando CLAUDE.md

CLAUDE.md es el archivo más importante para un uso efectivo de Claude Code. Sin él, Claude infiere tu stack a partir del contenido de los archivos y hace suposiciones razonables. Con él, Claude sigue tus convenciones exactas desde el primer prompt. La diferencia importa porque el comportamiento basado en inferencia deriva: Claude podría usar CommonJS en un proyecto ESM, elegir el runner de pruebas equivocado o ignorar tu flujo de trabajo de migraciones de base de datos. CLAUDE.md elimina esa deriva.

Crea el archivo en la raíz de tu proyecto:

touch CLAUDE.md

Aquí tienes una plantilla práctica de inicio para un proyecto de Python:

# My App

## Project Context
FastAPI backend with HTMX frontend. PostgreSQL database.

## Stack
- Backend: Python 3.11, FastAPI, SQLAlchemy 2.0 (async)
- Frontend: HTMX + Alpine.js, Jinja2 templates
- Database: PostgreSQL 16, Alembic migrations
- Testing: pytest with pytest-asyncio

## Code Standards
- Type hints on all function signatures
- Pydantic v2 models for request/response validation
- Async database operations only (no sync SQLAlchemy)

## Commands
- `source venv/bin/activate` before any Python command
- `uvicorn app.main:app --reload` starts the dev server
- `python -m pytest -v` runs the test suite
- `alembic upgrade head` applies database migrations

Para un proyecto de JavaScript/TypeScript, la estructura se ve similar:

# My App

## Stack
- Backend: Node.js 20, Express 4, TypeScript
- Frontend: React 18, Vite
- Database: PostgreSQL 16, Prisma ORM
- Testing: Vitest for unit, Playwright for e2e

## Code Standards
- ESM imports only (no require())
- All API endpoints need input validation with Zod
- Tests required for new endpoints before merging

## Commands
- `npm run dev` starts the dev server on port 3000
- `npm test` runs the test suite
- `npx prisma migrate dev` runs database migrations

Las secciones más valiosas de CLAUDE.md son las que previenen errores repetidos. Si Claude sigue importando con require() en lugar de import, agrega “ESM imports only” a Code Standards. Si tu comando de pruebas requiere activar primero un virtualenv, documenta esa secuencia. Claude lee CLAUDE.md al inicio de cada sesión, por lo que cada línea se convierte en una instrucción persistente que se acumula a lo largo de cientos de interacciones. Exploro los patrones que hacen que los archivos CLAUDE.md sean efectivos en Patrones de AGENTS.md, y el principio más amplio de cómo el contexto es arquitectura. La especificación abierta AGENTS.md⁹ sigue un patrón similar para otras herramientas agénticas, pero CLAUDE.md soporta funciones más ricas como directorios de habilidades y reglas.

La jerarquía importa. Puedes colocar un CLAUDE.md en tres ubicaciones, y Claude las fusiona en orden de especificidad:

1. ~/.claude/CLAUDE.md: instrucciones globales para todos los proyectos (tus preferencias personales de programación)
2. ./CLAUDE.md: instrucciones a nivel de proyecto (incluidas en tu repositorio, compartidas con tu equipo)
3. ./src/CLAUDE.md: instrucciones a nivel de directorio (delimitadas a un módulo o subsistema de monorepo)

El CLAUDE.md a nivel de proyecto es el que haces commit al control de versiones. Los miembros del equipo que usan Claude Code heredan tus convenciones automáticamente.

Fundamentos de permisos

Claude Code opera en tres niveles de permisos⁴ que determinan cuánta autonomía tiene el agente. El nivel que elijas controla una compensación fundamental: más autonomía significa sesiones más rápidas pero menos visibilidad sobre lo que cambia.

Modo Preguntar (el predeterminado) requiere aprobación antes de cada escritura de archivo, ejecución de comando o acción destructiva. Ves exactamente lo que Claude pretende hacer y apruebas o rechazas cada paso. Recomiendo empezar aquí porque las solicitudes de aprobación te enseñan cómo funciona Claude Code. Después de unas pocas sesiones, desarrollas intuición sobre qué operaciones son seguras para preaprobar y cuáles merecen escrutinio cada vez.

Permisos permitidos te permiten preaprobar herramientas y patrones específicos para que Claude no pregunte cada vez. Los configuras en el .claude/settings.json de tu proyecto:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(python -m pytest*)",
      "Bash(alembic upgrade head)"
    ]
  }
}

La configuración anterior permite que Claude lea archivos, busque en la base de código y ejecute tus comandos de pruebas y migraciones sin preguntar. Todavía pregunta antes de escribir archivos o ejecutar cualquier otro comando de bash. Observa el patrón: las operaciones de lectura y los comandos de seguridad conocida se agregan a la lista de permitidos. Las operaciones de escritura permanecen en modo Preguntar porque quieres revisar lo que Claude escribe antes de que llegue al disco.

Omitir permisos peligrosamente (--dangerously-skip-permissions) desactiva todas las solicitudes de confirmación. El flag existe exclusivamente para pipelines de CI/CD y flujos de trabajo automatizados donde no hay humanos presentes para aprobar. Nunca lo uses en sesiones interactivas sobre una base de código que te importe.

El sistema de permisos hace que Claude Code sea seguro de usar en proyectos reales. La progresión es deliberada: comienza en modo Preguntar para construir entendimiento, agrega a la lista de permitidos las operaciones que se vuelven repetitivas, y deja las operaciones de escritura bloqueadas para que siempre revises los cambios antes de que se apliquen.

Tu primer hook

Los hooks son comandos de shell que se ejecutan en puntos específicos del ciclo de vida de Claude Code⁵. Escribí un tutorial completo de hooks que construye cinco hooks de producción desde cero, y mi publicación sobre construir skills personalizados cubre el siguiente nivel de automatización. Los hooks resuelven un problema fundamental con las herramientas basadas en LLM: el modelo sigue tus reglas de formato la mayor parte del tiempo, pero “la mayor parte del tiempo” significa que cada décima edición de archivo introduce una inconsistencia de estilo. Los hooks proporcionan garantías determinísticas donde el modelo proporciona garantías probabilísticas. Un hook de formato ejecuta tu formateador después de cada escritura de archivo, cada vez, sin importar lo que el modelo haya decidido hacer. Aquí tienes un primer hook práctico: formateo automático de archivos después de que Claude los edite.

Crea o edita .claude/settings.json en tu proyecto:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

El hook PostToolUse⁵ se dispara después de cada llamada a la herramienta Edit o Write. Claude Code establece $FILE_PATH en la ruta del archivo modificado. Prettier lo formatea en el lugar, y || true asegura que un código de salida distinto de cero no bloquee a Claude si Prettier no está instalado o el tipo de archivo no es compatible⁵.

Otros hooks de inicio prácticos que recomiendo:

• PreToolUse en Bash: Bloquea comandos peligrosos como rm -rf / o git push --force
• SessionStart: Inyecta la fecha actual, la rama git activa o variables de entorno en el contexto (la stdout de los hooks SessionStart alimenta el contexto de Claude)
• Stop: Ejecuta tu suite de pruebas automáticamente cuando Claude termina una tarea

Los hooks transforman a Claude Code de una herramienta conversacional a un entorno de desarrollo gobernado. Incluso uno o dos hooks bien elegidos eliminan categorías enteras de errores.

Cuando las cosas salen mal

Tres situaciones surgen repetidamente en la primera semana de uso de Claude Code. Saber de ellas por adelantado ahorra tiempo de depuración.

Claude ignora tus instrucciones de CLAUDE.md. La causa más común: Claude ya ha leído el archivo y almacenado en caché su comprensión antes de que lo editaras. Ejecuta /clear para restablecer el contexto, o inicia una nueva sesión. Claude relee CLAUDE.md al inicio de la sesión, no en cada prompt. Si Claude sigue ignorando las instrucciones después de una sesión fresca, verifica si un CLAUDE.md de mayor prioridad (a nivel de usuario en ~/.claude/CLAUDE.md) entra en conflicto con tu archivo a nivel de proyecto.

Claude hace un cambio que no aprobaste. Si agregaste un patrón a la lista de permitidos de forma demasiado amplia (por ejemplo, Bash(*) en lugar de Bash(python -m pytest*)), Claude puede ejecutar comandos sin preguntar. Acota tus patrones de lista de permitidos. El enfoque más seguro: agrega a la lista de permitidos solo operaciones de lectura y comandos específicos nombrados. Si Claude ya hizo un cambio no deseado, git diff muestra exactamente lo que cambió, y git checkout -- <file> lo revierte.

La ventana de contexto se llena durante una sesión larga. Claude Code comprime los mensajes anteriores cuando se llena la ventana de contexto de 200K, pero la compresión puede descartar detalles importantes del inicio de la conversación. Para sesiones de más de 30 minutos, haz commit de los cambios funcionales periódicamente e inicia una nueva sesión con /clear. El contexto fresco relee CLAUDE.md y comienza limpio. Yo hago commit después de cada subtarea completada, lo que me da tanto un punto de reversión como un límite de sesión natural.

Claude edita el archivo equivocado o hace cambios innecesarios. Cuando Claude comienza a “mejorar” código que no pediste que tocara, el problema suele ser ambigüedad en el prompt. En lugar de “limpia el módulo de autenticación”, di “en app/auth/handlers.py, renombra verify_user a verify_user_credentials y actualiza todos los llamadores”. La especificidad reduce los efectos secundarios no deseados. Si Claude ya hizo ediciones no deseadas, git diff muestra exactamente lo que cambió y git checkout -- <file> revierte archivos individuales sin perder otro trabajo.

Próximos pasos

El recorrido anterior cubre lo esencial: instalación, tu primera sesión, configuración del proyecto, permisos y un hook de inicio. Para una comparación de Claude Code contra otras herramientas agénticas, consulta Claude Code vs Codex. Para la referencia completa que cubre los 5 sistemas principales (jerarquía de CLAUDE.md, el modelo de permisos completo, la arquitectura de hooks, los comandos slash personalizados y los flujos de trabajo multiagente) lee La guía completa de Claude Code.

La guía cubre la gestión de la ventana de contexto, la delegación a subagentes, la activación automática de skills y los patrones que emergen después de meses de uso diario de Claude Code. Si te resultó útil este inicio rápido, la guía completa es el siguiente paso natural. Para una referencia de consulta rápida de cada comando, flag y atajo, consulta la Hoja de referencia de Claude Code.

Referencias

Preguntas frecuentes

¿Cuáles son los requisitos para instalar Claude Code?

Necesitas Node.js 18 o posterior (Claude Code se distribuye como un paquete de npm), una cuenta de Anthropic con acceso a la API o una suscripción Max, y cualquier emulador de terminal. Claude Code se ejecuta en macOS, Linux y Windows (mediante WSL o de forma nativa). No se requieren dependencias adicionales, contenedores de Docker ni runtimes de lenguaje más allá de Node.js. El comando de instalación es npm install -g @anthropic-ai/claude-code.

¿Qué es CLAUDE.md y por qué lo necesito?

CLAUDE.md es un archivo markdown en la raíz de tu proyecto que le indica a Claude Code tu stack, convenciones de código y comandos comunes. Sin él, Claude infiere tu configuración a partir del contenido de los archivos y hace suposiciones razonables, pero esas suposiciones derivan entre sesiones. Con CLAUDE.md, Claude sigue tus convenciones exactas desde el primer prompt, en cada sesión. Soporta una jerarquía de tres niveles: nivel de usuario (~/.claude/CLAUDE.md), nivel de proyecto (./CLAUDE.md) y nivel de directorio (./src/CLAUDE.md), fusionados en orden de especificidad.

¿Cuánto cuesta Claude Code?

Claude Code soporta dos modelos de facturación. El modelo pago por uso de API cobra por token a las tarifas estándar de la API de Anthropic⁶. Una sesión típica de 30-60 minutos cuesta entre 0,50 y 3,00 USD según el tamaño de la base de código y el volumen de generación. Alternativamente, el plan Max de Anthropic⁶ (100 USD/mes individual, 200 USD/mes para equipos, vigente a marzo de 2026) incluye el uso de Claude Code con límites de tasa más altos. Puedes monitorear el uso de la API en console.anthropic.com.

¿Puedo usar Claude Code con VS Code?

Sí. Claude Code funciona en cualquier terminal, incluida la terminal integrada de VS Code. Abre el panel de la terminal en VS Code, navega al directorio de tu proyecto y ejecuta claude exactamente como lo harías en una terminal independiente. Claude Code lee y edita archivos en disco, por lo que los cambios aparecen inmediatamente en tus pestañas del editor de VS Code. No se requiere una extensión separada de VS Code. Algunos desarrolladores mantienen una división de terminal dedicada para Claude Code junto a su editor, lo que funciona bien para revisar los cambios a medida que ocurren.

¿Es seguro usar Claude Code en bases de código de producción?

El modo Preguntar de Claude Code requiere aprobación explícita antes de cada escritura de archivo y ejecución de comando. Nada cambia en el disco sin tu confirmación. El sistema de permisos, combinado con hooks que pueden bloquear operaciones peligrosas como force pushes o comandos de shell destructivos, hace que Claude Code sea práctico para el trabajo en producción. Uso Claude Code a diario en proyectos que sirven a usuarios reales. La clave es comenzar en modo Preguntar, entender qué hace cada llamada a una herramienta antes de aprobarla, y agregar gradualmente a la lista de permitidos solo las operaciones en las que confías. El control de versiones proporciona la red de seguridad final: haz commit antes de comenzar cualquier sesión significativa de Claude Code para que siempre puedas revertir.

¿Cuál es el error más común que cometen los nuevos usuarios?

Darle a Claude demasiado contexto en el prompt en lugar de ponerlo en CLAUDE.md. Los nuevos usuarios tienden a pegar sus estándares de codificación completos en cada prompt, lo que desperdicia espacio de la ventana de contexto y produce resultados inconsistentes entre sesiones. Mueve las instrucciones recurrentes a CLAUDE.md una vez, y usa los prompts para solicitudes específicas de la sesión. El segundo error más común: agregar Bash(*) a la lista de permitidos en lugar de comandos específicos. Una lista de permitidos de Bash con comodín permite que Claude ejecute cualquier comando de shell sin preguntar, lo que anula el propósito del sistema de permisos.