TL;DR: Claude Code es un CLI agéntico que lee su código fuente, ejecuta comandos y modifica archivos a través de un sistema por capas de permisos, hooks, integraciones MCP y subagents. Domine cinco sistemas centrales (configuración, permisos, hooks, MCP y subagents) y desbloqueará una productividad multiplicadora. Elija el nivel de modelo que se ajuste a cada tarea — Opus para razonamiento complejo, Sonnet para trabajo general, Haiku para exploración rápida — o estandarice en Opus si la calidad es su única variable. Use hooks (no prompts) para todo lo que deba ejecutarse siempre.

Claude Code opera como un sistema agéntico, no como una interfaz de chat con conocimientos de programación. El CLI lee su código fuente, ejecuta comandos, modifica archivos, gestiona flujos de trabajo con git, se conecta a servicios externos a través de MCP y delega tareas complejas a subagents especializados. Todo fluye a través de una interfaz de línea de comandos que se integra en la forma en que los desarrolladores realmente trabajan. A febrero de 2026, el 4% de los commits públicos en GitHub (~135.000 por día) son creados por Claude Code — un crecimiento de 42.896× en 13 meses desde la vista previa de investigación — y el 90% del código propio de Anthropic está escrito por IA.¹¹⁰

La diferencia entre un uso casual y un uso efectivo de Claude Code se reduce a cinco sistemas centrales. Domínelos y Claude Code se convertirá en un multiplicador de fuerza:

1. Jerarquía de configuración: controla el comportamiento
2. Sistema de permisos: regula las operaciones
3. Sistema de hooks: habilita la automatización determinista
4. Protocolo MCP: extiende las capacidades
5. Sistema de subagents: gestiona tareas complejas de múltiples pasos

Conclusiones Clave

• Cinco sistemas determinan su efectividad: la jerarquía de configuración, los permisos, los hooks, MCP y los subagents controlan todo, desde el comportamiento hasta la automatización.
• Delegue el trabajo a la Capa de Delegación: los subagents previenen la saturación de contexto al aislar la exploración en ventanas de contexto limpias, devolviendo únicamente resúmenes.
• Los hooks garantizan la ejecución; los prompts no: use hooks para linting, formateo y verificaciones de seguridad que deben ejecutarse cada vez, independientemente del comportamiento del modelo.
• La jerarquización de modelos ahorra costos sin sacrificar calidad: dirija la exploración de subagents a modelos más económicos y reserve Opus para razonamiento arquitectónico genuino — o estandarice en Opus si la calidad es su única variable.
• MCP conecta a Claude con su cadena de herramientas: bases de datos, GitHub, Sentry y más de 3.000 integraciones extienden Claude más allá de la lectura de archivos y los comandos bash.

Pasé meses llevando Claude Code al límite en bases de código en producción, pipelines de CI/CD y despliegues empresariales. Esta guía destila esa experiencia en la referencia completa que desearía haber tenido cuando empecé. Cada función incluye la sintaxis real, ejemplos de configuración concretos y los casos límite que hacen tropezar incluso a los usuarios experimentados.

Cómo Usar Esta Guía

Esta es una referencia de más de 5.000 líneas — no necesita leerla de principio a fin. Comience donde se ajuste a su nivel de experiencia:

Use Ctrl+F / Cmd+F en su navegador para buscar flags, comandos o claves de configuración específicas. La Tarjeta de Referencia Rápida al final proporciona un resumen escaneable de todos los comandos principales.

Cómo funciona Claude Code: el modelo mental

Antes de explorar las funciones en detalle, es importante comprender cómo la arquitectura de Claude Code determina todo lo que puede hacer con él. El sistema opera en tres capas:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Capa central (Core Layer): Su conversación principal. Cada mensaje, lectura de archivo y salida de herramienta consume contexto de una ventana compartida (200K tokens estándar⁹⁸, 1M tokens con Opus 4.6 o modelos de contexto extendido). Cuando el contexto se llena, Claude pierde el seguimiento de decisiones anteriores y la calidad se degrada. Esta capa tiene un costo por token.

Capa de delegación (Delegation Layer): Los subagents se generan con contextos limpios, realizan trabajo enfocado y devuelven resúmenes. Los resultados de exploración no saturan su conversación principal; solo las conclusiones regresan. Puede dirigir los subagents a niveles de modelo más económicos para exploración, o usar su modelo principal en todo momento si la calidad importa más que el costo.

Capa de extensión (Extension Layer): MCP conecta servicios externos (bases de datos, GitHub, Sentry). Los hooks garantizan la ejecución de comandos de shell independientemente del comportamiento del modelo. Los skills codifican experiencia de dominio que Claude aplica automáticamente. Los plugins empaquetan todo esto para su distribución.

La idea clave: La mayoría de los usuarios trabajan exclusivamente en la capa central, observando cómo el contexto se satura y los costos aumentan. Los usuarios avanzados delegan la exploración y el trabajo especializado a la capa de delegación, mantienen la capa de extensión configurada para su flujo de trabajo, y usan la capa central únicamente para orquestación y decisiones finales.

Tabla de contenidos

1. ¿Cómo instalo Claude Code?
2. Inicio rápido: su primera sesión
3. Modos de interacción principales
4. Sistema de configuración en profundidad
5. ¿Qué modelo debo elegir?
6. ¿Cuánto cuesta Claude Code?
7. Marcos de decisión
8. ¿Cómo funciona el sistema de permisos?
9. ¿Cómo funcionan los hooks?
10. ¿Qué es MCP (Model Context Protocol)?
11. ¿Qué son los subagents?
12. ¿Qué es el modo de pensamiento extendido?
13. Estilos de salida
14. Slash Commands
15. ¿Cómo funcionan los skills?
16. Sistema de plugins
17. ¿Cómo funciona la memoria?
18. Imágenes y entrada multimodal
19. ¿Cómo funciona la integración con Git?
20. ¿Cómo uso Claude Code en mi IDE?
21. Patrones de uso avanzado
22. Agentes remotos y en segundo plano [VISTA PREVIA DE INVESTIGACIÓN]
23. Claude in Chrome
24. Claude Code en Slack [VISTA PREVIA DE INVESTIGACIÓN]
25. Optimización de rendimiento
26. ¿Cómo depuro problemas?
27. Implementación empresarial
28. Referencia de atajos de teclado
29. Mejores prácticas
30. Recetas de flujos de trabajo
31. Guía de migración
32. Orientación por tipo de audiencia
33. Tarjeta de referencia rápida
34. Registro de cambios
35. Referencias

¿Cómo instalo Claude Code?

Requisitos del sistema

Claude Code funciona en macOS 10.15+, Ubuntu 20.04+/Debian 10+, y Windows 10+ a través de WSL o Git Bash. El sistema requiere un mínimo de 4 GB de RAM y una conexión a internet activa.⁹⁹ La compatibilidad con shells funciona mejor con Bash, Zsh o Fish.

Para Windows, tanto WSL 1 como WSL 2 funcionan. Git Bash también funciona si prefiere Windows nativo. Alpine Linux y otros sistemas basados en musl requieren paquetes adicionales:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Métodos de instalación

Instalación nativa (recomendada)

El binario nativo ofrece la experiencia más limpia sin dependencia de Node.js:

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

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Para instalación de una versión específica:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Instalación por NPM (obsoleta)

Nota: A partir de la v2.1.15, las instalaciones por npm muestran un aviso de obsolescencia. El binario nativo es ahora el método de instalación recomendado. Migre con claude install.

Para entornos heredados donde npm aún sea necesario:

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

Nunca use sudo con la instalación por npm. Crea problemas de permisos que complican todo posteriormente.

Migración desde una instalación existente

Si tiene una instalación anterior basada en npm, migre al binario nativo:

claude install

Opciones de autenticación

Claude Code admite tres rutas de autenticación, cada una con diferentes ventajas y desventajas:

Claude Console (facturación por API)

Conéctese directamente a la API de Anthropic a través de platform.claude.com (anteriormente console.anthropic.com). Cree una cuenta, configure la facturación y autentíquese a través del CLI. La Console proporciona facturación basada en uso con acceso completo a la API. Se crea automáticamente un workspace dedicado llamado “Claude Code”; no puede crear claves API para este workspace, pero puede monitorear el uso.

Suscripción Claude Pro o Max

Use las credenciales de su cuenta de claude.ai. La suscripción cubre tanto la interfaz web como el uso del CLI bajo un único plan mensual. La suscripción simplifica la facturación para usuarios individuales que desean costos predecibles.

Plataformas empresariales

AWS Bedrock, Google Vertex AI y Microsoft Foundry proporcionan acceso de nivel empresarial con relaciones de facturación en la nube existentes:

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

Para implementaciones empresariales detrás de proxies o a través de gateways de LLM:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Verificación

claude doctor

El comando reporta el tipo de instalación, la versión, la configuración del sistema y cualquier problema detectado.

Gestión de autenticación (v2.1.41+)

Administre la autenticación sin entrar al REPL:⁹⁷

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

Flujo de trabajo común para cambiar entre cuentas u organizaciones:

claude auth logout && claude auth login

Consulte también: ¿Cómo depuro problemas? para solucionar fallos de autenticación.

Actualizaciones

Claude Code se actualiza automáticamente de forma predeterminada, verificando al inicio y periódicamente durante las sesiones. Las actualizaciones se descargan en segundo plano y se aplican en el siguiente inicio.

Desactivar las actualizaciones automáticas:

export DISABLE_AUTOUPDATER=1

O en settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Actualización manual:

claude update

Desinstalación

Instalación nativa (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Instalación nativa (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Limpiar configuración (elimina todas las configuraciones):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Inicio rápido: Su primera sesión

1. Instale e inicie:

claude                           # Launch in current directory

2. Navegue a un proyecto:

cd ~/my-project && claude        # Or launch from any git repo

3. Pida a Claude que haga algo:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Use atajos de teclado durante su sesión:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Continúe más tarde:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Consejo avanzado: Cree un archivo CLAUDE.md en la raíz de su proyecto con comandos de compilación, convenciones de código y notas de arquitectura. Claude lo lee en cada sesión — es la acción individual con mayor impacto que puede realizar para mejorar la calidad.

Modos principales de interacción

REPL interactivo

Inicie Claude Code sin argumentos para entrar al bucle interactivo de lectura-evaluación-impresión (REPL):

cd your-project
claude

El REPL mantiene el contexto de la conversación entre turnos. Escriba consultas directamente, reciba respuestas y continúe hasta salir con /exit o Ctrl+D.

Comience con un prompt inicial para enfocar la sesión:

claude "explain the authentication flow in this project"

Consejo avanzado: El REPL persiste el estado a través de eventos de compactación. Cuando el contexto crece demasiado, Claude resume automáticamente la conversación antigua preservando las decisiones clave y los fragmentos de código. Puede activar esto manualmente con /compact o agregar instrucciones personalizadas sobre qué preservar.

Modo no interactivo

El modo de impresión (-p) ejecuta una sola consulta y termina:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Para salida estructurada adecuada para análisis en scripts:

claude -p "count lines by file type" --output-format json

La salida JSON incluye todo lo que necesita para automatización:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Para procesamiento en tiempo real de salida en streaming:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Opciones de formato de salida:

Códigos de salida:

Control del comportamiento autónomo en modo -p:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

Patrón de integración CI/CD:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Gestión de sesiones

Las sesiones persisten el historial de conversación para continuarlas posteriormente. La persistencia de sesiones es esencial para trabajo complejo que abarca múltiples sesiones:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Sesiones vinculadas a PR (v2.1.27+): Inicie una sesión vinculada a un pull request específico:⁸¹

claude --from-pr 123                                    # By PR number
claude --from-pr https://github.com/org/repo/pull/123   # By URL

Las sesiones también se vinculan automáticamente a PRs cuando los crea mediante gh pr create durante una sesión. Esto facilita retomar el trabajo en un PR específico más adelante.

Sesiones con nombre (dic. 2025): Nombre y gestione sesiones para recuperarlas fácilmente:

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Nota: --session-id requiere un UUID válido (por ejemplo, 550e8400-e29b-41d4-a716-446655440000). Para nombres de sesión legibles, use /rename y --resume en su lugar.

Claude Code almacena las sesiones como transcripciones JSONL. La ejecución de agentes asigna valores únicos de agentId con transcripciones almacenadas como agent-{agentId}.jsonl. Reanudar preserva el contexto completo de conversaciones anteriores.

Modo de planificación

El modo de planificación restringe a Claude a exploración de solo lectura — sin edición de archivos, sin ejecución de Bash, sin acciones destructivas. Claude diseña un enfoque de implementación, lo escribe en un archivo de plan y espera su aprobación antes de ejecutar cualquier cosa.

Cómo entrar al modo de planificación:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

Cómo funciona:

1. Claude entra en modo de planificación (automáticamente para tareas complejas, o mediante Shift+Tab)
2. Explora el código fuente usando herramientas de solo lectura: Read, Glob, Grep, WebSearch, WebFetch
3. Escribe un plan en .claude/plans/{session-slug}.md
4. Sale del modo de planificación con ExitPlanMode, presentando el plan para su revisión
5. Usted aprueba, solicita cambios o rechaza

Herramientas disponibles en modo de planificación: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. Las herramientas de edición (Edit, Write, Bash, NotebookEdit) están bloqueadas.

Después de aprobar el plan (v2.1.32+): Claude ofrece tres opciones: - “Sí, limpiar contexto y auto-aceptar ediciones” (Shift+Tab) — comienza de cero con contexto completo para el plan - “Sí, y aprobar ediciones manualmente” — preserva el contexto, usted aprueba cada cambio - “Sí, auto-aceptar ediciones” — preserva el contexto, Claude ejecuta sin aprobación por cada edición

Limpiar el contexto al aprobar es el flujo de trabajo recomendado. Le da al plan una ventana de contexto nueva, lo que mejora significativamente la adherencia al plan — Claude se mantiene enfocado por más tiempo sin que la conversación anterior interfiera.

Cuándo usar el modo de planificación: - Implementaciones de nuevas funciones con decisiones arquitectónicas - Refactorizaciones de múltiples archivos donde desea revisar el enfoque primero - Bases de código desconocidas donde la exploración debe preceder a la modificación - Cualquier tarea donde existan múltiples enfoques válidos y desee aportes

Consejo avanzado: Cuanto más tiempo dedique al modo de planificación, más probable es que Claude tenga éxito en la implementación. El modo de planificación es esencialmente exploración gratuita — sin llamadas a herramientas riesgosas, sin ediciones desperdiciadas. Úselo ampliamente.

Inmersión en el Sistema de Configuración

Claude Code utiliza un sistema de configuración por capas. Comprender la jerarquía es esencial porque los niveles superiores anulan a los inferiores, y la configuración empresarial no puede ser eludida en absoluto.

Jerarquía de Configuración

Consejo avanzado: Use .claude/settings.local.json para preferencias personales en proyectos compartidos (agréguelo a .gitignore). Use .claude/settings.json para configuración de todo el equipo que se registra en el control de versiones.

Referencia Completa de settings.json

Una configuración completa que demuestra todas las opciones principales:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  }
}

Referencia de Variables de Entorno

Autenticación y API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Configuración de modelo:

ANTHROPIC_MODEL=claude-opus-4-6                 # Override default model
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6    # Opus 4.6 (Feb 2026)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # Enable extended thinking
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Configuración de proveedor en la nube:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

Control de comportamiento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic updates
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls

Configuración de herramientas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Red y proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

Interfaz y terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]

Identidad del llamante SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=[email protected]        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Depuración:

ANTHROPIC_LOG=debug                             # Enable API request logging

¿Qué modelo debería elegir?

Elegir el modelo adecuado para cada tarea impacta significativamente tanto en el costo como en la calidad. Claude Code ofrece cambio flexible de modelos en múltiples niveles.

Modelos disponibles

Opus 4.6 (5 de febrero de 2026): El modelo insignia más reciente con ventana de contexto de 1M de tokens (beta), salida máxima de 128K, pensamiento adaptativo y equipos de agentes.⁸⁶ Mismo precio que Opus 4.5 ($5/$25 por MTok). El contexto extenso (>200K de entrada) cuesta $10/$37.50 por MTok. ID del modelo: claude-opus-4-6.¹

Sonnet 4.6 (17 de febrero de 2026): El nuevo modelo equilibrado que reemplaza a Sonnet 4.5 como predeterminado en claude.ai y Claude Cowork.¹⁰⁰ Mismo precio que Sonnet 4.5 ($3/$15 por MTok). Rendimiento mejorado en búsqueda agéntica mientras consume menos tokens. Soporta pensamiento extendido, pensamiento adaptativo y una ventana de contexto de 1M de tokens (beta). Salida máxima de 64K. Fecha de corte de conocimiento: agosto de 2025 (confiable), enero de 2026 (datos de entrenamiento). ID del modelo: claude-sonnet-4-6. Sonnet 4.5 es ahora un modelo heredado.¹⁰⁰

Por qué importan estas diferencias de precio: Una sesión típica de codificación consume entre 50K y 200K tokens de entrada y entre 10K y 50K tokens de salida. Con Haiku, eso equivale a $0.10-$0.45 por sesión. Con Opus, la misma sesión cuesta $0.50-$2.25, 5 veces más. Reserve Opus para problemas genuinamente difíciles.¹

Cuándo usar cada modelo

Haiku: Úselo para subagents que realizan exploración, búsquedas simples de archivos y preguntas rápidas. Es aproximadamente 5 veces más económico que Opus y responde más rápido. Perfecto para tareas en segundo plano donde no necesita razonamiento profundo.

Sonnet: El caballo de batalla para el desarrollo diario. Maneja bien la mayoría de las tareas de codificación: implementar funciones, corregir errores, escribir pruebas y revisión de código. Úselo como su opción predeterminada. Sonnet 4.6 (febrero de 2026) ofrece búsqueda agéntica mejorada y mejor eficiencia de tokens en comparación con Sonnet 4.5, con soporte para pensamiento adaptativo y la ventana de contexto de 1M en beta.¹⁰⁰

Opus: Resérvelo para razonamiento genuinamente complejo: decisiones arquitectónicas, depuración difícil, comprensión de sistemas complejos y análisis de seguridad. Opus 4.6 (febrero de 2026) representa un avance significativo: planifica con más cuidado, mantiene tareas agénticas por más tiempo, opera de manera más confiable en bases de código grandes y detecta mejor sus propios errores durante la revisión de código.⁸⁶ Cuenta con una ventana de contexto de 1M de tokens en beta e introduce pensamiento adaptativo que determina automáticamente la profundidad del razonamiento. Según Anthropic, en Terminal-Bench 2.0, Opus 4.6 alcanza la puntuación más alta de la industria en codificación agéntica. En GDPval-AA (trabajo de conocimiento económicamente valioso), Anthropic reporta que supera a GPT-5.2 por ~144 puntos Elo.⁸⁶ Nota: Los usuarios con suscripción Pro tienen acceso a Opus como parte de su suscripción.²⁰

Opusplan: Un modo híbrido que utiliza Opus para la planificación (donde la calidad del razonamiento importa más) y Sonnet para la ejecución (donde la velocidad importa). Excelente para refactorizaciones complejas donde desea el mejor plan pero no necesita razonamiento de nivel Opus para cada edición individual.

Cambio de modelos

Durante la sesión:

> /model opus
> /model sonnet
> /model haiku

Al iniciar:

claude --model opus

Mediante variable de entorno:

export ANTHROPIC_MODEL=opus

En settings.json:

{
  "model": "claude-sonnet-4-5-20250929"
}

Para subagents específicamente:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Contexto extendido

Para bases de código grandes o sesiones largas, active el contexto de 1M de tokens:

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.6 with 1M context (beta)

O dentro de una sesión:

> /model sonnet[1m]
> /model opus[1m]

Opus 4.6 es el primer modelo de clase Opus con soporte nativo de contexto de 1M. Alcanza un 76% de precisión en la variante de 8 agujas de 1M de MRCR v2 (los competidores obtienen ~18.5%), lo que lo convierte en el modelo más potente para recuperación en contexto extenso.⁸⁶

El contexto extendido cuesta más por token (2x en entrada, 1.5x en salida cuando la entrada supera los 200K tokens). Úselo cuando realmente lo necesite, no como configuración predeterminada.

Verificar el modelo actual

> /status

Este comando muestra el modelo actual, información de la cuenta, configuración aplicada y otros estados de la sesión.

Etiquetas del selector de modelos (v2.1.51+): El selector /model ahora muestra etiquetas legibles (por ejemplo, “Sonnet 4.6”) en lugar de IDs de modelo sin procesar para versiones fijadas, con indicaciones de actualización cuando hay versiones más recientes disponibles.¹⁰⁵

Modo rápido (v2.1.36+)

El modo rápido proporciona una salida significativamente más veloz del mismo modelo; no cambia a un modelo más económico. Actívelo durante una sesión con /fast.⁹³

> /fast            # Toggle fast mode on/off

Precios (modo rápido de Opus 4.6):

El precio del modo rápido se aplica en toda la ventana de contexto, incluyendo solicitudes con más de 200K tokens de entrada — no hay recargo adicional por contexto extenso en modo rápido.¹ El precio del modo rápido se acumula con los multiplicadores de caché de prompts y residencia de datos, pero NO con el precio de contexto extenso. El modo rápido no está disponible con la API por lotes.

Cuándo usar el modo rápido: - Iterando rápidamente en cambios pequeños donde la latencia es el cuello de botella - Generando pruebas, código repetitivo o código estándar donde la velocidad importa más que el costo - Trabajando a través de una lista de tareas similares secuencialmente

Cuándo NO usar el modo rápido: - Tareas agénticas de larga duración (el costo se acumula rápidamente a tarifas 6x) - Trabajo de subagents en segundo plano (nadie está esperando la salida) - Sesiones con presupuesto limitado

El modo rápido de Opus 4.6 ahora incluye la ventana completa de contexto de 1M (v2.1.50+). Anteriormente, el modo rápido estaba limitado al contexto estándar; ahora obtiene la misma capacidad de 1M de tokens a velocidades de modo rápido.¹⁰³

Consejo avanzado: El modo rápido combina bien con el híbrido opusplan: use el modo rápido durante la fase de ejecución de Sonnet para iteración rápida mientras mantiene las tarifas estándar para la planificación con Opus. Tenga en cuenta que /fast requiere que /extra-usage esté activado primero (corrección en v2.1.37).⁹³

¿Cuánto cuesta Claude Code?

Comprender y controlar los costos es esencial para un uso sostenible de Claude Code. Consulte también Selección de modelo para conocer las capacidades de cada modelo y Marcos de decisión para elegir el modelo adecuado según la tarea.

Consultar costos

> /cost

Resultado:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Planes de suscripción

Límites de uso (agosto 2025): Anthropic introdujo límites de uso semanales para suscriptores de pago. Los suscriptores Max pueden adquirir uso adicional más allá del límite a las tarifas estándar de API.²¹

Precios de tokens de API (febrero 2026)¹⁸⁶

Para usuarios facturados por API, precio por millón de tokens:

Precios de contexto largo (>200K tokens de entrada):

El umbral de 200K se basa en el total de tokens de entrada (incluyendo lecturas/escrituras de caché). Cuando se excede, Anthropic factura todos los tokens a la tarifa de contexto largo.¹

Precios con residencia de datos: Especificar inferencia exclusiva en EE. UU. mediante inference_geo añade un multiplicador de 1,1× en todos los precios de tokens (solo modelos Opus 4.6+).¹

Prompt caching reduce significativamente los costos de entrada repetida: las escrituras en caché cuestan 1,25× la tarifa base (caché de 5 min) o 2× (caché de 1 hora), pero las lecturas de caché cuestan solo 0,1×, un ahorro del 90%. Para sistemas RAG y asistentes de código con contexto repetido, el almacenamiento en caché puede reducir costos entre un 88-95%.

Batch API ofrece descuentos del 50% con entrega en 24 horas para tareas no urgentes como suites de pruebas nocturnas.

Política de múltiples cuentas⁵⁹

¿Se pueden tener múltiples cuentas de Claude? Sí, para casos de uso legítimos. Anthropic permite explícitamente múltiples cuentas cuando sirven para propósitos distintos.

Qué está permitido:

Límites técnicos: - Hasta 3 cuentas pueden verificarse con el mismo número de teléfono - Múltiples suscripciones de pago desde la misma IP/red están explícitamente soportadas - Las cuentas son completamente independientes; no hay transferencia de chats o proyectos entre ellas

Qué está prohibido (según la Política de uso): - Crear cuentas para evadir suspensiones después de haber sido suspendido - Coordinar actividad maliciosa entre cuentas para evitar la detección - Usar múltiples cuentas para eludir límites de uso o créditos del nivel gratuito

Nota del mundo real: En enero de 2026, el usuario avanzado Jeffrey Emanuel (@doodlestein) tuvo 22 cuentas Max marcadas automáticamente y suspendidas temporalmente. El empleado de Anthropic Thariq (@trq212) resolvió la situación en 4 horas tras confirmar el uso legítimo. Si usted utiliza Claude Code extensivamente tanto para trabajo como para proyectos personales en múltiples cuentas, ese es exactamente el uso para el que está diseñado el servicio, pero no intente manipular el sistema.

En caso de duda: Contacte al Soporte de Anthropic para confirmar su configuración específica por escrito.

Factores de costo

Ejemplos de costos reales

Consejo para ahorrar costos: Usar Haiku para subagents de exploración y Sonnet para implementación típicamente reduce los costos entre un 40-50% en comparación con usar Sonnet para todo.

Gestión de costos en equipo

TPM/RPM recomendados por tamaño de equipo:

Tarifas ocultas de herramientas

Más allá del precio por token, algunas herramientas generan cargos adicionales:¹⁶

Estos costos se acumulan en bucles de agentes. Un ciclo de depuración de 100 iteraciones con Bash genera aproximadamente 24.500 tokens de entrada adicionales solo en sobrecarga.

Estrategias para reducir costos

1. Use Haiku para subagents: La mayoría de las exploraciones no necesitan Sonnet
2. Habilite prompt caching: Está activo por defecto, pero verifique que no esté deshabilitado
3. Establezca un máximo de turnos: claude --max-turns 5 evita conversaciones descontroladas
4. Use el modo plan para exploración: Sin ejecución = sin operaciones costosas accidentales
5. Compacte proactivamente: Menos contexto = menos tokens
6. Limite la salida: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Batch API para trabajo no urgente: 50% de descuento tanto en tokens de entrada como de salida

Monitoreo de uso

• Consola de Claude: platform.claude.com (requiere rol de Admin o Billing)
• Límites de workspace: Configure límites de gasto por workspace
• Bedrock/Vertex: Use el monitoreo de costos nativo de la nube
• LiteLLM: Para seguimiento detallado por usuario con proveedores externos

Uso de tokens en segundo plano

Algunas operaciones consumen tokens en segundo plano: - Resumen de conversaciones para /resume - Comandos /cost y /status - Auto-compactación

Normalmente menos de $0,04 por sesión.

Claude Code Analytics API (Team/Enterprise)⁵³

Acceda programáticamente a las analíticas de uso y métricas de productividad de Claude Code de su organización a través del Admin API.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Clave de Admin API (sk-ant-admin...) - Plan Team o Enterprise - Rol de Admin, Billing o Developer

Métricas disponibles:

Solicitud de ejemplo:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Casos de uso: - Análisis de productividad de desarrolladores (sesiones, commits, PRs) - Métricas de uso de herramientas (tasas de aceptación/rechazo para Edit, Write, etc.) - Seguimiento y asignación de costos entre equipos - Justificación de ROI para herramientas de codificación con IA

Nota: Los datos aparecen dentro de 1 hora de completada la actividad. Solo se incluyen en las respuestas los datos con más de 1 hora de antigüedad para mantener la consistencia.

Marcos de Decisión

Conocer las funciones no es suficiente. Necesita saber cuándo usar cada una. Estos árboles de decisión transforman el conocimiento en acción.

¿Qué modelo debería usar?

INICIO → ¿Es una tarea simple? (búsqueda de archivos, pregunta rápida, formato)
         │
         ├── SÍ → Use Haiku
         │         Costo: ~$0,03/tarea
         │         Velocidad: La más rápida
         │
         └── NO → ¿Requiere razonamiento profundo?
                  (arquitectura, depuración compleja, análisis de seguridad)
                  │
                  ├── SÍ → Use Opus 4.6
                  │         Costo: ~$2,00/tarea
                  │         Calidad: La más alta (contexto de 1M, pensamiento adaptativo)
                  │
                  └── NO → Use Sonnet (predeterminado)
                           Costo: ~$0,75/tarea
                           Equilibrio: El mejor en general

Regla general: Comience con Sonnet. Baje a Haiku para subagents. Escale a Opus 4.6 solo cuando la respuesta de Sonnet se sienta superficial. Con equipos de agentes (v2.1.32+), Opus puede coordinar múltiples agentes trabajando en paralelo en diferentes subtareas.⁸⁶

¿Comando, Skill, Subagent o equipo de agentes?

¿Desea control explícito sobre cuándo se ejecuta?
│
├── SÍ → Use Slash Command
│         Ejemplo: /deploy, /test, /security-review
│         Usted lo invoca. Usted controla el momento.
│
└── NO → ¿Debería aplicarse la experiencia automáticamente según el contexto?
         │
         ├── SÍ → Use Skill
         │         Ejemplo: Patrones de seguridad, reglas de dominio, estándares de código
         │         Claude reconoce el contexto y aplica la experiencia.
         │
         └── NO → ¿El trabajo necesita contexto aislado?
                  │
                  ├── SÍ → ¿Es una subtarea o muchas subtareas en paralelo?
                  │         │
                  │         ├── UNA → Use Subagent (herramienta Task)
                  │         │         Ejemplo: Exploración profunda, análisis en paralelo
                  │         │         Evita la saturación de contexto en la conversación principal.
                  │         │
                  │         └── MUCHAS → Use equipo de agentes (v2.1.32+)
                  │                   Ejemplo: 5 agentes revisando diferentes módulos simultáneamente
                  │                   Opus coordina; cada agente trabaja de forma independiente.
                  │
                  └── NO → Simplemente escriba el prompt directamente
                           No todo necesita abstracción.

¿Hook o Prompt?

¿La acción SIEMPRE debe ocurrir, independientemente del juicio de Claude?
│
├── SÍ → Use Hook (determinístico)
│         Ejemplos:
│         - Formatear código después de cada edición
│         - Registrar todos los comandos bash
│         - Bloquear acceso a archivos .env
│         Claude no puede omitirlo, olvidarlo ni decidir lo contrario.
│
└── NO → Use Prompt (probabilístico)
         Ejemplos:
         - "Considere agregar pruebas"
         - "Piense en los casos límite"
         - "Revise la seguridad si es relevante"
         Claude decide según el contexto.

¿Cuándo usar Extended Thinking?

¿Es un problema genuinamente difícil?
│
├── Decisión arquitectónica con muchas compensaciones → SÍ, use thinking
├── Depuración compleja con causa raíz poco clara → SÍ, use thinking
├── Análisis de seguridad que requiere razonamiento cuidadoso → SÍ, use thinking
├── Comprender un código base desconocido → SÍ, use thinking
│
├── Corrección de errores rutinaria → NO, omita thinking
├── Refactorización simple → NO, omita thinking
├── Formato de código → NO, omita thinking
└── Preguntas rápidas → NO, omita thinking

Alterne con Alt+T durante la sesión. Los presupuestos de pensamiento más altos cuestan más; comience con el mínimo y aumente solo si las respuestas se sienten apresuradas.

Pensamiento adaptativo de Opus 4.6: Opus 4.6 ajusta automáticamente la profundidad de pensamiento según la complejidad del problema. Para la mayoría de las tareas, no es necesario el control explícito del presupuesto de pensamiento — Opus escala para problemas difíciles y se mantiene rápido para los simples. El ajuste manual de thinking es más útil con Sonnet cuando desea forzar un análisis más profundo.

¿Qué superficie de ejecución?

¿Dónde debería realizarse este trabajo?
│
├── Requiere SUS archivos y herramientas locales
│   │
│   ├── Trabajo interactivo e iterativo → Sesión principal REPL
│   ├── Tarea única con script → claude -p "prompt" (modo print)
│   ├── Automatización CI/CD → claude -p --json (no interactivo + salida estructurada)
│   └── Tareas paralelas aisladas → Subagents mediante herramienta Task
│
├── Requiere el entorno de OTRA PERSONA
│   │
│   └── Código base o servidor remoto → Agente en segundo plano (nube)
│
└── No requiere ningún entorno
    │
    ├── Investigación o análisis → Subagent con tipo Explore
    └── Extracción de contenido web → Herramientas WebFetch / WebSearch

Equipos de agentes vs Subagents vs Sesiones paralelas

¿Necesita múltiples agentes trabajando en subtareas relacionadas?
│
├── SÍ → ¿Las subtareas son independientes (sin estado compartido)?
│         │
│         ├── SÍ → ¿Pueden compartir el mismo código base?
│         │         │
│         │         ├── SÍ → Use equipo de agentes (v2.1.32+)
│         │         │         Opus coordina. Los agentes comparten acceso al repositorio.
│         │         │         Ejemplo: "Revisar auth, API y módulos DB en paralelo"
│         │         │
│         │         └── NO → Use sesiones paralelas (terminales separadas)
│         │                  Cada una tiene su propio directorio de trabajo.
│         │                  Ejemplo: "Corregir repo-A y repo-B simultáneamente"
│         │
│         └── NO → Use subagents secuenciales
│                  Los resultados de uno alimentan al siguiente.
│                  Ejemplo: "Explorar → Planificar → Implementar"
│
└── NO → Use un solo subagent o REPL principal

¿Qué tipo de Hook?

¿Qué tipo de automatización necesita?
│
├── ¿Ejecutar un comando de shell en un evento específico?
│   │
│   └── Use Command Hook
│       Disparador: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Ejemplo: "Ejecutar prettier después de cada edición de archivo"
│       Configuración: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── ¿Modificar el prompt del sistema de Claude según el contexto?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Disparador: Los mismos eventos
│       Ejemplo: "Inyectar reglas del proyecto al trabajar en /src/auth/"
│       Configuración: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── ¿Hacer que Claude tome una decisión antes de continuar?
    │
    └── Use Agent Hook (v2.1.35+)
        Disparador: Los mismos eventos
        Ejemplo: "Evaluar si este comando bash es seguro antes de ejecutarlo"
        Configuración: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

¿Cuándo usar /fast?

¿La velocidad de respuesta es más importante que la profundidad en este momento?
│
├── SÍ → Use /fast
│         El mismo modelo Opus 4.6, salida más rápida
│         Bueno para: preguntas rápidas, ediciones simples, explicaciones de código,
│                     búsqueda de archivos, tareas de formato
│
└── NO → Permanezca en modo normal
         Bueno para: decisiones de arquitectura, depuración compleja,
                     revisiones de seguridad, refactorizaciones de múltiples archivos,
                     cualquier cosa que requiera razonamiento profundo

/fast activa el modo rápido para la sesión actual. Utiliza el mismo modelo (Opus 4.6) con velocidad de salida optimizada — NO cambia a un modelo más económico.

¿Cómo funciona el sistema de permisos?

El sistema de permisos de Claude Code proporciona control detallado sobre qué operaciones pueden ejecutarse. Comprenderlo es esencial tanto para la seguridad como para la eficiencia del flujo de trabajo. Consulte también Implementación empresarial para configuraciones administradas que aplican permisos a nivel organizacional.

Niveles de permisos

Herramientas de solo lectura (aprobadas automáticamente): - Read - Leer contenido de archivos - Glob - Buscar archivos por patrón - Grep - Buscar contenido en archivos - WebSearch - Buscar en la web - LSP - Inteligencia de código (ir a definición, buscar referencias, documentación al pasar el cursor)²⁵

Capacidades de la herramienta LSP (v2.0.74+): La herramienta LSP proporciona inteligencia de código similar a un IDE: - Ir a definición: Saltar al lugar donde se define un símbolo - Buscar referencias: Listar todos los usos de un símbolo en todo el código fuente - Documentación al pasar el cursor: Obtener información de tipos y documentación para cualquier símbolo - Funciona con TypeScript, Python, Go, Rust y otros lenguajes con soporte LSP - Requiere que el servidor de lenguaje esté disponible (normalmente se instala con su cadena de herramientas)

Herramientas de modificación (requieren aprobación): - Edit - Modificar archivos existentes - Write - Crear archivos nuevos - Bash - Ejecutar comandos de shell - WebFetch - Obtener contenido de URLs - NotebookEdit - Modificar notebooks de Jupyter

La primera vez que se ejecuta una herramienta de modificación, Claude Code solicita aprobación. Las aprobaciones persisten durante la sesión a menos que se configure explícitamente de otra manera.

Modos de permisos

Modo YOLO (v2.0.68+): Para operación completamente autónoma, utilice el flag --dangerously-skip-permissions. Este flag acepta todo: ediciones de archivos, comandos bash, todas las llamadas a herramientas. La palabra “dangerous” es intencional. Úselo en entornos aislados o cuando confíe plenamente en el código fuente.⁶¹

claude --dangerously-skip-permissions

Establecer el modo vía CLI:

claude --permission-mode acceptEdits

Alternar durante la sesión:

Shift+Tab  # Cycles through modes

En settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Sintaxis de reglas de permisos

Las reglas detalladas controlan operaciones específicas. Las reglas se evalúan en orden: la primera coincidencia gana.

Patrones de comandos Bash:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

El asterisco proporciona coincidencia por prefijo: Bash(npm run test:*) permite npm run test, npm run test:unit y npm run test:integration.

Limitación importante: Los patrones de Bash solo coinciden por prefijo, no por expresiones regulares. Un patrón como Bash(curl http:*) no coincidirá con curl -X GET http://... porque las opciones aparecen antes de la URL. Para un bloqueo confiable, deniegue el comando completamente: Bash(curl:*).

Patrones de operaciones de archivos:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Sintaxis de rutas: - Rutas relativas: Edit(src/**) - relativa al directorio de trabajo - Absolutas desde el archivo de configuración: Edit(/build/**) - relativa a la ubicación del archivo de configuración - Absolutas verdaderas: Edit(//tmp/**) - comienza con // - Directorio de inicio: Read(~/.zshrc)

Patrones de herramientas MCP:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Utilice la sintaxis de comodín mcp__server__* para permitir o denegar todas las herramientas de un servidor MCP específico.³⁹ La sintaxis de comodín es útil para habilitar rápidamente todas las herramientas de servidores confiables o bloquear servidores completos de fuentes no confiables.

Patrones de WebFetch:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Directorios adicionales

Extienda el acceso de Claude más allá del proyecto actual:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Los directorios adicionales son esenciales para monorepos o cuando Claude necesita hacer referencia a código en directorios hermanos.

Modo sandbox

Habilite el aislamiento de sistema de archivos y red:

> /sandbox

O configúrelo en la configuración:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true
    }
  }
}

Cuando está en modo sandbox: - El acceso al sistema de archivos se restringe al directorio del proyecto - El acceso a la red está controlado - Ciertos comandos se excluyen de las restricciones del sandbox - Los comandos Bash se aprueban automáticamente si autoAllowBashIfSandboxed es verdadero

Consejo avanzado: El modo sandbox es excelente para ejecutar Claude en bases de código no confiables. Habilítelo al explorar proyectos desconocidos o cuando desee una capa adicional de protección. Las pruebas internas de Anthropic encontraron que el sandboxing reduce las solicitudes de permisos en un 84%.⁴⁵ El sandbox utiliza primitivas a nivel de sistema operativo (seatbelt de macOS, bubblewrap de Linux) para el aislamiento del sistema de archivos y la red, de modo que incluso una inyección de prompt exitosa queda completamente contenida. Anthropic ha publicado como código abierto el runtime del sandbox para equipos que construyen sus propios agentes.⁸⁹

Notas de seguridad (v2.1.34+): Los comandos excluidos del sandboxing mediante sandbox.excludedCommands o dangerouslyDisableSandbox anteriormente podían eludir la regla de permiso de solicitud de Bash cuando autoAllowBashIfSandboxed estaba habilitado; esto se corrigió en v2.1.34.⁹⁴ A partir de v2.1.38, las escrituras en .claude/skills están bloqueadas en modo sandbox, evitando que la inyección de prompts modifique las definiciones de skills.⁹⁵

¿Cómo funcionan los hooks?

Los hooks ejecutan comandos de shell determinísticos en puntos específicos del flujo de trabajo de Claude Code. A diferencia de indicarle a Claude que realice acciones mediante prompts, los hooks garantizan la ejecución independientemente del comportamiento del modelo. Son esenciales para aplicar estándares de equipo y automatizar tareas repetitivas. Consulte Marcos de decisión para el árbol de decisión “¿Qué tipo de hook?” que cubre hooks de comando, de prompt y de agente.

Por qué hooks en lugar de prompts: Decirle a Claude “siempre ejecuta Prettier después de editar archivos” funciona a veces. Pero Claude podría olvidarlo, priorizar la velocidad o decidir que el cambio es “demasiado pequeño.” Los hooks garantizan la ejecución: cada Edit o Write activa su formateador, cada vez, sin excepciones. Para cumplimiento, seguridad y estándares de equipo, lo determinístico supera a lo probabilístico.⁷

Eventos disponibles

Configuración de hooks

Defina los hooks en settings.json o en un archivo hooks.json dedicado:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

El campo matcher determina qué herramientas activan un hook:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Protocolo de entrada/salida de hooks

Los hooks reciben JSON en stdin:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Hooks de Stop/SubagentStop (v2.1.47+) reciben un campo adicional last_assistant_message que contiene el texto de la respuesta final de Claude, para que los hooks puedan inspeccionar la salida sin analizar archivos de transcripción:

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

Los códigos de salida controlan el comportamiento: - 0: Éxito: la operación continúa. La salida estándar se muestra en modo detallado (Ctrl+O). Para UserPromptSubmit y SessionStart, la salida estándar se agrega al contexto. - 2: Error bloqueante: la operación se detiene. La salida de error se convierte en el mensaje de error que se envía a Claude. - 1, 3, etc.: Error no bloqueante: la operación continúa. La salida de error se muestra como advertencia en modo detallado.

Para control avanzado, los hooks pueden generar JSON:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

Control de decisión en PreToolUse (formato preferido): Los hooks de PreToolUse usan hookSpecificOutput para un control más completo: tres resultados posibles (allow/deny/ask) además de la capacidad de modificar la entrada de la herramienta e inyectar contexto:⁹⁶

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Nota: Los campos de nivel superior decision y reason están obsoletos para PreToolUse. Use hookSpecificOutput.permissionDecision y hookSpecificOutput.permissionDecisionReason en su lugar. Otros eventos (PostToolUse, Stop, etc.) aún usan decision de nivel superior.⁹⁶

Hooks asíncronos (enero de 2026)

Los hooks ahora pueden ejecutarse en segundo plano sin bloquear la ejecución de Claude Code. Agregue async: true a la configuración de su hook:⁸⁸

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Cuándo usar hooks asíncronos: - Notificaciones (Slack, correo electrónico, Pushover) que no deberían ralentizar la sesión - Registro y telemetría que pueden ejecutarse en segundo plano - Post-procesamiento no crítico (analíticas, respaldos)

Cuándo NO usar hooks asíncronos: - Formateo (debe completarse antes de la siguiente edición) - Validación (debe bloquear en caso de fallo) - Cualquier hook que necesite modificar la entrada/salida de la herramienta

Hooks basados en prompts y en agentes (v2.1.32+)

Más allá de los hooks de comandos de shell (type: "command"), Claude Code soporta dos tipos de hooks potenciados por LLM que evalúan condiciones usando razonamiento de IA en lugar de scripts.⁹⁶

Hooks de prompt (type: "prompt") envían un prompt de un solo turno a un modelo rápido de Claude. El modelo devuelve { "ok": true } para permitir o { "ok": false, "reason": "..." } para bloquear:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hooks HTTP (type: "http") envían la entrada JSON del evento como una solicitud POST a una URL y reciben JSON de vuelta. Úselos para webhooks, servicios de notificación externos o validación basada en API (v2.1.63+):¹¹¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Los hooks HTTP usan el mismo formato de decisión que los hooks de comando (devuelven JSON con decision y reason). Se enrutan a través del proxy de red del sandbox cuando el sandboxing está habilitado. No soportados para eventos SessionStart/Setup.

Hooks de agente (type: "agent") generan un subagente con acceso a herramientas (Read, Grep, Glob) para verificación de múltiples turnos. Úselos cuando la verificación requiera inspeccionar archivos reales o resultados de pruebas:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Use $ARGUMENTS como marcador de posición para la entrada JSON del hook. Ambos tipos soportan los campos model (por defecto usa modelo rápido) y timeout. Eventos soportados: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle no soporta hooks de prompt/agente.

Variables de entorno de hooks

Los hooks tienen acceso a variables de entorno para resolver rutas:⁹⁶

Persistir variables de entorno desde SessionStart:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Seguridad de hooks HTTP (v2.1.51+): Los hooks HTTP que interpolan variables de entorno en encabezados ahora requieren una lista explícita de allowedEnvVars. Esto previene la exfiltración arbitraria de variables de entorno a través de valores de encabezados. Los hooks HTTP también se enrutan a través del proxy de red del sandbox cuando el sandboxing está habilitado, aplicando la lista de dominios permitidos. Los hooks HTTP no están soportados para eventos SessionStart/Setup.¹⁰⁵

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Confianza del espacio de trabajo en hooks (v2.1.51+): Los comandos de hooks statusLine y fileSuggestion ahora requieren la aceptación de confianza del espacio de trabajo antes de ejecutarse en modo interactivo, cerrando un vector de seguridad potencial.¹⁰⁵

Ejemplos prácticos de hooks

Auto-formatear archivos TypeScript después de editarlos:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Registrar todos los comandos de bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

Bloquear acceso a archivos sensibles:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

Ejecutar pruebas después de cambios en el código:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Sistema de notificaciones personalizado:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Inyectar contexto dinámico en los prompts:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Depuración de hooks

Habilite el modo de depuración para resolver problemas con los hooks:

claude --debug

El modo de depuración registra: - Tiempos de ejecución de hooks - Datos de entrada/salida - Mensajes de error y trazas de pila - Resultados de decisiones (allow/reject/ask)

Hooks con alcance de componente (v2.1.0+)

Los hooks pueden definirse directamente en Skills, subagentes y slash commands usando frontmatter. Estos hooks tienen alcance limitado al ciclo de vida del componente y solo se ejecutan cuando ese componente está activo.⁴¹

Skill con hooks integrados:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

Eventos soportados: PreToolUse, PostToolUse, Stop

La opción once (solo para skills y slash commands) asegura que el hook se ejecute solo una vez por sesión, lo cual es útil para tareas de limpieza o finalización.

Estrategia para sesiones de larga duración

Para sesiones nocturnas o desatendidas de Claude Code, configure hooks para mantener a Claude encaminado sin intervención manual. La idea clave: use hooks de linting y pruebas como barandillas que obliguen a Claude a corregir problemas antes de continuar.⁶⁴

El patrón “No te detengas hasta que las pruebas pasen”:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

Estrategia para sesiones nocturnas:

1. Verificación previa: Use un hook de Setup para verificar que el entorno está listo
2. Validación continua: Los hooks de PostToolUse ejecutan pruebas después de cada cambio
3. Control de finalización: Los hooks de Stop verifican todos los criterios de aceptación antes de que Claude declare “listo”
4. Notificación: Los hooks de Stop pueden notificarle mediante Slack/Pushover cuando Claude termine o se quede atascado

Combine con --dangerously-skip-permissions en un contenedor aislado para ejecuciones nocturnas completamente autónomas. Claude seguirá iterando hasta que las pruebas pasen o agote sus opciones.

¿Qué es MCP (Model Context Protocol)?

MCP extiende Claude Code con acceso a herramientas externas, bases de datos, APIs y servicios a través de un protocolo estandarizado. El ecosistema ha crecido exponencialmente: MCP ahora tiene 100 millones de descargas mensuales y más de 3.000 servidores indexados en MCP.so (enero de 2026), consolidando su posición como el estándar de la industria para conectar IA con herramientas y datos.³⁵⁴ Comprender MCP es esencial para integrar Claude en su cadena de herramientas existente.

Por qué MCP es importante para los desarrolladores: Sin MCP, Claude Code solo puede leer archivos y ejecutar comandos bash. Con MCP, Claude puede consultar su base de datos de producción, crear tickets en Jira, revisar PRs en GitHub, verificar errores en Sentry e interactuar con cualquier API que su equipo utilice, todo desde solicitudes en lenguaje natural. El protocolo estandariza cómo las herramientas de IA se conectan a servicios externos, evitando la dependencia de un proveedor específico. Consulte Marcos de decisión para orientación sobre cuándo usar MCP frente a otros mecanismos de extensión.

Soporte para MCP remoto (junio de 2025)

Claude Code ahora admite servidores MCP remotos con autenticación nativa OAuth.²⁸ Conéctese a herramientas y fuentes de datos sin gestionar servidores locales. Solo autentíquese una vez y Claude Code se encargará de la renovación automática de tokens.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

Conectores MCP de claude.ai (v2.1.46+)

Claude Code ahora puede usar conectores MCP configurados en su cuenta de claude.ai. Esto conecta la experiencia web con CLI: los servidores MCP que haya configurado a través de la interfaz de claude.ai están automáticamente disponibles en Claude Code sin necesidad de reconfigurarlos localmente.¹⁰²

Desactivar: Establezca ENABLE_CLAUDEAI_MCP_SERVERS=false en su entorno o en el bloque env de settings.json para evitar que los servidores MCP de claude.ai se carguen.¹¹¹

Búsqueda de herramientas MCP (v2.1.7+)

A medida que los servidores MCP crecieron en capacidad (algunos exponiendo más de 50 herramientas), las descripciones de herramientas comenzaron a consumir contexto excesivo. La búsqueda de herramientas MCP resuelve esto cargando dinámicamente las descripciones de herramientas solo cuando se necesitan, una forma de carga diferida para herramientas de IA.⁵⁴

Impacto en el rendimiento: Las pruebas comparativas internas muestran mejoras dramáticas en precisión: - Opus 4: 49% → 74% en evaluaciones MCP - Opus 4.5: 79,5% → 88,1% en evaluaciones MCP - Reducción de consumo de tokens: 85%

Cómo funciona: Cuando las descripciones de herramientas MCP exceden el 10% de la ventana de contexto (umbral predeterminado), Claude Code difiere la carga de las descripciones completas hasta que realmente se necesiten. Claude ve los nombres de las herramientas pero obtiene las descripciones bajo demanda.

Configuración:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

Valores: - true — Siempre habilitar la búsqueda de herramientas - false — Siempre deshabilitar (cargar todas las descripciones de herramientas por adelantado) - auto:N — Habilitar cuando las herramientas excedan el N% del contexto (0-100)

Consejo avanzado: Con la búsqueda de herramientas habilitada, puede conectarse a muchos más servidores MCP sin preocuparse por los límites de contexto. La reducción del 95% del contexto significa que los servidores que antes competían por contexto ahora coexisten sin problemas.

Asistente interactivo de configuración MCP

Ejecute claude mcp add sin argumentos para iniciar una interfaz paso a paso para agregar servidores MCP. El asistente le guía a través de la selección del tipo de transporte, autenticación y configuración.¹⁵

Tipos de transporte

HTTP (recomendado para servidores remotos):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (obsoleto pero funcional):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (servidores locales):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows requiere un envoltorio cmd para stdio:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Gestión de alcances

Los servidores MCP existen en tres alcances con precedencia clara (local anula proyecto, proyecto anula usuario):

Especifique el alcance durante la instalación:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Formato del archivo de configuración

El archivo .mcp.json define los servidores a nivel de proyecto:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

Las variables de entorno se expanden usando la sintaxis ${VAR} con valores predeterminados opcionales: ${VAR:-default}.

Comandos de gestión MCP

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

Autenticación OAuth

Para servidores que requieren OAuth:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Uso de recursos y prompts MCP

Referencia a recursos:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

Prompts MCP como comandos de barra:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Límites de salida

Claude Code limita la salida de MCP para prevenir el desbordamiento de contexto: - Umbral de advertencia: 10.000 tokens - Máximo predeterminado: 25.000 tokens

Aumente si es necesario:

export MAX_MCP_OUTPUT_TOKENS=50000

Servidores MCP populares

Patrones prácticos de MCP

Flujo de trabajo con GitHub:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Consultas a bases de datos:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Monitoreo de errores:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

Configuración MCP empresarial

Los administradores de sistemas pueden aplicar políticas MCP mediante managed-mcp.json:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Ubicación: - macOS: /Library/Application Support/ClaudeCode/managed-mcp.json - Linux: /etc/claude-code/managed-mcp.json - Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

La lista de denegación tiene precedencia absoluta. Los comandos deben coincidir exactamente, incluyendo el orden de los argumentos.

MCP Apps (enero de 2026)

Anthropic lanzó MCP Apps, una extensión del Model Context Protocol que permite interfaces de usuario interactivas para herramientas directamente dentro de la interfaz de Claude.⁷⁸ MCP Apps permite a los usuarios ver, editar e interactuar con contenido de servicios externos sin salir de Claude, incluyendo Asana, Box, Canva, Figma, Hex, monday.com y Slack. Cualquier servidor MCP puede proporcionar una interfaz interactiva que se renderiza dentro de Claude. Aunque MCP Apps actualmente aparece en la interfaz web de claude.ai, las extensiones subyacentes del protocolo MCP son relevantes para el ecosistema MCP de Claude Code a medida que los servidores adoptan las nuevas capacidades interactivas.

Plataforma API: herramienta de ejecución de código v2 (enero de 2026)

Anthropic lanzó la v2 de la herramienta de ejecución de código en beta pública, reemplazando el sandbox original exclusivo de Python con ejecución de comandos Bash y manipulación directa de archivos.⁷⁹ Cambios clave: - Ejecutar comandos Bash (no solo Python) en contenedores aislados - Escribir y ejecutar código en cualquier lenguaje - Llamadas programáticas a herramientas (también en beta pública): Claude puede llamar herramientas desde dentro de la ejecución de código, reduciendo la latencia y el consumo de tokens en flujos de trabajo con múltiples herramientas

La herramienta v2 afecta principalmente a los usuarios de API, pero señala la dirección para las capacidades de ejecución en la nube de Claude Code.

¿Qué son los subagents?

Los subagents son instancias especializadas de Claude que manejan tareas complejas de forma independiente. Son una de las funciones más poderosas de Claude Code y una de las menos comprendidas. Dominar los subagents amplía drásticamente lo que puede lograr. Consulte Marcos de decisión para obtener orientación sobre Agent Teams vs Subagents vs sesiones paralelas.

Por qué existen los subagents: La conversación principal de Claude Code tiene una única ventana de contexto. Todo lo que discute, cada archivo que Claude lee, cada salida de herramienta: todo eso consume contexto. En sesiones largas, el contexto se llena, Claude pierde el seguimiento de decisiones anteriores y el rendimiento se degrada. Los subagents resuelven esto aislando el trabajo: los resultados de exploración no inflan su conversación principal, solo el resumen retorna. Claude también puede ejecutar hasta 10 subagents en paralelo, habilitando trabajo concurrente que sería imposible de forma secuencial.²

Cómo funcionan los subagents

Cuando Claude encuentra una tarea que se beneficia de atención enfocada (exploración profunda, análisis de múltiples pasos, trabajo especializado), puede crear un subagent. El subagent:

1. Comienza con un contexto limpio (sin contaminación de la conversación principal)
2. Tiene acceso a herramientas específicas
3. Opera con un modelo específico (frecuentemente más económico/rápido)
4. Devuelve resultados a la conversación principal

La arquitectura previene el desbordamiento de contexto mientras habilita flujos de trabajo complejos.

Tipos de subagents integrados

Explore (rápido, solo lectura): - Modelo: Haiku (ultra-rápido) - Modo: Estrictamente solo lectura - Herramientas: Glob, Grep, Read y comandos bash seguros (ls, git status, git log, git diff, find, cat, head, tail) - Niveles de profundidad: Quick, Medium, Very thorough - Usar para: Exploración de código, búsqueda de archivos, comprensión de estructura

General-purpose: - Modelo: Sonnet - Modo: Lectura/escritura completa - Herramientas: Todas las herramientas disponibles - Usar para: Tareas complejas de investigación + modificación

Plan: - Modelo: Sonnet (u Opus con opusplan) - Modo: Solo lectura - Herramientas: Read, Glob, Grep, Bash - Usar para: Planificación de implementaciones complejas antes de la ejecución

Activación de subagents

Claude delega automáticamente a subagents según el tipo de tarea. También puede solicitarlos explícitamente:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

Consejo avanzado: Para tareas complejas, solicite explícitamente la delegación a subagents. “Use an explore agent to find…” previene la inflación de contexto en su conversación principal.

Creación de subagents personalizados

Defina subagents en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Campos de configuración:

Restricción de subagents generables (v2.1.33+, renombrado v2.1.63): El campo tools soporta la sintaxis Agent(agent_type) para limitar qué tipos de subagent puede generar un agente. Por ejemplo, tools: Read, Grep, Agent(Explore) permite al agente usar Read y Grep directamente pero solo delegar a subagents de tipo Explore. La restricción previene la sobre-delegación en agentes restringidos. Nota: En v2.1.63, la herramienta Task fue renombrada a Agent. Las referencias existentes a Task(...) en configuraciones y definiciones de agentes siguen funcionando como aliases retrocompatibles.¹¹³

Subagents definidos por CLI (v2.1.32+)

Defina subagents como JSON al iniciar para pruebas rápidas o automatización. Estos existen solo durante la sesión y no se guardan en disco:⁹⁶

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

El flag --agents acepta JSON con los mismos campos de frontmatter que los subagents basados en archivo: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills y memory.

Gestión de subagents

> /agents                    # Interactive management
> /agents create             # Create new subagent
> /agents edit               # Modify existing
> /agents delete             # Remove subagent
> /agents list               # View all

Listado por CLI (v2.1.50+): Liste todos los agentes configurados desde la línea de comandos sin iniciar una sesión interactiva:

claude agents                # Shows agents grouped by source (built-in, user, project, plugin)

Control remoto (v2.1.51+): El subcomando claude remote-control sirve su entorno local para builds externos, habilitando que todos los usuarios accedan a las capacidades del entorno local de forma remota:¹⁰⁵

claude remote-control        # Start serving local environment for external builds

Ejecución de agentes en segundo plano

Para tareas de larga duración:

> Run a thorough security review in the background

> /agents  # Check status of running agents

Recupere los resultados posteriormente con el ID del agente.

Patrones avanzados

Subagents encadenados:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Exploración paralela:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Agentes reanudables: Los agentes pueden reanudarse con su ID para continuar trabajo previo:

> Resume agent abc123 and continue the analysis

Subagents asíncronos (diciembre de 2025)

Los subagents asíncronos permiten multitarea y ejecución paralela para proyectos a gran escala:

> Run security review in the background while I continue frontend work
> /tasks                    # Check status of running agents

Los agentes asíncronos devuelven resultados a través del TaskOutputTool unificado, habilitando flujos de trabajo eficientes estilo pipeline.

Resiliencia ante denegación de permisos (v2.1.0+)

A partir de v2.1.0, los subagents continúan trabajando después de denegaciones de permisos en lugar de detenerse por completo. Cuando un subagent encuentra un muro de permisos, intenta enfoques alternativos automáticamente. El cambio hace que los flujos de trabajo autónomos sean más resilientes y reduce la necesidad de intervención humana.⁴⁷

Agent Teams (febrero de 2026, Research Preview)

Los Agent Teams coordinan múltiples instancias de Claude Code trabajando juntas. Una sesión actúa como el team lead, generando teammates que trabajan independientemente en sus propias ventanas de contexto, comunicándose directamente entre sí a través de un buzón compartido y una lista de tareas.⁸⁶⁹¹

A diferencia de los subagents (que se ejecutan dentro de una sola sesión y solo reportan al llamador), los teammates son sesiones independientes completas que pueden enviarse mensajes entre sí, cuestionar los hallazgos de los demás y autocoordinarse.

Habilitar:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

O mediante variable de entorno: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Arquitectura:

Modos de visualización:

Configure en settings: "teammateMode": "in-process" o "tmux". O por sesión: claude --teammate-mode in-process.

Controles principales: - Shift+Down: Ciclar entre teammates (modo in-process; vuelve al lead después del último teammate) - Shift+Tab: Habilitar delegate mode (restringe al lead solo a coordinación, sin cambios de código) - Ctrl+T: Alternar la lista de tareas compartida - Enter en teammate: Ver su sesión; Escape para interrumpir su turno

Cuándo usar agent teams vs subagents:

Mejores casos de uso: - Investigación y revisión (múltiples perspectivas simultáneamente) - Nuevos módulos/funciones (cada teammate es responsable de piezas separadas) - Depuración con hipótesis competidoras (probar diferentes teorías en paralelo) - Coordinación entre capas (frontend, backend, tests cada uno a cargo de un teammate diferente)

Aprobación de plan para teammates: Para tareas complejas o riesgosas, requiera que los teammates planifiquen antes de implementar. El teammate trabaja en modo de plan de solo lectura hasta que el lead revise y apruebe su enfoque:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

El lead toma decisiones de aprobación de forma autónoma. Influya en su criterio con condiciones: “only approve plans that include test coverage” o “reject plans that modify the database schema.”

Prompts de ejemplo:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Spawn a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Almacenamiento: Las configuraciones de equipos residen en ~/.claude/teams/{team-name}/config.json (arreglo de miembros con nombre, ID de agente, tipo de agente). Las listas de tareas en ~/.claude/tasks/{team-name}/. Las tareas soportan dependencias: las tareas bloqueadas se desbloquean automáticamente cuando sus dependencias se completan.⁹¹

Integración con hooks: Use los hooks TeammateIdle (código de salida 2 para enviar retroalimentación y mantener al teammate trabajando) y TaskCompleted (código de salida 2 para prevenir la finalización) para aplicar controles de calidad a los teammates.

Limitaciones (experimental): - Sin reanudación de sesión para teammates in-process (/resume no los restaurará) - Un equipo por sesión; sin equipos anidados - Los teammates no pueden crear sus propios equipos - Los paneles divididos requieren tmux o iTerm2 (no soportado en VS Code terminal, Windows Terminal ni Ghostty) - Todos los teammates inician con el modo de permisos del lead - Uso intensivo de tokens: cada teammate es una instancia separada de Claude

Agent Skills (diciembre de 2025)

Los Agent Skills son carpetas organizadas de instrucciones, scripts y recursos que los agentes descubren y cargan dinámicamente.³¹ Proporcionan experiencia de dominio componible y portable:

.claude/skills/
├── security-review/
│   ├── skill.md           # Instructions and prompts
│   ├── checklist.md       # Security checklist
│   └── common-vulns.sh    # Detection scripts
└── performance-audit/
    ├── skill.md
    └── profiling-guide.md

Los skills difieren de los comandos: los comandos se invocan explícitamente, mientras que los skills se activan automáticamente según el contexto de la tarea. El Claude Agent SDK (renombrado de Claude Code SDK) proporciona el framework para construir agentes personalizados con soporte de skills.³²

¿Qué es el modo de pensamiento extendido?

El pensamiento extendido le da a Claude más tiempo para razonar problemas complejos antes de responder. Es particularmente valioso para decisiones arquitectónicas, depuración de problemas difíciles y tareas que requieren un análisis cuidadoso.

Estado actual (enero de 2026)

El pensamiento extendido ahora está habilitado por defecto con un presupuesto de 31.999 tokens, el presupuesto máximo que anteriormente se activaba con “ultrathink”.⁷⁰ Anthropic realizó este cambio porque el pensamiento extendido mejora significativamente el rendimiento en tareas complejas de planificación y razonamiento.

Importante: Los activadores en lenguaje natural como “think”, “think hard”, “think harder” y “ultrathink” ya no funcionan. Claude ahora interpreta estas palabras clave como instrucciones regulares del prompt y no asigna tokens de pensamiento. El presupuesto de pensamiento se controla exclusivamente mediante la variable de entorno MAX_THINKING_TOKENS o a través de /config.⁷⁰

Modelos compatibles

• Claude Opus 4.6 (también soporta pensamiento adaptativo, que determina automáticamente la profundidad de razonamiento)
• Claude Sonnet 4.6 (también soporta pensamiento adaptativo)
• Claude Opus 4.5
• Claude Sonnet 4.5
• Claude Haiku 4.5

Control del pensamiento extendido

Alternancia rápida durante la sesión:

Press Alt+T to toggle thinking on/off

Nota: Anthropic cambió el atajo de alternancia de pensamiento de Tab a Alt+T para evitar activaciones accidentales.³⁹

A través de /config: Navegue a /config → Extended Thinking para habilitar/deshabilitar o ajustar el presupuesto.

Variable de entorno (permanente):

# Set custom budget (default is 31,999)
export MAX_THINKING_TOKENS=8000
claude

# Double the default for complex tasks
export MAX_THINKING_TOKENS=63999
claude

Deshabilitar para ahorrar costos: Para tareas más simples donde no se necesita razonamiento profundo, puede reducir costos deshabilitando el pensamiento en /config o reduciendo el presupuesto:

export MAX_THINKING_TOKENS=8000  # Reduce from default 31,999

Presupuestos de tokens de pensamiento

Consideración de costos: Anthropic factura los tokens de pensamiento como tokens de salida. El presupuesto predeterminado de 31.999 funciona bien para la mayoría de las tareas, pero para operaciones simples puede ahorrar costos reduciendo el presupuesto o deshabilitando el pensamiento por completo.

Cómo funciona

Cuando el pensamiento está habilitado, Claude realiza un razonamiento interno que influye en la respuesta pero no aparece en la salida. Claude Code cifra el pensamiento y lo devuelve en un campo signature para verificación.

En conversaciones de múltiples turnos con uso de herramientas, los bloques de pensamiento deben enviarse de vuelta a la API para preservar la continuidad del razonamiento. Claude Code maneja esto automáticamente.

Cuándo considerar deshabilitar/reducir

El pensamiento extendido es ahora el predeterminado, pero considere reducir el presupuesto o deshabilitarlo para: - Ediciones simples de archivos - Refactorización rutinaria - Preguntas rápidas - Formateo de código - Operaciones de alto volumen donde los costos se acumulan

Comportamiento de caché

Claude Code preserva el almacenamiento en caché del prompt del sistema cuando cambian los parámetros de pensamiento. Cambiar el presupuesto de pensamiento o el estado de habilitación entre turnos invalida el almacenamiento en caché de mensajes.

Estilos de salida

Los estilos de salida personalizan cómo Claude presenta la información, lo cual es útil para aprendizaje, documentación o preferencias específicas del equipo.¹⁹

Estilos integrados

Configurar el estilo de salida

> /output-style Explanatory
> /output-style Learning

O a través de la configuración:

{
  "outputStyle": "Explanatory"
}

Estilos de salida personalizados

Créelos en .claude/styles/:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

Invóquelo con /output-style my-style.

Comandos de barra

Los comandos de barra proporcionan acceso rápido a las funciones de Claude Code y permiten flujos de trabajo personalizados. Son más rápidos que escribir prompts completos para operaciones comunes.

Referencia de comandos integrados

Creación de comandos personalizados

Cree comandos reutilizables en .claude/commands/ (proyecto) o ~/.claude/commands/ (personal):

---
description: Security-focused code review
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-5
---

Review this code for security vulnerabilities:

1. Injection attacks (SQL, command, XSS)
2. Authentication and authorization flaws
3. Sensitive data exposure
4. Insecure dependencies

Focus on actionable findings with specific line references.

Guárdelo como .claude/commands/security-review.md, invóquelo con /security-review.

Opciones de frontmatter de comandos

---
description: Brief description for /help
allowed-tools: Read, Edit, Bash(npm:*)
model: opus
argument-hint: [arg1] [arg2]
disable-model-invocation: false
---

Interpolación de argumentos

Todos los argumentos como cadena única:

---
description: Fix GitHub issue
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

Uso: /fix-issue 123

Argumentos numerados:

---
description: Create component
argument-hint: [name] [type]
---

Create a new $2 component named $1 in src/components/.

Uso: /create-component Button functional

Ejecución de Bash en línea

Ejecute comandos bash dentro de los prompts de comandos:

---
description: Git status summary
allowed-tools: Bash(git:*)
---

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`
Changed files: !`git status --short`

Summarize the current state of this repository.

Referencias a archivos

Incluya el contenido de archivos en los comandos:

---
description: Compare implementations
---

Compare these files:
@src/v1/handler.ts
@src/v2/handler.ts

Which implementation is more maintainable?

Espacios de nombres de comandos

Organice los comandos en subdirectorios:

.claude/commands/
├── backend/
│   ├── test.md
│   └── deploy.md
├── frontend/
│   ├── test.md
│   └── build.md
└── review.md

Los comandos con el mismo nombre muestran su espacio de nombres en la ayuda: /test (project:backend) vs /test (project:frontend).

¿Cómo funcionan los skills?

Los skills representan un enfoque fundamentalmente diferente para extender Claude Code. A diferencia de los slash commands que usted invoca explícitamente, los skills son invocados por el modelo—Claude los descubre y utiliza automáticamente según el contexto. Usted incorpora conocimiento experto en un skill, y Claude recurre a esa experiencia cuando la situación lo requiere, sin necesidad de que usted recuerde pedirlo.

Por qué los skills lo cambian todo: Considere el conocimiento experto de un dominio: las reglas de procesamiento de pagos, los requisitos de cumplimiento normativo, los patrones arquitectónicos que su equipo ha refinado durante años. Sin skills, usted debe re-explicar este contexto en cada sesión o esperar que Claude lo infiera de los comentarios en el código. Con skills, lo codifica una sola vez. Claude lee la definición del skill y aplica ese conocimiento automáticamente cuando sea relevante. Sus desarrolladores junior reciben orientación de nivel senior sin pedirla. Sus patrones de seguridad se aplican sin necesidad de recordar invocarlos.

La distinción es importante. Un slash command es un atajo que usted recuerda usar. Un skill es conocimiento que Claude siempre tiene disponible. Cuando crea un skill de revisión de seguridad con los patrones de vulnerabilidad específicos de su equipo y los requisitos de cumplimiento, Claude aplica esa experiencia cada vez que encuentra código relevante, ya sea durante revisiones de PR, refactorización o cualquier tarea donde la seguridad importa. Usted no invoca /security-review; Claude reconoce el contexto y aplica el skill automáticamente.

Skills vs Commands vs Subagents

Comprender cuándo usar cada mecanismo de extensión evita duplicación y maximiza la efectividad: