Depuración asistida por IA
En esta página
Encuentra y corrige errores más rápido
La depuración sigue siendo un arte: comprender el síntoma, rastrearlo hasta su causa raíz y solucionarlo sin romper nada más. Codex ayuda en los tres pasos, pero de forma desigual. En el primero, apenas aporta valor, ya que eres tú quien observa el síntoma y sabe cómo debería comportarse el sistema. En el segundo, destaca, porque rastrear un flujo de datos a través de diez archivos es una tarea de lectura sistemática, exactamente lo que una máquina hace mejor que un humano cansado. En el tercero, ofrece verificación inmediata mediante pruebas.
Depura a partir de un error
El caso más directo: pasa el error tal cual, sin reformularlo ni resumirlo.
"La prueba src/api/routes/orders.test.ts falla con:
TypeError: Cannot read properties of undefined
(reading 'id')
at createOrder (src/services/order.service.ts:42)
Encuentra la causa y corrige el error."
El agente encadena entonces seis operaciones: lee el archivo de prueba para entender el escenario, abre order.service.ts en la línea 42, rastrea el flujo de datos para encontrar dónde se introdujo el undefined, identifica la causa raíz (un parámetro faltante, un error de tipado u otra cosa), propone y aplica la corrección, y finalmente vuelve a ejecutar la prueba para verificarla. La tercera operación es la que te habría costado veinte minutos de lectura en silencio.
Depura comportamientos inesperados
A menudo no hay ningún error: el programa hace algo incorrecto en silencio. Estos son los errores más costosos y aquellos en los que la forma de formular tu solicitud importa más.
"La ruta POST /api/orders crea el pedido en la base de
datos, pero el total es siempre 0. Los precios de los
productos son correctos en la tabla products. Encuentra
por qué falla el cálculo del total."
Esta instrucción funciona porque define el alcance: qué funciona, qué no y una hipótesis ya descartada, dado que los precios en la base de datos son correctos. Codex rastrea entonces el flujo desde la petición HTTP hasta la inserción, aísla dónde se desvía el cálculo y propone una solución. Sin la frase sobre la tabla products, lo más probable es que empezara comprobando exactamente lo que tú ya has comprobado.
Analiza registros de producción
También puedes partir de trazas de producción, simplemente pegando el extracto relevante.
"Aquí hay un extracto de los registros de producción. La
aplicación devuelve intermitentemente un 500 en /api/checkout:
[2026-04-01 14:23:01] ERROR: Connection pool exhausted
[2026-04-01 14:23:01] WARN: Query timeout after 30s
[2026-04-01 14:23:02] ERROR: Transaction rollback
Analiza el código de la ruta checkout e identifica la fuga
de conexiones."
Codex conecta las tres líneas (pool agotado, tiempo de espera de consulta superado, transacción revertida), concluye que hay una fuga de conexiones a la base de datos y busca en el código los lugares donde se abre una conexión pero no se cierra correctamente. Este es típicamente un error que ninguna prueba revela, ya que solo aparece bajo carga y desaparece en cuanto intentas reproducirlo localmente.
Depuración por bisección
Cuando el problema es difuso en lugar de estar localizado, solicita una investigación metódica en lugar de una corrección rápida.
"La compilación de TypeScript falla con 23 errores de tipo
desde la última actualización de dependencias. Analiza cada
error, identifica si se trata de un cambio de API en una
dependencia y corrige el código para que sea compatible con
las nuevas versiones."
El valor de esta formulación es que obliga a diagnosticar error por error. Sin la instrucción de identificar el origen, la tentación para un agente (al igual que para un desarrollador al final del día) es añadir any hasta que el compilador se calle, lo que convierte veintitrés errores visibles en veintitrés errores futuros.
Patrones de depuración eficaces
El material que proporcionas condiciona todo lo demás. Cada tipo de síntoma requiere incluir pruebas específicas; omitirlas es como pedir un diagnóstico sin exploración.
| Síntoma | Instrucción para Codex |
|---|---|
| Prueba fallida | Proporciona el mensaje de error completo + el archivo de prueba |
| Error de tipo | Proporciona la salida de tsc --noEmit |
| Error en tiempo de ejecución | Proporciona la traza de la pila + pasos para reproducir |
| Comportamiento incorrecto | Describe el resultado esperado frente al observado |
| Problema de rendimiento | Proporciona métricas (tiempo de respuesta, consultas lentas) |
Previene errores futuros
Un error corregido solo está medio gestionado si nada impide que vuelva a aparecer en otro lugar. Por tanto, sigue sistemáticamente la corrección con una tarea de consolidación, formulada a partir de lo que acabas de aprender.
"El error provenía de un userId nulo no comprobado. Añade
guardas de tipo en todas las funciones de src/services/ que
reciban un userId. Añade también una prueba de regresión
para este caso."
Esta segunda tarea generaliza la lección donde la corrección permanecía local: las guardas cubren todos los servicios y la prueba de regresión asegura que este caso concreto siga monitorizado después de que abandones el proyecto. Este es el movimiento que distingue a un equipo que corrige errores de un equipo que reduce su acumulación de incidencias.
Puntos clave
- Proporciona a Codex el máximo contexto: mensajes de error, trazas de la pila, registros
- Codex rastrea el flujo de datos para encontrar la causa raíz
- Verifica su corrección volviendo a ejecutar las pruebas automáticamente
- Tras corregir, solicita protecciones y pruebas de regresión
- Cuanto más precisas sean tus instrucciones, más rápida será la depuración