Debugging y Resolución de Errores con IA

El Error 500 que No Tenía Sentido

🔄 Repaso rápido: En la lección anterior, exploramos generación de código que realmente funciona. Ahora construyamos sobre esa base para cuando las cosas salen mal.

El mes pasado, un developer pasó seis horas con un bug. La API devolvía errores 500, pero solo los martes. Solo para usuarios en la UE. Solo cuando subían PDFs de más de 2MB.

Finalmente pegó todo el flujo del request en un asistente de IA y preguntó: “¿Por qué esto solo falla los martes para usuarios de la UE con PDFs grandes?”

La respuesta llegó en 30 segundos: el load balancer de la región UE tenía una configuración de timeout diferente, y el servicio de procesamiento de PDFs tenía un cron job que corría cada martes y consumía memoria extra, empujando el procesamiento de archivos grandes por encima del umbral de timeout.

Seis horas de trabajo detectivesco, o 30 segundos con el contexto correcto. Eso es lo que te enseña esta lección.

La Trifecta de Debugging

Toda sesión efectiva de debugging con IA necesita tres cosas:

1. El error (qué salió mal)

TypeError: Cannot read properties of undefined (reading 'map')
at UserList.render (UserList.tsx:24)
at renderWithHooks (react-dom.development.js:14985)

2. El código (dónde salió mal)

const UserList = ({ users }: Props) => {
  return (
    <ul>
      {users.map(user => (  // Línea 24
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
};

3. La expectativa (qué debería haber pasado)

Esperado: Renderizar una lista de usuarios de la respuesta API
Real: Se rompe con TypeError cuando el componente se monta

Si falta alguno, la IA tiene que adivinar. Incluye los tres y acertará el diagnóstico casi siempre.

Cinco Patrones de Debugging que Funcionan

Patrón 1: Análisis de Stack Trace

Pega el stack trace completo y pide un diagnóstico.

Aquí va un stack trace de nuestro servicio Node.js en
producción. El error pasa intermitentemente, en
aproximadamente el 5% de los requests.

[stack trace completo]

Archivos de código relevantes:
[pega los archivos mencionados en el stack trace]

¿Qué lo causa, y por qué es intermitente?

La IA puede trazar la ruta de ejecución, identificar la línea que falla y razonar sobre causas intermitentes (condiciones de carrera, agotamiento de recursos, timeouts de servicios externos).

Patrón 2: El Debug de “¿Qué Cambió?”

Algo que funcionaba ayer está roto hoy. Aquí es donde la IA brilla con análisis de diff.

Este endpoint funcionaba ayer y hoy falla con un Error de
Validación 422. Aquí va el git diff de todo lo que cambió
desde ayer:

[pega el git diff]

Y aquí va el error:
[pega el error]

¿Qué en este diff podría causar este error de validación?

Patrón 3: El Upgrade del Pato de Hule

La técnica clásica del pato de hule — explicar tu problema en voz alta — funciona aún mejor con IA. Escribe tu problema como si le explicaras a un colega:

Estoy intentando entender por qué nuestras conexiones
WebSocket se caen después de exactamente 60 segundos
de inactividad.

Lo que sé:
- El servidor WebSocket tiene un timeout de 120 segundos
- Nginx está enfrente
- El cliente envía un ping cada 30 segundos
- Pero las conexiones se caen a los 60 segundos

Mi config de Nginx:
[pega config]

Config del servidor WebSocket:
[pega config]

¿Qué me estoy perdiendo?

Muchas veces solo escribir esto te va a hacer click. Pero cuando no, la IA probablemente detectará que tu proxy_read_timeout de Nginx está en 60 segundos, sobreescribiendo el timeout del servidor WebSocket.

Patrón 4: Reproducir-y-Corregir

Cuando no puedes reproducir un bug, describe los síntomas y pide a la IA que ayude a crear una reproducción.

Patrón 5: Traducción de Mensajes de Error

Algunos mensajes de error son genuinamente crípticos. La IA destaca traduciéndolos:

Me sale este error y no tengo idea qué significa:

FATAL ERROR: Ineffective mark-compacts near heap limit
Allocation failed - JavaScript heap out of memory

Pasa durante nuestro proceso de build cuando procesamos
más de 500 archivos markdown. Nuestro script de build:
[pega config de build]

La IA traduce: tu proceso Node.js se queda sin memoria durante el build. Sugerirá aumentar el heap de Node.js con --max-old-space-size y probablemente identifique qué parte del build consume más memoria.

✅ Revisión Rápida: ¿Cuáles son los tres elementos de la trifecta de debugging que deberías incluir siempre?

Debugging Multi-Archivo

Los bugs reales rara vez viven en un solo archivo. Cuando el issue abarca múltiples archivos, estructura tu solicitud mostrando el flujo completo de datos:

Tengo un bug donde las preferencias del usuario no persisten
después de recargar la página. El save parece funcionar (sin
errores), pero las preferencias se resetean al refrescar.

El flujo:
1. El usuario actualiza preferencias en SettingsPanel.tsx
2. Que llama a PreferenceService.save()
3. Que llama al endpoint API en preferences.controller.ts
4. Que escribe a la base de datos vía PreferenceRepository.ts

[pega el código relevante de cada archivo]

La API retorna 200 con las preferencias actualizadas.
DevTools del browser muestra que el request tiene éxito.
Pero después de recargar, regresan las preferencias viejas.

¿En qué parte de esta cadena se están perdiendo los datos?

Al mostrar el flujo completo, la IA puede rastrear los datos a través de cada capa.

Cuando la IA Se Equivoca en Debugging

El debugging con IA no es perfecto. Cuidado con estas trampas:

La respuesta equivocada pero segura. La IA a veces da una explicación que suena plausible pero está completamente equivocada. Siempre verifica comparando el comportamiento real contra la explicación de la IA.

Sugerir síntomas, no causas. A veces la IA arregla el mensaje de error sin abordar la causa raíz. Si el fix es “agrega un null check,” pregunta: “¿Pero por qué este valor es null para empezar?”

Ignorar tu entorno. La IA podría sugerir fixes para una versión diferente de una librería o un OS diferente. Siempre menciona tus versiones específicas.

Soluciones sobre-complicadas. Si la IA sugiere un fix de 50 líneas para lo que debería ser un bug simple, da un paso atrás. Pregunta: “¿Hay una explicación más simple para este error?”

Tu Template de Debugging

Aquí va un template que puedes reusar para cualquier sesión de debugging:

## Error
[pega mensaje de error y stack trace]

## Entorno
- Lenguaje/Runtime: [ej. Node.js 20.x, Python 3.12]
- Framework: [ej. Express 4.18, Django 5.0]
- OS: [si es relevante]
- Dependencias relevantes: [versiones de librerías clave]

## Código
[pega archivos/funciones relevantes]

## Comportamiento Esperado
[qué debería pasar]

## Comportamiento Real
[qué pasa realmente]

## Lo Que Ya Intenté
[lista pasos de debugging previos]

## Contexto Adicional
[patrones: ¿intermitente? ¿condiciones específicas?]

Llénalo antes de tu próxima sesión de debugging. Te sorprenderá lo rápido que la IA lo resuelve cuando tiene el contexto adecuado.

Conclusiones Clave

• Siempre proporciona la trifecta de debugging: error, código y comportamiento esperado
• Usa el patrón de debugging correcto para la situación (stack trace, diff, pato de hule, reproducción o traducción de errores)
• Para bugs multi-archivo, muestra el flujo completo de datos
• Verifica las explicaciones de la IA — no apliques fixes a ciegas
• Pregunta “¿por qué?” para llegar a causas raíz, no solo fixes de síntomas
• Construye un template de debugging reutilizable

Siguiente

En la Lección 4: Testing y Aseguramiento de Calidad, aprenderás a generar suites de tests con IA que cubren cases que nunca se te ocurrirían por tu cuenta.