⚙️ Instalación y configuración

Node.js v18+ (o Bun), terminal con soporte para colores y acceso a internet para la autenticación inicial.

Sin el entorno adecuado, la instalación falla silenciosamente. Verificarlo antes te ahorra 30 min de depuración.

Node.js LTS, verifica con node -v, npm v9+ o Bun v1+, compatibilidad con macOS/Linux/WSL2.

Un solo comando instala Claude Code globalmente: npm install -g @anthropic-ai/claude-code.

La instalación global hace que el comando claude disponible en cualquier directorio del sistema.

Flag -g (global), permisos de carpeta de npm, alternativa con Bun: bun install -g.

Ejecutar claude --version e claude --help para confirmar que el binario está en el PATH.

Detecta errores de PATH antes de perder tiempo con la autenticación. «command not found» tiene una solución sencilla.

PATH del sistema, which claude, salida esperada con número de versión.

Claude Code lanza actualizaciones frecuentes con nuevos modelos y features. El mismo comando de instalación con npm update -g actualiza.

Las versiones antiguas no son compatibles con los modelos nuevos. La actualización toma 30 segundos y trae mejoras importantes.

npm update -g @anthropic-ai/claude-code, revisar el changelog en GitHub, raros cambios incompatibles.

Claude Code se ejecuta de forma nativa en macOS y Linux. En Windows, usa WSL2 (Windows Subsystem for Linux) para una mejor compatibilidad.

Cada OS tiene particularidades de permisos y PATH distintas. Conocer las diferencias evita horas de frustración.

WSL2 en Windows, Homebrew en macOS para Node.js, distribuciones de Linux recomendadas (Ubuntu 22+).

Los 5 errores más frecuentes: EACCES (permisos de npm), command not found (PATH), ENOENT (versión antigua de Node), network timeout y conflicto de versión.

Los errores de instalación bloquean al 30% de los principiantes. Tener presente el diagnóstico permite resolverlos en minutos.

sudo npm install -g (solución EACCES), nvm para varias versiones de Node, verificar la caché de npm con npm cache clean --force.

Escribir claude en la terminal abre el REPL interactivo. En la primera ejecución, redirige a la autenticación.

Entender el flujo del primer inicio evita confusiones con los prompts de inicio de sesión y el terminal interactivo.

REPL (Read-Eval-Print Loop), terminal interactiva, flujo automático de onboarding.

Claude Code se autentica mediante browser OAuth con tu cuenta de Anthropic o mediante una API key. Las credenciales se guardan en ~/.claude/.

Elegir entre una cuenta y una API key determina la facturación, los límites y el modelo disponible.

OAuth2 browser flow, carpeta ~/.claude/, triggers, scripts — y el caso real

API key = pagas por uso (tokens). Claude Max = suscripción mensual con un límite generoso. Para un uso intensivo, la suscripción suele convenir más.

Una elección equivocada puede generar costos inesperados o limitar proyectos que necesitan muchas llamadas diarias.

Precios de tokens, límites de tasa, Claude Pro vs Max, variable de entorno ANTHROPIC_API_KEY.

El prompt > acepta lenguaje natural, comandos slash (/help, /clear) y referencias a archivos con @.

Dominar los atajos del REPL multiplica la productividad — sin tener que reescribir el contexto en cada mensaje.

Comandos /help, /clear, /status, referencias a archivos con @, texto multilínea con Enter vs. Shift+Enter.

Pedirle a Claude que cree un archivo, lea un proyecto y explique código existente: las primeras tareas prácticas.

Ponerse manos a la obra de inmediato consolida el aprendizaje y desmitifica el uso de la herramienta.

Prompt de tarea, confirmación de acción, diferencia entre lectura (segura) y escritura (requiere permiso).

Salir con Ctrl+C o /exit. Retoma el contexto anterior con claude --resume o abriendo el mismo directorio.

Las sesiones largas son normales en proyectos reales. Saber retomarlas sin perder contexto es esencial.

Contexto guardado en el directorio, .claude/ local, claude --resume, historial de conversaciones.

Archivo JSON que controla los permisos, las herramientas, los hooks y los comportamientos de Claude Code. Ubicado en ~/.claude/settings.json (global) o .claude/settings.json (proyecto).

Si no conoces settings.json, aceptas todos los valores predeterminados y recibes solicitudes de permiso para cada acción trivial.

Jerarquía user > project, clave permissions, tools, merge vs. override.

Cada herramienta se puede configurar con allow (ejecutar sin preguntar), ask (pedir confirmación) o deny (bloquear).

Los permisos incorrectos bloquean el workflow o exponen operaciones destructivas. El equilibrio adecuado es productivo y seguro.

Clave allow lista patrones glob, alcance por herramienta (Bash, Read, Write, Edit), override por proyecto.

Reglas generales: leer es seguro (allow), escribir dentro del proyecto está bien, los comandos externos del sistema requieren atención y delete/drop requiere ask.

Permitir todo (allow *) es peligroso en máquinas de producción. Permitir muy poco vuelve inútil la herramienta.

Principio del mínimo privilegio, glob src/** para limitar el alcance, deny para comandos destructivos.

Modos predefinidos: default (pide confirmación para todo), --dangerously-skip-permissions (sin confirmación — solo desarrollo local), modo headless para CI/CD.

En pipelines automatizados necesitas un modo no interactivo. En producción, nunca uses dangerously-skip.

Flag --print para la salida no interactiva, variables de entorno para CI, claude --no-tty.

Archivo Markdown que Claude lee automáticamente en cada sesión. Es el "briefing" del proyecto: contexto, convenciones y comandos especiales.

Sin CLAUDE.md, repites el contexto en cada sesión. Con él, Claude ya conoce el stack, el estilo y las reglas del proyecto.

Posición ./CLAUDE.md o ~/.claude/CLAUDE.md, resumido automático, CLAUDE.md como memoria externa.

Configuración global (~/.claude/settings.json) se aplican a todos los proyectos. Los ajustes del proyecto (.claude/settings.json) se aplican a ese repo.

Configurar correctamente la jerarquía evita conflictos entre proyectos personales y profesionales.

Fusionar objetos JSON, precedencia project > user, versionar .claude/settings.json en el git del proyecto.

Model Context Protocol (MCP) es un estándar abierto para conectar Claude con herramientas externas: bases de datos, APIs, sistemas de archivos, servicios en la nube.

Con MCP, Claude deja de ser un chatbot y se convierte en un agente que accede a datos reales de tu entorno.

Servidor MCP, cliente de Claude Code, JSON-RPC, herramientas expuestas mediante MCP, repositorio oficial de servidores.

Agregar un servidor MCP a settings.json en la clave mcpServers. Claude se inicializa y expone las herramientas automáticamente.

Conectar un MCP lleva 2 minutos. Sin este conocimiento, solo usas las herramientas nativas de Claude.

Clave mcpServers en el JSON, command e args, verificar con /mcp en el REPL.

Servidores MCP disponibles: filesystem, GitHub, PostgreSQL, Slack, Google Drive, Puppeteer (browser), SQLite y decenas más.

Cada MCP amplía drásticamente lo que Claude puede hacer. GitHub MCP + Claude = revisión de código automatizada.

Repositorio modelcontextprotocol/servers, MCP oficiales vs. comunitarios, seguridad de servidores de terceros.

Abrir Claude Code en un directorio existente o crear un proyecto desde cero con estructura de archivos, CLAUDE.md y configuración inicial.

Empezar un proyecto correctamente (con CLAUDE.md y settings) garantiza la consistencia durante todo el desarrollo.

cd meu-projeto && claude, estructura de directorios recomendada, /init para generar CLAUDE.md automáticamente.

Crear un proyecto, escribir CLAUDE.md, realizar una tarea real (p. ej., crear una API REST), revisar los cambios y hacer commit, todo con Claude como guía.

Ver el ciclo completo (intención → código → revisión → commit) consolida el modelo mental de uso de Claude Code.

Bucle de desarrollo, diff visual, confirmación de cambios, integración con git, resultado de tareas complejas.

Con la instalación, la autenticación, los settings y MCP configurados, estás listo para explorar Skills (T3), Automatización (T4) y Proyectos reales (T5).

La configuración es la base. Todo lo que viene después depende de que el entorno esté bien configurado.

Skills personalizadas, hooks de automatización, worktrees, proyectos con varios archivos, CI/CD con Claude.