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

Los agentes debuguean mejor con un error reproducible, logs reales y una hipótesis antes del fix — no con «arregla el bug».

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.

EJEMPLO

Prompt: «npm test falla. Aquí está el stack trace completo: [pega]. Reproduce el error, nombra la causa más probable y escribe primero un test que falle antes de arreglar nada.»

🛠️ EJERCICIO — PRUÉBALO TÚ

Introduce a propósito un bug pequeño en un proyecto de práctica (p. ej. una errata en el nombre de una variable) y haz que un agente lo encuentre de forma sistemática.

Provoca el error y copia el mensaje de error completo junto con el stack trace.
Dale al agente el mensaje de error y el comando de reproducción — y exige primero una hipótesis, todavía ningún fix.
Permite el fix solo después de haber leído la hipótesis, y haz que el agente verifique el éxito con el mismo comando.

✅ AUTOEVALUACIÓN

☐ ¿Nombró el agente la causa correcta antes de cambiar algo?
☐ ¿Demostró el fix con el comando de reproducción (mostrando la salida), en vez de limitarse a decir «hecho»?
☐ ¿Qué habría faltado si solo hubieras escrito «hay un bug»?

QUIZ RÁPIDO

¿Cuál es el primer paso más razonable cuando un agente debe arreglar un bug?