Cómo depurar con Claude Code: encuentra la causa del bug
Para depurar con Claude Code, describe el error con hechos concretos y deja que el agente explore el código hasta encontrar la causa, en lugar de pedirle un parche a ciegas. El comando /debug ataca la depuración del sistema, y para bugs difíciles puedes lanzar un equipo de subagentes. La clave de un buen debugging no es un prompt perfecto, sino darle el contexto correcto: el síntoma exacto, cómo reproducirlo y dónde empezar a mirar.
El error de principiante: pedir "arregla el bug" sin contexto. El agente parchea el síntoma sin entender la causa. Mejor: describe qué esperabas, qué pasó, cómo reproducirlo, y deja que primero encuentre la causa.
El flujo de depuración
- Describe el bug con hechos: comportamiento esperado vs real, mensaje de error exacto, pasos para reproducir. Cuanto más concreto, mejor el diagnóstico.
- Dale el material: carga el log o el stack trace con
@ruta/archivo, o píealo en modo headless:cat error.log | claude -p "¿qué está fallando?". - Pide la causa antes del parche: deja que el agente explore (a menudo lanzando un Explore Subagent) y te explique la raíz, no solo el síntoma.
- Usa
/debugpara la depuración del sistema cuando el problema es más profundo. - Verifica: que corra los tests o reproduzca el caso para confirmar que el fix funciona.
Para bugs difíciles: equipos de subagentes
Cuando un bug resiste (un sistema distribuido, un fallo intermitente), un solo agente puede quedarse corto. Ahí entran los equipos de subagentes: varios exploran distintas hipótesis en paralelo y un coordinador integra los hallazgos. Y para una segunda opinión con otro modelo, la revisión adversarial con Codex detecta lo que un solo modelo pasó por alto.
Cuida el contexto al depurar
Un riesgo concreto: si corriges el mismo error dos veces sin avanzar, el contexto ya está contaminado (es el Long Context Failure). El modelo empieza a repetir intentos fallidos. Mejor /clear, reformula el problema con lo que aprendiste, y vuelve a empezar con el contexto limpio.
Preguntas frecuentes
¿Cómo depuro un error con Claude Code?
Describe el bug con hechos concretos (comportamiento esperado, error exacto, cómo reproducirlo), dale el log o el stack trace, y pídele que encuentre la causa antes de proponer un parche. El comando /debug sirve para la depuración del sistema, y conviene verificar el fix corriendo los tests.
¿Qué hace el comando /debug en Claude Code?
Ataca la depuración del sistema: deja que el agente explore el código para encontrar la causa de un fallo, en lugar de parchear el síntoma. Es útil cuando el problema es más profundo que un error obvio.
¿Cómo le paso un log de error a Claude Code?
Puedes cargarlo al contexto con @ruta/al/log, o pipearlo en modo headless: cat error.log | claude -p "¿qué está fallando aquí?". Darle el stack trace o el log concreto mejora mucho el diagnóstico frente a describirlo con palabras.
¿Qué hago si Claude Code no encuentra el bug?
Si repite intentos fallidos, el contexto está contaminado: usa /clear y reformula el problema con lo aprendido. Para bugs difíciles, lanza un equipo de subagentes que exploren hipótesis en paralelo, o pide una revisión adversarial con otro modelo.
Recursos relacionados
- Equipos de subagentes y Long Context Failure.
- Comandos de calidad: refactor, debug, worktrees.
- Guía completa para dominar Claude Code.
Tu siguiente paso
Los comandos de calidad y debugging están en la Cheat Sheet de Claude Code: una hoja imprimible, en español.
Descargar la Cheat Sheet gratis
Es el resumen de Ship with Claude Code, la guía de Takren (14 módulos, 190 capítulos, actualizaciones gratuitas).