¿Qué es el modo de depuración de Cursor? Cómo usarlo con ejemplos de prompts

Qué es realmente el modo de depuración

En diciembre de 2025, Cursor anunció un nuevo modo de agente llamado «Modo de depuración» (Debug Mode). Mientras que el modo de agente normal lee tu código y salta directamente a una propuesta de solución, el modo de depuración adopta un enfoque más detectivesco: primero recopila información en tiempo de ejecución y luego identifica la causa.

En concreto, funciona así:

1. Describe el error: facilítale los síntomas y los pasos de reproducción con el mayor detalle posible.
2. Genera hipótesis: el agente lee tu código base y elabora varias hipótesis sobre la causa.
3. Añade instrumentación de registros: inserta temporalmente código de registro en las ubicaciones sospechosas para poner a prueba cada hipótesis.
4. Reproduce el error: utilizas la aplicación para activar el error y el agente recopila los registros de ejecución.
5. Identifica y soluciona la causa: basándose en lo que ha recopilado (estado de las variables, ruta de ejecución, tiempos, etc.), propone una solución precisa.
6. Verifica la solución: reproduces el error una vez más; si ha desaparecido, el agente elimina automáticamente toda la instrumentación de registros que añadió; si no, añade más registros y sigue acotando el problema.

Gracias a este ciclo de «plantear hipótesis → instrumentar → reproducir → verificar», se dice que, en lugar de reescribir ciegamente cientos de líneas, normalmente terminas con una solución precisa de entre 2 y 3 líneas.

Cómo activarlo

Presiona Shift + Tab para alternar entre modos y selecciona «Debug». También puedes hacer clic directamente en el modo y cambiarlo.

Cuándo es la herramienta adecuada

La documentación oficial señala que el modo de depuración resulta idóneo para:

• Errores que puedes reproducir pero cuya causa principal no logras encontrar.
• Problemas de rendimiento y fugas de memoria.
• Problemas en los que la mera lectura del código no revela la causa.

Por otro lado, un error sencillo con un seguimiento de la pila evidente suele resolverse más rápido en el modo de agente normal. Una regla general realista: prueba primero tu enfoque de solución habitual y cámbiate al modo de depuración si eso no te da resultados.

¿Qué tan útil es en la práctica?

Los desarrolladores que utilizan el modo de depuración con regularidad destacan algunos aspectos clave:

• Funciona mediante registros de texto basados en HTTP en lugar de depender de funciones específicas del IDE (como LSP), por lo que funciona con prácticamente cualquier lenguaje de programación o entorno: en entornos locales, por supuesto, pero también a través de SSH remoto.
• Puedes instrumentar tanto el frontend como el backend al mismo tiempo para rastrear errores que abarcan ambas partes.
• Algunos desarrolladores afirman que conectar herramientas de observabilidad externas como Datadog o Sentry a través de MCP agudiza aún más los resultados.

Un desarrollador se topó con un error en el que la paginación en una integración de API externa devolvía siempre la primera página, sin importar qué. El modo de depuración formuló tres hipótesis —un nombre de campo JSON erróneo, un parámetro de consulta faltante, un token que no se pasaba correctamente— y añadió instrumentación de registros para probarlas. Tras unas cuantas rondas de reproducción y recopilación de registros, resultó que la API utilizaba en realidad un esquema de paginación diferente para los puntos de conexión de agregación en comparación con las consultas normales, y dichos puntos de conexión requerían que el token se pasara de una forma completamente distinta. Descubrir este tipo de discrepancia oculta en las especificaciones a partir de datos reales —el tipo de detalle que es fácil pasar por alto con solo leer el código— es donde realmente brilla esta función.

Ejemplos de prompts por escenario

El modo de depuración es más preciso cuanto más detalladamente describes la situación. Basándonos en los patrones de uso de la documentación oficial, aquí tienes algunos ejemplos de prompts por escenario.

Investigar a partir de un mensaje de error

I'm getting "Cannot read property id of undefined" on line 45
of UserService.getProfile. Find the root cause and fix it.

La línea donde el seguimiento de la pila muestra un error y el lugar donde reside la causa real suelen ser diferentes. El modo de depuración rastrea hacia atrás hasta «cualquier cosa que haya llamado a eso» para encontrar la causa real.

Acotar una causa a partir de registros

Processing for order ID 12345 is failing. The logs show:
inventory check passed → payment auth started → error here.
Find out exactly where after payment auth this is failing.

Proporciónale registros con marcas de tiempo y el modo de depuración cotejará el orden de los eventos a medida que investiga.

Investigar a partir de un ticket de soporte

A customer reported that exporting their data produced an empty file.
Pro plan, account ID 12345. Check the export feature's code and
work out why the file might come out empty.

Un «archivo vacío» por sí solo abarca muchas posibilidades: cero registros, un tiempo de espera agotado, un fallo silencioso, una descarga corrupta. El modo de depuración expone estas posibilidades y ayuda a averiguar qué comprobar primero.

Investigar una prueba intermitente (frágil)

This test is flaky — sometimes it passes, sometimes it fails.
Run it 20 times, collect the failures, and find the pattern.

Ejecutar una prueba a mano una y otra vez es tedioso, pero ese tipo de trabajo repetitivo es exactamente donde el modo de depuración demuestra su valía.

Investigar un problema de frontend

Combinado con las herramientas de navegador de Cursor, puede comprobar la pantalla renderizada real, los errores de la consola e incluso las peticiones de red.

The "Place order" button on the checkout page doesn't respond when clicked.
Take a screenshot, check the console errors, and find the cause.

Consejos para prevenir problemas recurrentes y construir conocimiento institucional

Para evitar volver a investigar el mismo tipo de problema una y otra vez, vale la pena mantener un archivo de reglas de depuración bajo .cursor/rules/. Anota los patrones de errores comunes, las consultas internas que utilizas para investigar, las pruebas frágiles conocidas, etc. El modo de depuración lo tendrá en cuenta en futuras investigaciones.

Una vez implementada una solución, también conviene pedirle al modo de chat (Ask mode) que explique por qué se produjo el error en primer lugar y si el mismo patrón podría estar al acecho en otra parte. Eso es lo que realmente previene las recurrencias.

Una cosa más: no es una función exclusiva del modo de depuración, pero sí un consejo común para conseguir que Cursor resuelva bien los errores en general. Muchas personas envían un primer prompt que solo pide un esquema del enfoque, sin hacer que escriba código todavía. Esto te permite detectar cualquier malentendido por parte del agente antes de que se escriba código, lo que reduce el trabajo repetido.

Limitaciones conocidas y aspectos a tener en cuenta

Hay informes de que muchas de estas limitaciones se pueden sortear, al menos parcialmente, escribiendo reglas en .cursor/rules/*.mdc, tales como «usa esta biblioteca específica» o «ejecuta el comando de análisis estático limpio después de cualquier cambio». En cuanto al problema de la CLI donde las entradas dejan de registrarse, presionar Escape suele solucionarlo, y preaprobar comandos de confianza en una lista de permitidos —o activar la aprobación automática— facilita evitarlo por completo.

Conclusión

El modo de depuración integra una disciplina de depuración fundamentada en el agente: en lugar de «leer el código y adivinar», consiste en «encontrar la causa a partir de datos recopilados ejecutando realmente la aplicación». Es sólido frente a errores misteriosos y persistentes, así como problemas de rendimiento, aunque para errores sencillos el modo de agente normal a veces resulta más rápido; por lo tanto, saber cuándo recurrir a cada uno es importante.

Si aún no lo has probado, la próxima vez que te encuentres con un error cuya causa no sea obvia, dale una oportunidad al modo de depuración a través de Shift+Tab.