← Volver al listado de tecnologías ← Índice de Claude Code

Cap 17: Debugging

2 de marzo de 2026 Por: Artiko

claude-codedebuggingdoctorbrowserdiagnóstico

/doctor — Diagnóstico del sistema

El comando /doctor ejecuta diagnósticos completos de la instalación de Claude Code:

/doctor

Verifica:

Versión de Claude Code y actualizaciones disponibles
Estado de autenticación
Conectividad con API de Anthropic
Servidores MCP configurados y su estado
Permisos y configuración del sandbox
Estado de git y worktrees

Desde CLI

claude doctor

/debug — Modo debug

Activa logging detallado para investigar problemas:

# Modo debug general
/debug

# Debug con descripción del problema
/debug "los MCP servers no se conectan"

Debug con filtrado por categoría

# Solo debug de API y MCP
claude --debug "api,mcp"

# Todo excepto statsig y file
claude --debug "!statsig,!file"

Categorías disponibles: api, mcp, hooks, file, tools, permissions, entre otras.

Verbose mode

Para ver el output turn-by-turn completo:

claude --verbose

Muestra cada interacción con la API, incluyendo las herramientas usadas y sus resultados.

Background tasks para logs

Un patrón útil para debugging: ejecutar el servidor o proceso en background y dejar que Claude monitoree los logs:

# En Claude Code
"Ejecuta el servidor de desarrollo en background y monitorea los logs.
Si ves errores, analiza la causa raíz."

Claude puede:

Iniciar un proceso en background
Monitorear stdout/stderr
Detectar errores en tiempo real
Proponer y aplicar fixes

Superficie real de background tasks

/tasks lista las tareas en background de la sesión.
Los flags --bg / --background arrancan trabajo en segundo plano desde el CLI.
Los subcomandos claude agents, claude attach, claude stop, claude respawn y claude logs permiten listar, adjuntarse, detener, relanzar y leer la salida de esos procesos.

Desde v2.1.212, una llamada MCP hecha desde la conversación principal que supera 2 minutos pasa automáticamente a background task y aparece en /tasks. El umbral se ajusta con CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS (0 lo apaga). No aplica a subagentes, servidores IDE ni modo no interactivo, salvo que se defina CLAUDE_AUTO_BACKGROUND_TASKS=1.

MCP Browsers para debugging web

Antes de conectar nada: «Verify you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection risk.» Anthropic revisa los conectores del Directory contra criterios de listado, pero no audita ni gestiona servidores MCP de terceros. Los nombres de paquete de los ejemplos siguientes dependen del proveedor concreto del servidor: verifícalos en su documentación antes de ejecutarlos.

Playwright MCP

Automatización de navegador para testing y debugging:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["<paquete-del-proveedor>@latest"]
    }
  }
}

Capacidades:

Navegar a URLs
Tomar screenshots
Inspeccionar el DOM
Ejecutar JavaScript en la página
Interactuar con elementos (click, type, fill)
Capturar requests de red

Chrome DevTools MCP

Conecta con una sesión real de Chrome para debugging:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["<paquete-del-proveedor>@latest"]
    }
  }
}

Capacidades:

Acceder a la consola de Chrome
Inspeccionar requests de red
Analizar performance
Tomar memory snapshots
Evaluar scripts en contexto de la página

Claude in Chrome

Integración directa con Chrome habilitada con --chrome:

claude --chrome

Conecta con tu sesión real del navegador, incluyendo cookies, autenticación y estado actual.

Comparación de MCP browsers

Feature	Playwright	Chrome DevTools	Claude in Chrome
Tokens por snapshot	~13.7K	~19.0K	~15.4K
Cross-browser	Sí	Solo Chrome	Solo Chrome
Sesión real	No (nueva)	Sí	Sí
E2E testing	Ideal	No	No
Performance	No	Ideal	Parcial
Autenticación	Mock	Real	Real

Riesgo de prompt injection al traer la web al contexto

Traer páginas web y servidores MCP de terceros a una sesión de debugging amplía la superficie de ataque. El modelo de amenaza oficial lo dice directo: el comportamiento del agente puede ser influido por el contenido que procesa — archivos, páginas web o entrada de usuario. Si un README o una página cargada contiene instrucciones inusuales, Claude Code puede incorporarlas a sus acciones de formas no previstas.

Mitigaciones nativas vigentes:

WebFetch corre en una ventana de contexto aislada.
Los resultados de búsqueda web se resumen en vez de pasar contenido crudo al contexto.
curl y wget no se auto-aprueban por defecto.
Existe verificación de confianza (trust) para codebases y servidores MCP nuevos, pero se desactiva al correr no interactivamente con -p: un pipeline de CI no conserva las mismas barreras que una sesión interactiva.

La defensa es en profundidad (aislamiento, mínimo privilegio, controles de red), no confiar solo en el modelo. «No system is completely immune to all attacks.»

Screenshots como contexto

Claude Code puede leer imágenes. Proveer screenshots es una de las formas más efectivas de reportar bugs visuales:

# Claude puede leer screenshots directamente
"Mira el screenshot en /tmp/bug-screenshot.png y diagnostica el problema visual"

Debugging de MCP servers

Si un servidor MCP no funciona:

# Ver estado de todos los servidores
claude mcp list

# Debug específico
claude --debug "mcp"

# Verificar configuración
cat .mcp.json

Tool search: no ver las herramientas no significa que el servidor falló

Tool search está activo por defecto. Al inicio de la sesión solo entran al contexto los nombres de las herramientas MCP y las instrucciones del servidor; las definiciones completas se difieren y se cargan bajo demanda a través de la herramienta ToolSearch. Es el error de diagnóstico más común: no ver tus herramientas MCP en el contexto no implica que el servidor esté caído.

Control del comportamiento con ENABLE_TOOL_SEARCH:

Valor	Comportamiento
sin definir	Todo diferido
`true`	Todo diferido, forzando el header beta
`auto`	Carga upfront si las definiciones caben en el 10% de la ventana; difiere el resto
`auto:N`	Igual que `auto` con umbral porcentual custom (0-100)
`false`	Todo upfront

También se puede desactivar con permissions.deny: ["ToolSearch"].

Exenciones para que un servidor o una herramienta carguen siempre upfront:

"alwaysLoad": true en el entry del servidor (v2.1.121+, todos los transportes). Bloquea el arranque hasta conectar, con tope de 5 s.
"anthropic/alwaysLoad": true en el _meta de una herramienta concreta.

Tool search está desactivado por defecto en Google Cloud Agent Platform y cuando ANTHROPIC_BASE_URL apunta a un host que no es de primera parte (la mayoría de proxies no reenvían bloques tool_reference).

Errores de configuración frecuentes

url sin type: un entry con url pero sin type es error de configuración; se omite y se reporta MCP server "<name>" has a "url" but no "type". Antes de v2.1.202 el mensaje era el críptico command: expected string, received undefined.
Transportes: stdio (default cuando no se declara type), http, sse (DEPRECADO) y ws. En JSON, type acepta streamable-http como alias de http. El transporte ws solo se configura por .mcp.json o claude mcp add-json, no por --transport.

Timeouts

Situación	Valor
Arranque del servidor	`MCP_TIMEOUT`
Ejecución de herramienta	`timeout` por servidor, en ms (valores <1000 se ignoran y caen a `MCP_TOOL_TIMEOUT`, default ~28 h)
Primer byte en HTTP/SSE/conectores	timer de 60 s por request
Idle timeout (v2.1.187+)	5 min en HTTP/SSE/WS/conectores, 30 min en stdio; ajustable con `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` (`0` lo desactiva)

Truncados y límites de salida

Aviso cuando la salida de una herramienta supera 10.000 tokens (umbral fijo, no configurable).
Límite máximo por defecto de 25.000 tokens, ajustable con MAX_MCP_OUTPUT_TOKENS.
Las descripciones de herramientas y las instrucciones del servidor se truncan a 2KB cada una: si tu servidor documenta demasiado, lo crítico debe ir al principio.

Patrón de debugging efectivo

Reproducir: “Reproduce el error y muéstrame el output exacto”
Investigar: “Investiga la causa raíz sin proponer soluciones”
Diagnosticar: “¿Qué componentes están involucrados?”
Proponer: “Dame 2-3 soluciones con pros y contras”
Implementar: “Implementa la solución X y agrega un test”
Verificar: “Ejecuta los tests y confirma el fix”

Regla de verificación ejecutable

Pide evidencia, no aserciones de éxito: salida de tests, el comando ejecutado con su resultado, un screenshot. Sin un check, «looks done» es la única señal y el humano se convierte en el loop de verificación. La regla canónica es directa: «If you can’t verify it, don’t ship it.»

Regla de las dos correcciones

Si corregiste a Claude más de dos veces sobre lo mismo, el contexto ya está contaminado con enfoques fallidos — lo más habitual en una sesión de depuración larga. La respuesta no es insistir: /clear y reescribir el prompt inicial incorporando lo aprendido. «A clean session with a better prompt almost always outperforms a long session with accumulated corrections.»

Herramientas complementarias:

/rewind (o doble Esc con el input vacío) para volver a un checkpoint anterior de código y/o conversación.
/btw para preguntas laterales cuya respuesta no debe entrar al historial.

Siguiente: Status Line y UX