Cómo depurar código con IA: un flujo de trabajo práctico

Para depurar código con IA, dale al agente una forma de reproducir el bug, el error completo y los logs, y una regla clara: encontrar la causa raíz antes de cambiar nada. Un agente de programación como Claude Code o Codex puede ejecutar tus tests, leer stack traces, recorrer tu historial de git con bisect y añadir logs, lo que lo convierte en un buen compañero de depuración. También falla de formas previsibles: adivina cuando no puede ejecutar el caso que falla y “corrige” síntomas capturando errores o relajando tests.

Esta guía es un flujo de trabajo que aprovecha lo primero y te protege de lo segundo: reproducir, aportar las pruebas, acotar, explicar, corregir, fijarlo con un test y saber cuándo cortar.

Por qué los agentes depuran mal

La mayoría de las malas correcciones de la IA salen de los mismos pocos sitios:

• Sin reproducción. El agente lee el código, se forma una teoría y aplica un parche. Nada demuestra que la teoría fuera correcta.
• Pruebas a medias. Pegas la última línea del error. El frame útil, tres niveles más abajo en la pila, nunca llega al modelo.
• Corregir el síntoma. Una comprobación de null, un try/catch o un reintento hacen desaparecer el error mientras el estado incorrecto que lo causó sigue ahí.
• Mover la portería. El test falla, así que el agente edita el test.
• Sesiones largas y contaminadas. Tras cinco intentos fallidos, la conversación está llena de teorías equivocadas y el modelo sigue construyendo sobre ellas.

Cada paso de los que siguen apunta a uno de estos problemas.

Paso 1: reproduce el bug primero

Antes de que el agente toque el código, necesita un comando que muestre el bug. Puede ser un test que falla, una llamada con curl, un script o una página en el navegador. Lo importante es que cualquiera, incluido el agente, pueda ejecutarlo y ver el fallo.

Si ya tienes uno, ponlo al principio del prompt:

Esto falla:

  pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"

Esperaba un total de 90 y da 81. No cambies nada de código todavía.
Ejecuta el test, confirma que ves el mismo fallo y dime qué ves.

Si no tienes una reproducción, que esa sea la primera tarea:

Los usuarios dicen que guardar un borrador dos veces crea dos borradores.
Escribe un test que falle y reproduzca esto. No corrijas nada.
Para cuando el test falle por el motivo correcto.

“Por el motivo correcto” importa. Un test que falla por una errata en el propio test no demuestra nada. Pide al agente que muestre la salida del fallo y explique por qué coincide con el informe del bug. Con los bugs intermitentes, haz que ejecute la reproducción en bucle (por ejemplo, 50 veces) e informe de cuántas veces falla, para que luego puedas saber si una corrección ha servido de algo.

Paso 2: dale al agente todas las pruebas

Los agentes leen bien salidas largas y ruidosas. No se las recortes. Dale:

• el stack trace completo, no solo el mensaje;
• el comando exacto y su salida completa;
• los logs relevantes de alrededor del momento del fallo;
• qué ha cambiado hace poco: una actualización de dependencias, un despliegue, una rama fusionada;
• detalles del entorno si pueden importar: sistema operativo, versión del runtime, feature flags.

No hace falta que lo pegues todo en el chat. Guárdalo en un archivo y señálaselo al agente, o pásaselo directamente por una tubería. Con el modo print de Claude Code:

pnpm test 2>&1 | tail -n 200 > /tmp/test-output.txt
cat /tmp/test-output.txt | claude -p "Explain the root cause of this failure. Don't edit files."

Dentro de una sesión interactiva, ! ejecuta un comando de shell y añade su salida a la conversación, tanto en Claude Code como en Codex; por ejemplo, !pnpm test src/billing. Con logs enormes, pide al agente que haga grep del ID de la petición o del código de error en lugar de leer el archivo entero; así ahorra mucha ventana de contexto.

Paso 3: acótalo con git bisect

Cuando algo funcionaba y ahora no, no necesitas una teoría. git bisect encuentra el primer commit malo mediante búsqueda binaria y puede funcionar de forma totalmente automática, lo que lo convierte en un trabajo perfecto para un agente.

Primero, escribe un pequeño script que termine con 0 cuando el código está bien y con un valor distinto de cero cuando está mal:

#!/bin/sh
# check.sh
pnpm install --frozen-lockfile >/dev/null 2>&1 || exit 125
pnpm vitest run src/billing/invoice.test.ts -t "applies discount once"

Después deja que git haga el recorrido:

git bisect start
git bisect bad HEAD
git bisect good v2.3.0
git bisect run ./check.sh
git bisect reset

Los códigos de salida son el contrato, tal como los define la documentación oficial de git bisect: 0 significa bueno, cualquier código de 1 a 127 salvo el 125 significa malo, 125 significa “no se puede probar este commit, sáltalo” y cualquier valor mayor aborta el bisect. Por eso el paso de instalación de arriba termina con 125: un commit que ni siquiera se instala debe saltarse, no contarse como malo.

Un prompt que le pasa todo el trabajo a un agente:

El test del descuento de la factura pasa en la etiqueta v2.3.0 y falla en main.
Escribe un script de comprobación para git bisect run (exit 125 si el commit
no se puede compilar), ejecuta el bisect y luego git bisect reset.
Dime cuál es el primer commit malo y explica qué línea de su diff
causa el fallo. No corrijas nada todavía.

Asegúrate antes de que el árbol de trabajo esté limpio, o hazlo en un git worktree aparte para que los checkouts del bisect no choquen con tu propio trabajo. Si el archivo de test no existía en los commits antiguos, cópialo a una ruta fuera del repositorio y haz que el script ejecute esa copia.

Paso 4: añade logs y luego quítalos

Cuando el stack trace no explica el estado que llevó al error, el agente necesita ver valores en tiempo de ejecución. Pídele logs concretos y temporales:

Añade logs temporales que impriman los artículos del carrito, la lista de
descuentos y el total acumulado en cada paso de applyDiscounts(). Pon el
prefijo [DEBUG-1234] en cada línea para poder encontrarlas y quitarlas
después. Ejecuta el test que falla y enséñame las líneas de log.

El truco está en el prefijo. Cuando el bug está entendido, una sola instrucción lo limpia:

git grep -n "DEBUG-1234"

Los agentes también se manejan bien con depuradores cuando se pueden usar desde scripts: node --inspect con un breakpoint es incómodo para un agente de terminal, pero una sesión rápida de python -m pdb, una aserción extra o un script puntual que llame a la función con la entrada que falla suelen dar la misma respuesta más deprisa.

Paso 5: la causa raíz antes de la corrección

Esta es la regla más importante. Pide al agente que explique el bug antes de escribir una corrección, y lee la explicación:

Antes de cambiar código, explica la causa raíz:
1. ¿Qué estado es incorrecto y dónde se vuelve incorrecto por primera vez?
2. ¿Por qué el código produce ese estado?
3. ¿Por qué no lo detectaron los tests existentes?
Después propón la corrección más pequeña y espera mi visto bueno.

Una buena respuesta señala una línea concreta y una condición concreta (“el descuento se aplica tanto en addItem como en checkout desde que el commit a1b2c3 movió la llamada”). Una respuesta floja es vaga (“puede haber un problema con la forma en que se gestionan los descuentos”) o salta directamente a un parche defensivo. Si recibes una del segundo tipo, el agente todavía no ha encontrado la causa; mándalo de vuelta al paso 3 o al 4.

Aquí viene bien el modo plan de Claude Code, porque el agente puede leer y ejecutar comandos de solo lectura, pero no editar archivos hasta que lo apruebes. Arráncalo con claude --permission-mode plan o pulsa Shift+Tab para pasar a él. Modo plan de Claude Code lo explica en detalle. En Codex, /plan cumple una función parecida.

Paso 6: corrígelo y fíjalo con un test de regresión

Ahora deja que el agente lo corrija, con restricciones:

Aplica la corrección. Reglas:
- No edites ni te saltes los tests existentes.
- No captures el error para silenciarlo.
- Añade un test de regresión con el nombre del bug que falle sin
  la corrección y pase con ella. Demuestra ambas cosas: revierte la
  corrección, ejecuta el test, restaura la corrección y vuelve a ejecutarlo.
- Ejecuta todos los tests al final.

La parte de “demuestra ambas cosas” es lo que hace fiable el test. Un test de regresión que habría pasado antes de la corrección es decoración. Para sacar tests útiles de un agente, consulta cómo escribir tests unitarios con IA.

Después revisa tú mismo el diff, buscando las correcciones de síntoma habituales:

A veces uno de estos cambios es la corrección adecuada. La pregunta que hay que hacerse es si el agente explicó por qué.

Bugs del navegador: dale un navegador al agente

Los bugs de interfaz son difíciles de describir con texto: un botón que no hace nada, un diseño que se rompe tras un clic, un error que solo aparece en la consola. Con Playwright MCP el agente puede abrir la página y verlo por sí mismo. Añádelo a Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

o a Codex en ~/.codex/config.toml:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

Herramientas como browser_navigate, browser_click, browser_snapshot, browser_console_messages y browser_network_requests permiten al agente reproducir el bug paso a paso, leer los errores de la consola y ver qué llamada a la API falló. Un prompt de depuración:

Arranca el servidor de desarrollo. Abre http://localhost:5173/settings,
cambia el nombre visible y haz clic en Save. Informa de los errores de
consola y de la petición de red del guardado, con su estado y el cuerpo
de la respuesta. No corrijas nada todavía.

Una vez clara la causa, pide al agente que convierta los pasos en un test de Playwright para que el bug no vuelva. Pruebas en el navegador con agentes de IA profundiza en la configuración.

Bugs que solo aparecen en CI

Cuando los tests pasan en local pero fallan en CI, la diferencia suele estar en el entorno: zona horaria, configuración regional, paralelismo, variables de entorno que faltan, otra versión de Node o Python, o el orden de los tests. Dale al agente el log de CI y el archivo del workflow, y pídele que enumere las diferencias entre CI y tu máquina antes de adivinar. Ejecutar los tests en orden aleatorio o con la zona horaria de CI (TZ=UTC pnpm test) suele reproducir el fallo en local. Si los fallos de CI son una tarea habitual, corregir fallos de CI automáticamente con IA muestra cómo automatizar el ciclo.

Cuándo detener al agente

Un agente seguirá intentándolo mucho después de cuando debería parar. Córtalo cuando:

• Han fallado dos o tres correcciones. Cada nuevo intento se basa en la misma teoría equivocada.
• El diff se extiende. Empezó en invoice.ts y ahora está editando la configuración, módulos sin relación o lock files.
• Toca los tests. Cambiar una aserción para que coincida con la salida incorrecta nunca es corregir un bug.
• No consigue reproducir el bug, pero lo corrige de todos modos.
• La explicación cambia de un turno a otro sin pruebas nuevas.

Qué hacer en su lugar:

1. Detén el turno (Esc en Claude Code y Codex).
2. Deshaz sus cambios. Haz commit antes de empezar a depurar para que git restore . o git stash te devuelvan al punto de partida; deshacer los cambios de Claude Code repasa las opciones.
3. Apunta lo que has aprendido: qué teorías eran erróneas y por qué.
4. Empieza una sesión nueva con la reproducción, los hechos y las teorías descartadas. Un contexto limpio con tres hechos buenos vale más que uno largo con diez malas suposiciones.

A veces lo correcto es plantear una pregunta más acotada: “¿cart.items ya está mal cuando se llama a checkout()?” es más fácil de responder que “arregla el bug del checkout”.

Depurar con AgentVera

AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta Claude Code, Codex, Gemini CLI y otros agentes CLI en terminales reales, uno al lado de otro. Varias de sus herramientas encajan con el flujo anterior:

• Enviar al agente: selecciona un error en el dock de terminales, la consola del navegador o los logs de Docker y envíalo a un agente con ⌘⇧L, o haz clic en la insignia Fix de un error detectado. Los logs largos se limitan a 12.000 caracteres y conservan el final, que es donde suele estar el stack trace.
• Navegador del agente: un Chrome con un perfil aparte que los agentes controlan mediante Playwright MCP, con las pestañas retransmitidas en directo para que veas cómo el agente reproduce el bug.
• Checkpoints: cada turno se guarda como instantánea en una ref de git oculta, así que puedes ver qué cambió un intento fallido y deshacer ese turno sin tocar tus ramas ni tu stash.
• Dos teorías en paralelo: inicia dos agentes en worktrees separados desde el panel Git, dale a cada uno una hipótesis distinta y quédate con la corrección que se sostenga.
• Verify: en Pro y Team, un verificador independiente de solo lectura comprueba criterios como “el test de regresión falla sin la corrección y pasa con ella” cuando termina el turno del agente.

Una vez corregido el bug, apunta lo que has aprendido donde la próxima persona vaya a encontrarlo; escribir documentación con IA cubre esa parte.

Conclusión

Depurar con un agente de IA funciona cuando lo tratas como depurar con un compañero espabilado: parte de una reproducción, comparte todas las pruebas, acota la búsqueda con git bisect, añade logs para ver los valores reales e insiste en la causa raíz antes de la corrección. Cierra cada bug con un test de regresión que hayas visto fallar y pasar. Y cuando el agente empiece a adivinar, detenlo, deshaz y empieza de nuevo con lo que has aprendido.