Instalar Claude Code CLI: guía de configuración en 5 minutos (2026)

¿Cómo se configura Claude Code? Instala la CLI con el instalador nativo, curl -fsSL https://claude.ai/install.sh | bash, autentícate desde tu navegador y luego crea un archivo CLAUDE.md en la raíz de tu proyecto con los detalles de tu stack y tus convenciones de código. Configura los permisos en .claude/settings.json y agrega un hook de formato que corrija el estilo automáticamente después de cada edición. Toda la configuración toma menos de cinco minutos. {.answer-block}

ServiceNow desplegó Claude Code entre más de 29.000 empleados¹, y Allianz anunció una alianza que pone Claude a disposición de toda su plantilla a comienzos de 2026². La curva de adopción de la herramienta refleja un patrón: cuando alguien prueba la programación agéntica en su propia terminal, ya no vuelve a copiar y pegar desde una ventana de chat. El recorrido que sigue te lleva de cero a una sesión funcional de Claude Code en unos cinco minutos, con una configuración real que podrás seguir usando después.

En resumen: instala Claude Code con el instalador nativo (curl -fsSL https://claude.ai/install.sh | bash), autentícate desde el 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 que formatee los archivos automáticamente después de cada edición. Todo el proceso toma menos de cinco minutos y la configuración persiste entre sesiones.

Puntos clave

• Desarrolladores independientes: CLAUDE.md y un hook de formato cubren el 80 % de lo que necesitas. Empieza con los permisos predeterminados y aprueba herramientas por adelantado a medida que ganes confianza.
• Líderes de equipo: versiona .claude/settings.json en tu repositorio para que todo el equipo comparta las mismas listas de permitidos y los mismos hooks.
• Ingenieros de seguridad: el modelo de permisos⁴ (Ask/Manual, listas de permitidos, el clasificador del modo auto, --dangerously-skip-permissions) se corresponde directamente con niveles de confianza. El modo Ask exige aprobación explícita para cada escritura y cada comando; sin embargo, desde el 14 de agosto de 2026 las sesiones Pro, Max y Team arrancan en modo auto: fija "defaultMode": "manual" si tu modelo de amenazas exige una persona en cada aprobación.

Requisitos previos

Necesitas dos cosas antes de instalar Claude Code:

Una cuenta de Anthropic. Claude Code requiere una cuenta Pro, Max, Team, Enterprise o Console; el plan gratuito de Claude.ai no incluye acceso³. Los planes de suscripción incluyen el uso de Claude Code (Max 5x por 100 USD al mes o Max 20x por 200 USD al mes, ambos niveles individuales, a mediados de 2026)⁶, o puedes pagar por token con una clave de API de console.anthropic.com. La autenticación ocurre en el navegador después de instalar, así que todavía no hay nada que copiar.

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

Node.js no es necesario para la instalación recomendada. Solo importa si eliges la alternativa con npm que se describe más abajo, que requiere Node.js 22 o posterior desde la v2.1.198.

Instalación

Instala Claude Code con el instalador nativo, el que recomienda Anthropic³:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

En Windows, ejecuta irm https://claude.ai/install.ps1 | iex en PowerShell. El instalador coloca el binario en ~/.local/bin/claude, y las instalaciones nativas se actualizan solas en segundo plano, de modo que te mantienes al día sin actualizaciones manuales.

Comprueba que la instalación fue correcta:

claude --version

Deberías ver un número de versión impreso en la salida estándar. Si aparece el error «command not found», significa que ~/.local/bin no está en tu PATH. Agrégalo al perfil de tu shell y recárgalo:

# Zsh (macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Para un diagnóstico más profundo de tu instalación y tu configuración, ejecuta claude doctor: revisa el binario, el PATH y el estado de las actualizaciones automáticas, y señala instalaciones en conflicto, por ejemplo una copia global de npm que quedó junto a la nativa.

Instalaciones alternativas. Homebrew sirve si prefieres casks gestionados: brew install --cask claude-code (actualiza con brew upgrade --cask claude-code, o define CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 desde la v2.1.129 para actualizaciones en segundo plano mediante el gestor de paquetes). El paquete de npm todavía funciona, pero es heredado y está obsoleto desde la v2.1.15: npm install -g @anthropic-ai/claude-code (Node.js 22+, nunca con sudo⁷), y por dentro instala ese mismo binario nativo. Si empezaste con npm y quieres pasar a la configuración recomendada, instala la versión nativa y elimina la copia de npm con npm uninstall -g @anthropic-ai/claude-code para evitar conflictos de versiones.

En el primer arranque, Claude Code abre tu navegador para la autenticación con OAuth. Inicias sesión, autorizas y Claude Code guarda el estado de autenticación en tiempo de ejecución de forma local en ~/.claude.json. Como alternativa, puedes definir la variable de entorno ANTHROPIC_API_KEY antes de arrancar. En ambos casos, las credenciales se quedan en tu máquina y solo autentican solicitudes a la API.

Primera sesión

Ve a cualquier directorio de proyecto y ejecuta:

cd ~/Projects/my-app
claude

Claude Code inicia una sesión REPL interactiva y carga al arrancar tu CLAUDE.md y tu configuración. En tu primera petición dentro de un proyecto nuevo, Claude explora lo que necesita:

1. Escanea la estructura de directorios para entender la organización del proyecto
2. Lee archivos de configuración como package.json, pyproject.toml o Cargo.toml para identificar el stack técnico
3. Aplica las instrucciones de tu CLAUDE.md desde la raíz del proyecto, ya cargadas al inicio

Prueba una petición sencilla 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, que aparecen en tiempo real antes de cada acción, y las solicitudes de permiso. Las llamadas a herramientas revelan cómo navega Claude por tu base de código. Notarás que lee archivos que quizá no se te habría ocurrido revisar, lo que a menudo saca a la luz contexto útil. Las solicitudes de permiso te muestran exactamente qué pretende cambiar Claude antes de que algo toque el disco. Si una edición propuesta se ve mal, recházala y aclara lo que quieres. Claude ajusta su enfoque según tus comentarios dentro de la misma sesión⁸.

Cómo configurar CLAUDE.md

CLAUDE.md es, con diferencia, el archivo más importante para usar Claude Code con eficacia. Sin él, Claude deduce tu stack a partir del contenido de los archivos y hace suposiciones razonables. Con él, Claude sigue tus convenciones exactas desde la primera petición. La diferencia importa porque el comportamiento basado en deducciones se desvía: Claude podría usar CommonJS en un proyecto ESM, elegir el runner de pruebas equivocado o ignorar tu flujo de migraciones de base de datos. CLAUDE.md elimina esa desviación.

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

touch CLAUDE.md

Esta es una plantilla inicial práctica 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 o TypeScript, la estructura es parecida:

# 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 un CLAUDE.md son las que evitan errores repetidos. Si Claude insiste en importar con require() en lugar de import, agrega «ESM imports only» a Code Standards. Si tu comando de pruebas exige activar antes un entorno virtual, documenta esa secuencia. Claude lee CLAUDE.md al inicio de cada sesión, así que cada línea se convierte en una instrucción persistente cuyo efecto se acumula a lo largo de cientos de interacciones. Los patrones que hacen eficaces a los archivos CLAUDE.md los exploro en Patrones de AGENTS.md, y el principio más amplio de que el contexto es arquitectura. La especificación abierta AGENTS.md⁹ sigue un patrón parecido para otras herramientas agénticas, pero CLAUDE.md admite funciones más ricas, como skills y directorios de reglas.

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

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

El CLAUDE.md de proyecto es el que versionas en el control de código. Los integrantes del equipo que usan Claude Code heredan tus convenciones automáticamente.

Fundamentos de los permisos

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

El modo Ask (llamado «Manual» en la CLI desde la v2.1.200) exige aprobación antes de cada escritura de archivo, cada ejecución de comando y cada acción destructiva. Ves exactamente qué pretende hacer Claude y apruebas o rechazas cada paso. Ten en cuenta que el valor predeterminado cambió el 14 de agosto de 2026: las sesiones Pro, Max y Team ahora arrancan en modo auto, donde un clasificador de seguridad revisa cada acción en lugar de preguntarte; pulsa Shift+Tab para volver a Manual, o fíjalo con "defaultMode": "manual" en la configuración. Sigo recomendando empezar en Manual, porque las solicitudes de aprobación te enseñan cómo funciona Claude Code. Tras unas cuantas sesiones, desarrollas intuición sobre qué operaciones puedes aprobar por adelantado sin riesgo y cuáles merecen revisión cada vez.

Las listas de permitidos te dejan aprobar de antemano herramientas y patrones concretos para que Claude no pregunte cada vez. Se configuran en el archivo .claude/settings.json de tu proyecto:

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

La configuración anterior permite a Claude leer archivos, buscar en la base de código y ejecutar tus comandos de pruebas y migraciones sin preguntar. Sigue preguntando antes de escribir archivos o de ejecutar cualquier otro comando de bash. Fíjate en el patrón: las operaciones de lectura y los comandos conocidos como seguros entran en la lista de permitidos. Las escrituras se quedan en modo Ask, porque quieres revisar lo que Claude escribe antes de que llegue al disco.

Saltarse los permisos de forma peligrosa (--dangerously-skip-permissions) desactiva las confirmaciones; los comandos de borrado catastrófico siguen pidiendo confirmación, una red de seguridad presente desde la v2.1.126. La bandera existe exclusivamente para pipelines de CI/CD y flujos automatizados donde no hay una persona presente para aprobar. Nunca la uses en sesiones interactivas sobre una base de código que te importe.

El sistema de permisos hace que Claude Code sea seguro en proyectos reales. La progresión es deliberada: empieza en modo Ask para entender el funcionamiento, agrega a la lista de permitidos las operaciones que se vuelven repetitivas y deja las escrituras bajo control para revisar siempre los cambios antes de que se apliquen.

Tu primer hook

Los hooks son comandos de shell que se ejecutan en puntos concretos del ciclo de vida de Claude Code⁵. Escribí un tutorial completo de hooks que construye cinco hooks de producción desde cero, y mi artículo sobre crear skills personalizados cubre el siguiente nivel de automatización. Los hooks resuelven un problema de fondo de 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 diez ediciones de archivo aparece una inconsistencia de estilo. Los hooks aportan garantías deterministas donde el modelo solo ofrece probabilidades. Un hook de formato ejecuta tu formateador después de cada escritura, siempre, sin importar lo que haya decidido el modelo. Este es un primer hook práctico: dar formato automático a los 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 las herramientas Edit o Write. Claude Code asigna a $FILE_PATH la ruta del archivo modificado. Prettier lo formatea en el sitio, y || true garantiza 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 iniciales prácticos que recomiendo:

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

Los hooks convierten Claude Code de una herramienta conversacional en un entorno de desarrollo con reglas. Incluso uno o dos hooks bien elegidos eliminan categorías enteras de errores.

Cuando las cosas salen mal

Cuatro situaciones aparecen una y otra vez durante la primera semana de uso de Claude Code. Conocerlas de antemano te ahorra tiempo de depuración.

Claude ignora las instrucciones de tu CLAUDE.md. La causa más común: Claude ya leyó el archivo y guardó en caché su comprensión antes de que lo editaras. Ejecuta /clear para reiniciar el contexto, o abre una sesión nueva. Claude vuelve a leer CLAUDE.md al iniciar la sesión, no en cada petición. Si Claude sigue ignorando las instrucciones tras una sesión nueva, revisa si un CLAUDE.md de mayor prioridad, el del nivel de usuario en ~/.claude/CLAUDE.md, entra en conflicto con el archivo de tu proyecto.

Claude hace un cambio que no aprobaste. Si añadiste a la lista de permitidos un patrón demasiado amplio, una regla genérica de Bash en lugar de un prefijo acotado como Bash(python -m pytest:*), Claude puede ejecutar comandos sin preguntar. Acota tus patrones. Lo más seguro es permitir solo operaciones de lectura y comandos concretos nombrados uno a uno. Si Claude ya hizo un cambio no deseado, git diff muestra exactamente qué cambió y git checkout -- <file> lo revierte.

La ventana de contexto se llena durante una sesión larga. Claude Code compacta los mensajes anteriores a medida que se llena la ventana de contexto (los modelos predeterminados tienen ventanas de 1 millón de tokens a mediados de 2026, así que ese límite tarda mucho más en llegar que antes), pero la compactación puede descartar detalles importantes del principio de la conversación. En sesiones de más de 30 minutos, haz commit de los cambios que funcionan cada cierto tiempo y abre una sesión nueva con /clear. El contexto fresco vuelve a leer CLAUDE.md y arranca limpio. Yo hago commit después de cada subtarea terminada, lo que me da a la vez un punto de reversión y un límite natural de sesión.

Claude edita el archivo equivocado o hace cambios innecesarios. Cuando Claude se pone a «mejorar» código que no le pediste tocar, el problema suele ser la ambigüedad de la petición. 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 todas las llamadas». La precisión reduce los efectos secundarios indeseados. Si Claude ya hizo ediciones no deseadas, git diff muestra exactamente qué cambió y git checkout -- <file> revierte archivos concretos sin perder el resto del trabajo.

Próximos pasos

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

La guía cubre la gestión de la ventana de contexto, la delegación en subagentes, la activación automática de skills y los patrones que emergen tras meses de uso diario de Claude Code. Si esta guía rápida te resultó útil, la guía completa es el siguiente paso natural. Como referencia de consulta rápida de cada comando, bandera y atajo, consulta la hoja de referencia de Claude Code.

Si tu proyecto es una app de iOS o macOS, la guía de desarrollo iOS con agentes cubre los patrones de Claude Code propios de Apple: la integración con XcodeBuildMCP para compilaciones y simuladores, los hooks para desarrollo en Apple que protegen .pbxproj de las ediciones del agente, y la Serie del ecosistema Apple, dedicada a App Intents, servidores MCP, Foundation Models y la conexión entre agente y plataforma a nivel de framework.

Referencias

FAQ

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

Necesitas una cuenta de Anthropic (Pro, Max, Team, Enterprise o Console; el plan gratuito no incluye Claude Code) y cualquier emulador de terminal. Claude Code funciona en macOS 13+, Linux y Windows, tanto de forma nativa como con WSL. La instalación recomendada es la del instalador nativo, curl -fsSL https://claude.ai/install.sh | bash, que no necesita Node.js, ni Docker, ni ningún otro runtime. Node.js 22+ solo hace falta si eliges la alternativa con npm (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, tus convenciones de código y tus comandos habituales. Sin él, Claude deduce tu configuración a partir del contenido de los archivos y hace suposiciones razonables, pero esas suposiciones se desvían de una sesión a otra. Con CLAUDE.md, Claude sigue tus convenciones exactas desde la primera petición, en cada sesión. Admite una jerarquía de tres niveles: usuario (~/.claude/CLAUDE.md), proyecto (./CLAUDE.md) y directorio (./src/CLAUDE.md), combinados por orden de especificidad.

¿Cuánto cuesta Claude Code?

Claude Code admite dos modelos de facturación. El modelo de pago por uso de la API cobra por token según las tarifas estándar de la API de Anthropic⁶. Una sesión típica de 30 a 60 minutos cuesta entre 0,50 y 3,00 USD según el tamaño de la base de código y el volumen generado. Como alternativa, los planes Max⁶ de Anthropic (Max 5x por 100 USD al mes, Max 20x por 200 USD al mes, ambos niveles individuales, a mediados de 2026) incluyen el uso de Claude Code con límites de uso más altos. Puedes vigilar tu consumo 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, ve al directorio de tu proyecto y ejecuta claude igual que lo harías en una terminal independiente. Claude Code lee y edita archivos en el disco, así que los cambios aparecen de inmediato en tus pestañas del editor de VS Code. Para este flujo no hace falta ninguna extensión, aunque también existe una extensión de VS Code dedicada si prefieres un panel integrado. Algunos desarrolladores mantienen una terminal dividida y dedicada a Claude Code junto a su editor, algo 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 Ask de Claude Code exige aprobación explícita antes de cada escritura de archivo y cada ejecución de comando. Nada cambia en el disco sin tu confirmación. El sistema de permisos, combinado con hooks capaces de bloquear operaciones peligrosas como los push forzados o los comandos de shell destructivos, hace que Claude Code resulte práctico para el trabajo en producción. Yo uso Claude Code a diario en proyectos que atienden a usuarios reales. La clave está en empezar en modo Ask, entender qué hace cada llamada a herramienta antes de aprobarla y permitir poco a poco solo las operaciones en las que confías. El control de versiones es la última red de seguridad: haz commit antes de cualquier sesión importante de Claude Code para poder revertir siempre.

¿Cuál es el error más común entre quienes empiezan?

Darle a Claude demasiado contexto en la petición en lugar de ponerlo en CLAUDE.md. Quienes empiezan tienden a pegar todos sus estándares de código en cada petición, lo que desperdicia espacio de la ventana de contexto y produce resultados inconsistentes entre sesiones. Traslada las instrucciones recurrentes a CLAUDE.md una sola vez y reserva las peticiones para lo específico de cada sesión. El segundo error más común: permitir Bash(*) en lugar de comandos concretos. Una lista de permitidos de Bash con comodín deja que Claude ejecute cualquier comando de shell sin preguntar, lo que anula el propósito del sistema de permisos.