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

URL: https://agentvera.dev/es/blog/debug-code-with-ai/ · Publicado: 2026-10-27

Depura código con IA de forma fiable: reproduce primero, dale al agente el test que falla y los logs, usa git bisect, busca la causa raíz y fíjala con un test.

**En resumen:**

- Un agente de IA depura bien cuando puede ejecutar el bug por sí mismo: empieza por una reproducción, un test que falla o un comando exacto, no por una descripción del síntoma.
- Dale el stack trace completo y los logs, deja que busque con git bisect run, que añada logs temporales y pídele la causa raíz antes de cualquier corrección.
- Termina con un test de regresión que falle antes de la corrección y pase después, y detén al agente cuando empiece a adivinar o a relajar los tests.

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

```text
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:

```text
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:

```bash
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](/es/glossary/context-window/ "Qué es la 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:

```bash
#!/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:

```bash
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:

```text
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](/es/blog/git-worktree-parallel-agents/ "Git worktrees para agentes en paralelo") 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:

```text
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:

```bash
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:

```text
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](/es/blog/claude-code-plan-mode/ "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:

```text
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](/es/blog/write-unit-tests-with-ai/ "Escribir tests unitarios con IA").

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

| Patrón en el diff | Por qué es sospechoso |
| --- | --- |
| Nuevo `try/catch` que registra el error y continúa | El error queda oculto y el estado incorrecto sigue ahí |
| Encadenamiento opcional o `?? default` añadido donde se produce el fallo | Trata la falta de datos como algo normal en lugar de preguntar por qué faltan |
| Reintentos o timeouts más largos | A menudo ocultan una condición de carrera |
| Tipo ampliado a `any` o `unknown` | Silencia al compilador en lugar de corregir el tipo |
| Expectativa del test modificada | Se ha movido la portería |

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](https://github.com/microsoft/playwright-mcp "Playwright MCP") el agente puede abrir la página y verlo por sí mismo. Añádelo a Claude Code:

```bash
claude mcp add playwright npx @playwright/mcp@latest
```

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

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

```text
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](/es/blog/ai-agent-browser-testing/ "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](/es/blog/auto-fix-ci-failures-with-ai/ "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](/es/blog/undo-claude-code-changes/ "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/download/ "Descargar 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](/es/features/send-to-agent/ "Enviar a un 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](/es/features/agent-browser/ "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](/es/features/checkpoints-and-replay/ "Checkpoints y repetición de sesiones"):** 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](/es/features/git-and-github/ "Git y GitHub"), dale a cada uno una hipótesis distinta y quédate con la corrección que se sostenga.
- **[Verify](/es/features/verify/ "AgentVera 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](/es/blog/write-documentation-with-ai/ "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.

## Preguntas frecuentes

**¿La IA puede depurar código de verdad o solo adivina?** Un agente de programación puede depurar de verdad cuando puede ejecutar el código: reproducir el bug, leer la salida, añadir logs y poner a prueba una hipótesis. Si no tiene forma de ejecutar el caso que falla, solo puede adivinar leyendo, y de ahí sale la mayoría de las correcciones equivocadas.

**¿Qué le doy al agente cuando le informo de un bug?** El comando o test exacto que falla, el error completo con su stack trace, lo que esperabas en su lugar y cualquier cosa que haya cambiado hace poco. Una reproducción de una línea vale más que una descripción larga del síntoma.

**¿Un agente puede ejecutar git bisect por su cuenta?** Sí. Dale un commit bueno, uno malo y un script que termine con 0 cuando el código funciona y con 1 cuando no. git bisect run va haciendo checkout de commits y ejecutando el script hasta encontrar el primero malo. El código de salida 125 le dice a git que se salte un commit que no se puede probar.

**¿Cómo evito que un agente de IA haga una corrección que solo oculta el bug?** Pídele la causa raíz en palabras sencillas antes de cambiar código, prohíbele editar o saltarse los tests existentes y exige un test de regresión que falle sin la corrección. Revisa el diff en busca de bloques try/catch, reintentos y tipos ampliados que silencian el error en lugar de eliminar su causa.

**¿Cuándo debo detener al agente y depurar yo mismo?** Cuando ha probado dos o tres correcciones que no han funcionado, cuando empieza a cambiar archivos que no tienen relación o cuando propone debilitar un test o una aserción. Detenlo, deshaz sus cambios y empieza de nuevo con una reproducción más precisa o una pregunta más acotada.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/