Debugging con agentes de IA: método, no adivinar

El error más frecuente

Mucha gente le da a un agente solo «arregla el bug» — sin mensaje de error, sin contexto. Entonces el agente adivina. El debugging sistemático funciona de otra forma.

Paso 1: reproducir el error

Dale al agente el comando con el que aparece el error, y deja que provoque el fallo él mismo. La documentación de Claude Code recomienda justo eso: decirle al agente cómo reproducir el problema y obtener un stack trace. Un error que el agente puede provocar por sí mismo también es uno que puede verificar por sí mismo después del fix.

Paso 2: aportar logs y stack traces

Pega el mensaje de error completo, en vez de describirlo. También funciona por pipe: cat error.log | claude -p "explica la causa". Indica además si el error aparece siempre o solo a veces.

Paso 3: hipótesis antes que fix

Deja que el agente nombre primero las causas probables, ordenadas por probabilidad — y luego compruebe una de forma dirigida. Importante: arreglar la causa, no el síntoma. La documentación oficial lo formula como regla de prompt: «address the root cause, don't suppress the error» (ataca la causa raíz, no ocultes el error).

Herramientas de diagnóstico

Para problemas con el propio Claude Code existe /doctor: una comprobación automática de la instalación, los ajustes, las extensiones y el uso de contexto. Si claude ni siquiera arranca, ayuda claude doctor directamente desde la shell.