Detectar y solucionar errores

A medida que los agentes de programación escriben más código, los ingenieros dedican más tiempo a revisar ese código y a localizar errores. Incluso con la ayuda de agentes de programación, conviene repasar los fundamentos de una depuración eficaz y buscar formas de acelerar el trabajo delegando partes de ese proceso en los agentes.

Fundamentos de la depuración

Una buena depuración sigue los mismos principios, tanto si la realiza una persona como un agente:

1. Crea una reproducción fiable. Si no puedes reproducir el error, no puedes verificar la solución. Anota los pasos, las entradas y las condiciones exactas que desencadenan el problema.
2. Reduce el problema a un caso mínimo. Elimina todo lo que no esté relacionado con el error. Cuanto más pequeña sea la reproducción, más fácil será encontrar la causa raíz.
3. Aísla las variables. Cambia una cosa a la vez. Si cambias tres cosas y el error desaparece, no sabes cuál de esos cambios lo solucionó.
4. Formula hipótesis específicas. Piensa en algunas posibles causas raíz. «El error probablemente está en el código de pago» es demasiado impreciso. «El error ocurre porque calculateTotal() no tiene en cuenta los descuentos negativos» es lo bastante específico como para ponerlo a prueba.
5. Instrumenta tu código. Añade registros en las entradas y salidas del código donde sospechas que está el problema. Compara los valores esperados con los que observas.
6. Evita regresiones con pruebas. Una vez que encuentres y soluciones el error, escribe una prueba que lo hubiera detectado. Así evitas que el mismo error vuelva a aparecer.

Dos enfoques para depurar

Resolver errores sencillos rápidamente

Para errores con mensajes claros o causas evidentes, el agente suele poder encontrar y solucionar el problema directamente. Pega el error, proporciona algo de contexto sobre cuándo ocurre y deja que el agente se encargue.

TypeError: Cannot read properties of undefined (reading 'profile')
at getProfile (src/services/UserService.ts:45)
at UserController.show (src/controllers/UserController.ts:23)

Esto funciona bien cuando la causa es visible en el mensaje de error. El agente puede leer la traza de pila, encontrar el código y aplicar una corrección. Sin embargo, no siempre funciona, y quizá debas adoptar un enfoque más sistemático para encontrar la causa raíz.

Modo de depuración: la evidencia primero

Para los errores más complejos, el Modo de depuración adopta un enfoque diferente. En lugar de intentar adivinar soluciones, primero recopila evidencia en tiempo de ejecución.

El Modo de depuración sigue cinco pasos que reflejan los fundamentos de la depuración:

1. Genera hipótesis sobre lo que podría estar fallando
2. Instrumenta tu código con registros específicos
3. Te pide que reproduzcas el error mientras recopila datos
4. Analiza los registros para identificar la causa raíz
5. Aplica una solución específica basándose en la evidencia recopilada

El Modo de depuración puede ayudarte a encontrar y solucionar tus errores más complejos. Parte de los fundamentos que vimos antes y enseña al agente a ser un depurador eficaz, automatizando la investigación que, de otro modo, harías manualmente.

Ejecuta varios modelos en paralelo

Para errores complejos, distintos modelos a veces detectan cosas diferentes. Cursor te permite ejecutar la misma instrucción de depuración en varios modelos simultáneamente. Cada agente trabaja de forma aislada, por lo que no interfieren entre sí.

El flujo de trabajo:

1. Redacta un resumen claro de depuración con los pasos para reproducir el problema y tus hipótesis
2. Selecciona varios modelos en el menú desplegable del agente
3. Envía la instrucción; cada modelo trabaja de forma independiente
4. Compara las soluciones propuestas por cada modelo
5. Quédate con el enfoque que tenga la evidencia más sólida

Cursor te sugerirá cuál considera que es la mejor solución, pero debes evaluar el razonamiento, no solo la solución final. Para confirmar aún más que la solución es correcta, puedes pedirle al modelo que verifique su trabajo.

Incorpora datos de tiempo de ejecución en el ciclo del agente

El agente puede detectar problemas de rendimiento y errores comunes solo leyendo el código. Pero cuanta más evidencia en tiempo de ejecución le proporciones, más a fondo podrá investigar.

Empieza con una pregunta

No siempre necesitas registros ni herramientas de perfilado para empezar a investigar. Hazle una pregunta directa al agente y analizará tu código para detectar problemas comunes.

En el ejemplo anterior, el agente detectó una consulta lenta al revisar el código. No hicieron falta registros ni herramientas de perfilado. Para algunos problemas de rendimiento, esto basta.

Proporciónale evidencia en tiempo de ejecución

Cuando el análisis de código por sí solo no basta, proporciona al agente datos reales. Pega en la conversación la salida de la terminal, registros de consultas u otros datos. El agente puede usar estos datos para encontrar la causa raíz con mayor eficacia.

Por ejemplo, si investigas una consulta lenta a la base de datos, puedes ejecutar EXPLAIN ANALYZE en una consulta lenta de Postgres, pegar la salida y el agente podrá rastrear el problema hasta tu esquema:

Seq Scan on orders  (cost=0.00..45892.00 rows=47 width=244) (actual time=0.423..1203.112 rows=47 loops=1)
Filter: (user_id = 'usr_abc123')
Rows Removed by Filter: 2341856
Planning Time: 0.089 ms
Execution Time: 1203.298 ms

El mismo patrón funciona con registros de la aplicación, datos de perfilado o salidas de creación y pruebas.

Usa el navegador para depurar el frontend

Para solucionar problemas de frontend, el navegador integrado de Cursor proporciona al agente acceso directo a tu aplicación web. Puede leer los registros de la consola, inspeccionar solicitudes de red y observar el DOM sin que tengas que copiar nada.

Pide al agente que abra una página, reproduzca un problema y revise la consola en busca de errores o la pestaña Red para detectar solicitudes lentas. El agente ve lo mismo que verías en DevTools y puede rastrear los problemas hasta tu código fuente.

Conecta herramientas de monitorización con MCP

Los servidores MCP aportan nuevas capacidades a tu agente y lo conectan con herramientas de observabilidad de producción. En lugar de pegar datos manualmente, el agente obtiene lo que necesita cuando lo necesita.

En el ejemplo anterior, el agente consulta Sentry mediante MCP y obtiene los detalles relevantes del error. Correlaciona el error con los registros, encuentra el código problemático y propone una solución, todo en la misma conversación.

Servidores MCP útiles para depurar:

• Sentry: Detalles de errores, trazas de pila y breadcrumbs
• Datadog: Registros de producción y trazas de APM
• Bases de datos: Consulta datos de producción para verificar hipótesis
• Issues de Linear o GitHub: Incorpora informes de errores y pasos de reproducción a la conversación

Puedes configurar flujos de trabajo en los que las alertas de monitorización de tu aplicación en producción inicien automáticamente investigaciones del agente. Si la tasa de errores se dispara, se crea un ticket en Linear y un agente empieza a diagnosticar el problema antes de que una persona siquiera lo revise. Esto puede reducir el tiempo necesario para resolver los errores reportados por los clientes, o incluso solucionar problemas antes de que los clientes los detecten.

Patrón de fallo habitual: aceptar soluciones que no entiendes

Si no entiendes la solución, no puedes validar si es correcta. El agente podría añadir una comprobación de valores nulos que haga desaparecer el error, pero la inconsistencia de datos subyacente seguirá ahí.

Cuando el agente proponga una solución, haz preguntas hasta entenderla. ¿Por qué ese valor es nulo? ¿Qué cambió para provocar esto? ¿Es esta la causa raíz o estamos ocultando el síntoma? Como vimos en fundamentos, los agentes pueden inventar explicaciones que parecen plausibles. Debes desarrollar tu propia comprensión y usar los datos de tu investigación para confirmar que el agente ha identificado la verdadera causa raíz.

Qué sigue

Ahora que comprendes la depuración y cómo los agentes de programación pueden acelerar tu investigación, debes asegurarte de que los cambios sean correctos y no introduzcan regresiones. En el próximo capítulo, aprenderás a revisar el código y probarlo sistemáticamente.