Cap 17: Debugging

/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:

1. Iniciar un proceso en background
2. Monitorear stdout/stderr
3. Detectar errores en tiempo real
4. Proponer y aplicar fixes

MCP Browsers para debugging web

Playwright MCP

Automatización de navegador para testing y debugging:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright@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": ["@anthropic-ai/mcp-chrome-devtools@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

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

Patrón de debugging efectivo

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

---

Siguiente: Status Line y UX