Cómo instalar y configurar Claude Code en 2026 — Guía completa para empresa y desarrolladores

Pre-requisitos antes de instalar Claude Code

Antes de ejecutar el primer comando, verificá que tenés los cuatro elementos siguientes. Saltarse la validación previa es la causa número uno de frustraciones en la primera instalación — todos los errores que vemos con más frecuencia trazan origen a uno de estos cuatro puntos.

1. Node.js 18 o superior. Claude Code se distribuye como paquete npm global y requiere Node 18+. Recomendamos Node 20 LTS por soporte a largo plazo. Verificá con node --version. Si tenés Node 16 o inferior, no basta con actualizar — conviene migrar a nvm (Node Version Manager) para poder gestionar múltiples versiones sin romper proyectos existentes.

2. Cuenta Anthropic con acceso a Claude. Dos rutas válidas. Ruta A: suscripción Claude Pro (20 USD/mes) desde claude.com/pricing que incluye uso razonable de Claude Code. Ruta B: API key pay-as-you-go generada en console.anthropic.com — factura por tokens consumidos. Para uso personal intensivo Claude Pro suele salir más barato; para automatizaciones batch o CI/CD la API directa es más flexible.

3. Editor de código. Claude Code vive en terminal — no requiere editor específico. Pero tendrás mejor experiencia visualizando los cambios en un editor. VS Code es el recomendado por integración nativa (hay extensiones oficiales de Anthropic). JetBrains IDEs, Neovim y Sublime también funcionan perfectamente.

4. Sistema operativo soportado. macOS 12+, Linux (cualquier distribución moderna con glibc ≥ 2.31) y Windows 10/11 vía WSL2. Para Windows, instalar Ubuntu desde Microsoft Store y ejecutar Claude Code dentro del entorno WSL2 es la ruta óptima. PowerShell nativo funciona parcialmente pero con limitaciones en hooks y MCPs — WSL2 es la elección sensata.

Instalación paso a paso — los 6 pasos reales

Esta es la secuencia exacta que ejecutamos nosotros cada vez que configuramos Claude Code en una máquina nueva (developer onboarding o máquina propia tras reinstalación). Los pasos 1 y 2 son setup externo; los pasos 3 a 6 son los que realmente instalan y dejan Claude Code operativo.

Paso 1 — Crear cuenta Anthropic y obtener acceso

Ir a console.anthropic.com y crear cuenta. Si preferís Claude Pro, suscribirse desde claude.com/pricing con la misma cuenta. Si preferís API pay-as-you-go, generar una API key desde Settings → API Keys → Create Key. Habilitar 2FA antes de cualquier otra cosa — es una cuenta con acceso a modelos LLM y potencialmente a billing. Guardar la API key en un gestor de contraseñas (1Password, Bitwarden) — nunca en repos o mensajes Slack.

Paso 2 — Instalar Node.js 18 o superior

Verificar si ya tenés Node con node --version. Si la versión es inferior a 18 o no tenés Node instalado:

En macOS y Linux, instalar nvm (preferido) y luego la versión LTS:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install 20 && nvm use 20

En Windows, usar nvm-windows o descargar desde nodejs.org. Confirmar con node --version y npm --version.

Paso 3 — Instalar Claude Code vía npm global

Con Node 18+ listo, instalar el paquete global:

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

Si aparece EACCES permission denied, NO uses sudo — es señal de que tu configuración npm global tiene permisos raíz (problema frecuente en macOS instalado con el instalador oficial Node). La solución correcta es migrar a nvm o reconfigurar el prefix de npm a tu home: npm config set prefix ~/.npm-global y añadir ese bin al PATH. Usar sudo resuelve el síntoma pero deja el sistema con un mix de permisos que causará más errores después.

Verificar instalación: claude --version debería imprimir la versión instalada.

Paso 4 — Autenticar y configurar variables de entorno

Ejecutar claude desde cualquier directorio. La primera invocación detecta que no hay autenticación y abre un flujo de onboarding en el navegador — login con tu cuenta Anthropic y autorización del cliente. Tras autorizar, Claude Code guarda el token localmente.

Alternativa si preferís API key directa: exportar la variable en tu shell rc:

export ANTHROPIC_API_KEY="sk-ant-..."

Añadir esa línea a ~/.zshrc (zsh) o ~/.bashrc (bash). Recargar con source ~/.zshrc. Nunca committear la API key en repos ni pegar en Slack, issues de GitHub o documentos compartidos. Validar todo con claude --help — debe mostrar los comandos disponibles sin pedir auth.

Paso 5 — Ejecutar el primer comando en un proyecto test

Crear un proyecto de prueba para validar que la tool use y el filesystem funcionan end-to-end antes de apuntar Claude Code a un repo real importante:

mkdir ~/test-claude && cd ~/test-claude
git init
echo "# Test proyecto" > README.md
claude

Esto abre la sesión interactiva (REPL). Probá un prompt simple como «describe el repositorio» o «lista los archivos». Claude debería leer el directorio usando su tool de filesystem y responder con el contenido. Salir con /exit. Si ves la respuesta, la instalación está 100% funcional.

Paso 6 — Crear CLAUDE.md del proyecto como manifiesto

Este paso diferencia a quien instaló Claude Code de quien lo opera bien. CLAUDE.md es un archivo Markdown en la raíz del proyecto que Claude lee automáticamente al inicio de cada sesión en ese directorio. Funciona como contrato explícito entre humano y agente.

Mínimo viable CLAUDE.md:

# Nombre del proyecto
## Stack — Node 20, Astro 5, Tailwind, Supabase
## Convenciones — camelCase JS, kebab-case archivos, commits conventional
## Comandos útiles — npm run dev, npm test, npm run build
## Glosario — términos de dominio específicos
## Decisiones — link a carpeta de decisiones arquitectónicas o resumen inline

Con CLAUDE.md básico, cada sesión arranca con el agente calibrado al proyecto — sin él, Claude descubre cada vez desde cero y pierde contexto valioso. Es el ROI más alto por minuto invertido en todo el setup.

Configuración para empresa — la extensión que separa poder de caos

Los seis pasos anteriores dejan a un developer individual productivo. Para un equipo, Claude Code sin governance adicional produce deuda técnica invisible rápidamente — cada developer instala MCPs distintos, las API keys acaban en Slack, los hooks se configuran a mano y las convenciones se pierden. Estos son los cinco bloques que añadimos en los proyectos donde implantamos Claude Code para equipos.

1. Gestión centralizada de API keys. Una API key corporativa, gestionada por IT, rotada trimestralmente, nunca committeada. Se distribuye vía variables de entorno del sistema operativo o via gestor de secretos (1Password Secrets Automation, HashiCorp Vault, AWS Secrets Manager). Jamás en .env del repo — el .env se usa para configuración no sensible y .env.example documenta las claves esperadas sin valores.

2. Variables de entorno seguras. Crear .env.example con los nombres de las variables (ANTHROPIC_API_KEY=, CLAUDE_MODEL=, etc.) pero sin valores. Añadir .env al .gitignore desde el día uno del proyecto. Documentar en el README cómo obtener los valores reales — típicamente un link al gestor de secretos corporativo o una instrucción para pedirlos a IT.

3. MCPs compartidos. Los servidores Model Context Protocol extienden las capacidades del agente. Los tres MCPs base que instalamos en casi todos los equipos: Filesystem (acceso controlado a directorios), Context7 (documentación de librerías up-to-date) y Playwright (automatización de navegador para verificación visual). Configurarlos en .claude/settings.json a nivel proyecto para que todos los developers los carguen igual al clonar el repo.

4. Permisos granulares. settings.json permite definir permissions.allow y permissions.deny por tool. En entornos empresariales, denegar Bash(rm -rf *), limitar WebFetch a dominios corporativos y requerir confirmación humana antes de git push son mínimos razonables. El objetivo no es cortar al agente las alas — es evitar el accidente de madrugada.

5. Hooks automatizados. Hooks ejecutan scripts en puntos de ciclo de vida: pre-commit (lint, format), post-tool-use (log auditoría), on-session-start (cargar contexto). Para equipos que trabajan con Claude Code en producción, configurar al menos un hook pre-commit con eslint + prettier + typecheck evita que cambios con errores triviales lleguen al repo.

En GSC aplicamos este patrón completo en los proyectos de implantación Claude Code. El onboarding de un developer nuevo pasa de 2 horas (setup personal) a 30 minutos (clonar repo, ejecutar un setup.sh, validar con claude --help) porque toda la config está versionada.

Flujos de trabajo esenciales — los cuatro modos que debés conocer

Claude Code tiene más capacidades de las que parece al primer vistazo. Estos cuatro modos cubren el 90% de los casos de uso reales. Dominarlos el día uno multiplica la productividad del resto del equipo técnico.

1. Chat interactivo vs non-interactive

Modo interactivo (REPL): ejecutar claude sin argumentos abre una sesión donde tipeas prompts, Claude responde y podés seguir iterando. Ideal para exploración, debugging en vivo y pair programming.

Modo non-interactive: claude -p "arregla los errores de ESLint en src/" ejecuta el prompt, Claude actúa y termina. Ideal para automatización, scripts y CI/CD. Combinable con --output-format stream-json para pipelines.

2. Plan mode — el modo que previene accidentes

claude --permission-mode plan hace que Claude proponga acciones sin ejecutarlas. El agente genera un plan detallado y espera aprobación humana antes de cualquier modificación. Uso crítico para refactors grandes, auditorías y cualquier operación sobre código en producción. Regla interna GSC: plan mode por defecto en cualquier repo con main protegido.

3. Agents especializados

Claude Code permite definir agentes custom en .claude/agents/*.md (proyecto) o ~/.claude/agents/*.md (global). Cada agente tiene un prompt de sistema específico — por ejemplo code-reviewer.md para revisión de PRs, security-auditor.md para auditoría OWASP, test-writer.md para generar tests. Invocarlos con /agents dentro de sesión interactiva. Permite especializar el agente sin rebuild global.

4. MCPs — el estándar abierto que conecta Claude con tu stack

Model Context Protocol es un protocolo abierto de Anthropic (con implementaciones también en OpenAI y otros) que expone herramientas externas al agente. Configuración típica en settings.json:

"mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] }, "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] } }

Hay catálogo creciente en modelcontextprotocol.io. Empezá con los tres base (filesystem, context7, playwright); añadí especializados según tu stack (Supabase, Stripe, Linear, Sanity, etc.) cuando los necesites realmente.

Troubleshooting común — los 7 errores que vemos con más frecuencia

Estos son los errores reales observados en instalaciones GSC y en clientes. No son el universo completo — son los que aparecen más de una vez y tienen solución directa. Si chocás con uno distinto, el canal soporte oficial Anthropic y el repo público de Claude Code tienen más detalle.

Dos consejos operativos que no caben en la tabla. Primero, si algo falla de forma rara (contexto que se pierde, respuestas inconsistentes), probá primero /clear en la sesión. Resuelve más del 30% de incidencias aparentemente misteriosas — son artefactos de contexto corrupto. Segundo, mantené Claude Code actualizado con npm update -g @anthropic-ai/claude-code al menos semanalmente. El equipo de Anthropic lanza fixes con frecuencia y muchos bugs reportados desaparecen con el upgrade.

Experiencia GSC operando Claude Code — data real del dogfooding

Esta misma web — genaisapiens.com — se migró de un SPA React (montado previamente con Lovable) a Astro 5 SSG usando Claude Code como ejecutor principal bajo un flujo Bridge autónomo. No es caso sintético: es el código que estás leyendo ahora mismo renderizado.

Data objetiva Fase 1 (retrospectiva interna): 24 commits convencionales (feat(phase-1):, chore(phase-1):, docs(phase-1):) desde el purge de Lovable hasta el cierre de fase. 26 prompts totales ejecutados (11 R de contexto, 12 P de planning, 23 I de implementación, 2 V de verificación, 2 A de administración). ~30 horas calendario, de las cuales ~20 fueron Bridge autónomo activo. Resultado: siete páginas Astro, 26 HTML generados, performance Lighthouse 100 en desktop en 4 de 5 páginas indexables, visual parity preservada.

Lo que no verás en reviews sintéticos:

La curva de aprendizaje es real. MCP, hooks, CLAUDE.md disciplinado y patrones del agente no son plug-and-play. Un developer que nunca haya vivido en terminal tardará días en rendir. Si el objetivo es onboarding de menos de un día, Cursor gana. Si el objetivo es delegar tareas agénticas con governance, Claude Code es la herramienta — con inversión inicial.

Autonomía exige governance. El agente se equivoca — y lo hace. En producción usamos soul.md (valores del proyecto), known-issues.md (deuda documentada), retrospectivas por fase y heartbeats cada 5 prompts I para mantener el loop sano. Sin esa infraestructura, Claude Code autónomo genera deuda técnica invisible.

Tests son imprescindibles. El agente acelera la generación de bugs si no hay red de seguridad. En esta web mantenemos astro check + Lighthouse baseline + visual parity antes de cada cierre de fase. Sin verificadores automatizados, la aceleración es ilusoria.

Si dudás entre Claude Code y alternativas como Cursor o GitHub Copilot, escribimos una comparativa técnica honesta 3-way con criterios de decisión por use case. Y si ya decidiste por Claude Code y querés usarlo para crear un agente de IA en tu empresa, ese tutorial es el siguiente paso operativo. Más casos de éxito con Claude Code en ecommerce, legal, medical y logística.

Preguntas frecuentes

Preguntas frecuentes sobre instalar Claude Code