Debugging con IA: reproducir, dar evidencia y verificar la causa

¿Por qué la IA parchea síntomas?

Cuando un agente no puede ejecutar el comando que falla, se queda con la descripción del problema y tiende a proponer un arreglo plausible en el lugar donde parece estar el error. Así se ve bien, pero el error reaparece en otro punto. El problema no es la inteligencia de la herramienta, sino la falta de evidencia. La regla que sale de las guías consultadas es que no debe aceptarse ninguna reparación hasta que el fallo se pueda reproducir (Verdent, cómo arreglar bugs con un agente de código).

¿Qué evidencia dar?

La evidencia útil es concreta. Lo que más ayuda es:

Lo que no ayuda: “arregla el bug”. La IA tendrá que adivinar qué bug y qué significa “arreglado”.

El método en seis pasos

Una guía práctica de depuración con IA propone este flujo, que se puede seguir en cualquier herramienta (WebReference, AI-assisted debugging):

1. Reproduce el fallo. Anota los pasos y el resultado exacto.
2. Copia la evidencia. Traza, mensaje, prueba que falla.
3. Pide una hipótesis. La IA debe decir qué cree que causa el error y por qué, antes de editar.
4. Aplica un parche mínimo. Solo en los archivos que la hipótesis señala, y pide la lista de archivos antes de editar.
5. Vuelve a ejecutar el comando que falla. Un arreglo no está probado hasta que ese comando pasa.
6. Revisa el diff. Una persona lee el cambio antes de aceptarlo.

La guía de Verdent añade algo útil: convierte la reproducción en una prueba automatizada y elige el parche más pequeño que ataque la causa raíz. Así el fallo queda documentado y no regresa en el futuro.

Señales de un arreglo malo

Hay atajos que hacen pasar la prueba sin resolver nada:

• Silenciar la excepción con un try vacío.
• Debilitar la validación para que el caso ya no falle.
• Borrar o marcar como omitida la prueba que falla.
• Agregar reintentos sin explicar por qué el primer intento falla.
• Mezclar la corrección con refactorizaciones de otras partes del código.
• Corregir solo el lugar donde salta el error, sin revisar otros sitios que parten de la misma suposición equivocada.

Si el agente reporta “arreglado” sin decir la causa raíz, los archivos cambiados y las pruebas que corrió, pide ese reporte antes de aceptar. El mismo ritmo de cambios pequeños se describe en iterar por prompts.

¿Cómo darle a la IA una forma de verificar?

La documentación de Claude Code lo plantea así: si la IA no tiene una comprobación que pueda ejecutar, la persona que revisa se convierte en el ciclo de verificación y cada error espera a que ella lo vea. Una comprobación puede ser un conjunto de pruebas, el código de salida de una compilación, un linter, un script que compara la salida con un resultado esperado o, en una interfaz, una captura de pantalla comparada con el diseño. Con una señal así, el agente trabaja, ejecuta la comprobación, lee el resultado y repite hasta que pasa (Anthropic, Best practices for Claude Code). Si no tienes pruebas escritas, el equivalente mínimo es un caso concreto con entrada y resultado esperado, como el del ejemplo de abajo.

¿Qué no conviene delegar?

Los errores que dependen del tiempo, como las condiciones de carrera o los fallos que aparecen una vez de cada diez veces, requieren registros y perfiles antes que una conjetura. Los incidentes en producción y las vulnerabilidades de seguridad también deben estar liderados por una persona. La IA puede ayudar a resumir registros o a revisar una lista de verificación, pero no debería decidir el arreglo sola. Si el código es de otra persona y no lo entiendes, empieza por leer código sin saber programar. Los criterios generales están en cuándo no hacer vibe coding.

Verdent recomienda además un plan de reversión cuando el arreglo toca datos, migraciones, concurrencia, permisos o servicios externos, y empezar el trabajo del agente en una rama aislada y sin credenciales de producción. Si el cambio afecta el manejo de errores, los reintentos, las transacciones o la seguridad, una persona debe revisarlo aparte.

Ejemplo

Ejemplo ilustrativo: un formulario de contacto de un sitio falla solo cuando el campo de teléfono tiene espacios. El diseñador copia el mensaje de error y el caso exacto ("’+34 600 123 456’ falla, ‘+34600123456’ pasa"). Pide a la IA su hipótesis antes de tocar nada. La IA responde que la validación compara con una expresión que no admite espacios, y lista los dos archivos que tocaría. El diseñador acepta el cambio solo en la validación, vuelve a correr la prueba con ambos formatos y revisa el diff. No aceptó un try que oculta el error.

Cómo aplicarlo mañana

1. Guarda en tu proyecto una plantilla de reporte de error con cinco campos: qué hiciste, qué esperabas, qué pasó, el mensaje exacto y cómo se reproduce.
2. Cuando un agente te diga que “ya está”, pide el reporte completo: causa raíz, archivos cambiados, pruebas que corrió y lo que no pudo reproducir.
3. Antes de aceptar, vuelve a ejecutar el caso que falló con tus propios datos, no con los del agente.
4. Convierte cada error reproducido en una prueba automática. La próxima vez que alguien cambie esa parte, la prueba avisará antes que el usuario.

Este hábito cuesta minutos y evita volver a discutir el mismo error dentro de tres meses.

Errores comunes

• Pedir “arregla el bug” sin evidencia.
• Aceptar un arreglo que nadie reprodujo.
• Dejar que la IA refactorice mientras investiga.
• Dar varios bugs en un mismo prompt.
• Confiar en “ya está arreglado” sin volver a ejecutar la prueba.
• Delegar a la IA un incidente de producción o una vulnerabilidad sin revisión humana.

Fuentes

• WebReference, “AI-Assisted Debugging”: https://webreference.com/ai/building/ai-assisted-debugging/
• Verdent, “How to fix bugs with an AI coding agent”: https://www.verdent.ai/guides/answers/fix-bugs-ai-coding-agent
• Anthropic, “Best practices for Claude Code” (dar criterios de verificación y evidencia en lugar de confiar en “parece terminado”): https://code.claude.com/docs/en/best-practices