Cómo trabajar con agentes de programación en Cursor (plan, debug y revisión)

Escribes un prompt, recibes algo de vuelta, pasas diez minutos corrigiéndolo y repites. Bienvenido a la máquina tragaperras.

Es la sensación con la que se estanca casi todo el mundo que abre un editor con IA: el autocompletado va fino, el chat cumple, pero todo lo demás parece una moneda al aire. Y la tentación es echarle la culpa al modelo.

No es el modelo. Es el método.

La diferencia entre el que avanza y el que va corrigiendo cada respuesta no está en tener un prompt mágico. Está en entender cómo funciona el agente por debajo y en montar un puñado de barandillas para que se corrija solo. Eso es lo que vamos a ver hoy con Cursor como banco de pruebas, porque su forma de organizar el trabajo del agente se ha convertido en una de las más completas.

Esto es lo que te llevas de este artículo:

• Qué es el harness de un agente y por qué saberlo mejora tus prompts.
• Cómo usar los cuatro modos de Cursor (Ask, Plan, Agent, Debug) sin meterlo todo en el mismo cajón.
• El ciclo planificar → implementar → verificar → revisar que evita la corrección de diez minutos.
• Ejemplos de prompt y de código en TypeScript para cada fase.

Si vienes de comparar herramientas de terminal, esto es el otro lado del ecosistema. Para la foto completa tienes la comparativa de agentes de IA para programación en terminal y el repaso a la mejor IA para programar en 2026. Y si ya combinas varios agentes, la revisión cruzada entre dos de ellos es un capítulo aparte. Aquí no comparamos: nos metemos en el método.

Casi todo lo que viene está destilado del tutorial Cursor: coding agents tutorial (2026), un recorrido por cómo trabajar con agentes de programación dentro del editor. No es doctrina cerrada ni verdad revelada: es un flujo probado por gente que se dedica a esto, y encaja con lo que venimos defendiendo sobre planificar antes de improvisar. Lo que hago aquí es bajarlo a tierra con ejemplos de prompt y de código que puedas copiar hoy.

Curso gratis · paso a paso

El método de planificar antes de programar, de principio a fin

Este post te da el ciclo; el curso te lo hace recorrer entero. Un ciclo completo de Spec Driven Development con OpenSpec sobre un proyecto real y en modo asistido: acordar el qué antes del cómo, que es justo lo que te ahorra la corrección de diez minutos.

Entra en el curso gratis →

Qué es el harness que ejecuta al agente ¶

Un agente de programación no es solo el modelo. Vive dentro de lo que se llama un harness, que son tres cosas cocinándose a la vez.

Primero, las instrucciones: el prompt de sistema y las reglas que guían su comportamiento. Segundo, las herramientas que le das: editar ficheros, buscar en el código, ejecutar comandos en la terminal. Y tercero, el modelo que hace el trabajo, que en Cursor eliges entre varios modelos frontera.

La buena noticia es que no tienes que configurar nada de esto. Cursor se encarga. La noticia útil es otra: entender que existe te cambia la forma de pedir las cosas. Si sabes que el agente tiene una herramienta para buscar en tu código y otra para lanzar comandos, dejas de darle instrucciones como si fuera un chatbot ciego y empiezas a darle trabajo como a un compañero con manos.

Dentro de esas instrucciones caben también las skills, esos paquetes de conocimiento que convierten al agente en un especialista de tu dominio. Ya les dedicamos una guía completa de Agent Skills y una criba de las mejores skills para agentes de IA, así que aquí las damos por sabidas y nos centramos en el flujo de trabajo.

La intención lo es todo (y el prompt es donde vive) ¶

Puedes pedirle una funcionalidad con un prompt de una línea. A veces cuela. Pero el agente tendrá que adivinar el layout que querías, los componentes, el estilo. Y adivinar es justo lo que produce esas respuestas que están “casi pero no”.

No es una impresión tuya. Según el Stack Overflow Developer Survey 2025, el 66% de los desarrolladores cita como su mayor frustración precisamente eso: soluciones de IA que están cerca pero no del todo bien. Y el 45% dice que depurar código generado por IA le lleva más tiempo que haberlo escrito a mano.

Compara ese prompt vago con uno que referencia patrones que ya existen en tu código y le adjunta contexto real, como un log de error. La probabilidad de recibir algo de calidad se dispara.

Mira la diferencia en la práctica:

# Prompt pobre
Añade un sistema de descuentos al checkout.

# Prompt con intención
Añade descuentos al checkout. Sigue el patrón de `src/pricing/tax.ts`
para el cálculo, usa el tipo `Discount` que ya existe en `types/order.ts`
y devuelve el desglose en el mismo formato que `calculateTotal`.
No inventes utilidades nuevas si ya hay algo reutilizable.

El segundo prompt no es más largo por capricho. Le está diciendo al agente dónde mirar, qué reutilizar y qué formato respetar. Le estás dando intención. Y el agente se toma tus peticiones al pie de la letra: si no le das intención, usará su mejor criterio, que unas veces acierta y otras te llena el repositorio de deuda técnica.

💡 Si solo te llevas una cosa de aquí: cada minuto que inviertes en dar contexto al prompt te ahorra diez de corrección después. El prompt no es la orden, es el contrato.

El contexto es memoria de trabajo, y se llena ¶

A medida que trabajas, la conversación acumula contexto: tus mensajes, las llamadas a herramientas, el contenido de los ficheros que el agente lee. Es su memoria de trabajo. Potente, pero con límites.

Dos reglas prácticas que funcionan:

1. Empieza una conversación nueva para cada funcionalidad. Arrastrar el contexto de una tarea a otra ensucia la memoria y confunde al modelo.
2. Si ves que el agente empieza a equivocarse y a dar vueltas, abre chat nuevo. No insistas en el mismo hilo emborronado; casi siempre es más rápido resetear.

Esto no es maniático: la tasa de defectos post-merge sube entre un 7% y un 15% cuando los agentes de IA no tienen contexto completo del código (Panto, Vibe Coding Statistics). Un contexto limpio es una barandilla, no un lujo.

Los modelos recientes se apañan bien buscando el contexto que necesitan cuando les das buenas herramientas de búsqueda. Si sabes el fichero exacto, etiquétalo en el prompt. Si no, deja que el agente lo encuentre: para eso están las herramientas del harness.

Cuando la búsqueda es grande, Cursor puede lanzar subagentes en su propia ventana de contexto, separada de la conversación principal. Devuelven solo sus hallazgos, sin inflar el hilo. Es una de las mejores formas de mantener el contexto principal limpio y enfocado.

Entiende el código antes de tocarlo ¶

Uno de los errores que más se repiten: pedirle al agente que cambie código que todavía no entiendes. El agente, obediente, crea una utilidad nueva o un patrón nuevo cuando ya había código que podía reaprovechar. Resultado: dos formas de hacer lo mismo y un poco más de caos.

Antes de construir, construye tu mapa mental. Y aquí los agentes brillan, porque puedes describir lo que buscas en lenguaje natural en lugar de pelearte con expresiones regulares.

Por debajo, el agente combina dos formas de buscar:

• Coincidencia exacta con herramientas tipo grep, para encontrar el nombre exacto de una función o una variable. El agente te escribe la regex complicada sin que tú aprendas su sintaxis.
• Búsqueda semántica, para cuando no sabes la palabra exacta. Si preguntas “¿dónde gestionamos la autenticación?”, te encuentra el middleware aunque la palabra authentication no aparezca literal en ese fichero.

La mezcla de las dos es lo que da respuestas buenas, sobre todo en bases de código grandes. Y no configuras nada: Cursor indexa tu proyecto en segundo plano al arrancar.

Para un código heredado y desconocido, pide un diagrama. Un prompt tan simple como este te ahorra media mañana de arqueología:

Explícame cómo funciona el flujo de checkout antes de que toque nada.
¿Qué servicios intervienen? Genera un diagrama Mermaid del flujo de datos
y dime dónde se calcula el total del pedido.

Ese “antes de que toque nada” es la parte importante. Estás usando al agente para aprender, no para producir. Y aprender primero es lo que evita que le pidas cambios a ciegas.

Plan mode: planifica antes de que escriba una línea ¶

Plan Mode hace que el agente investigue tu código y escriba un plan revisable antes de tocar una sola línea. Es el corazón del método: en vez de lanzarlo a generar código directo, arrancas cada funcionalidad con un plan que puedes leer y corregir.

En Cursor pulsas Shift+Tab para entrar en Plan Mode. El agente investiga tu código, te hace preguntas para aclarar requisitos y produce un plan paso a paso en Markdown que puedes editar antes de generar nada. Cuando el plan te convence, pulsas build y empieza a construir.

Esto no es una manía de organización. Es exactamente la idea del Spec Driven Development aplicada dentro del editor: acuerdas el qué antes del cómo, y el plan se convierte en el contrato que el agente sigue. Invertir en planificar cambia los resultados, y no lo digo yo solo: en un mundo donde el 41% del código a nivel global ya sale de una IA (Second Talent, Vibe Coding Statistics 2026), planificar es lo que separa el prototipo del producto.

El truco que funciona es dejar el prompt inicial un poco vago a propósito, para negociar los requisitos con el modelo:

Vamos a añadir páginas dedicadas para cada modelo que soportamos en apps/docs.
Investiga primero cómo está montado el sitio y qué podemos reutilizar.

El agente lanza sus subagentes, entiende la estructura, y vuelve con preguntas: “¿qué modelos deben tener página?”. Tú respondes (“solo los no ocultos”), y de esa ida y vuelta sale un plan de calidad. Lees el plan, quitas los pasos demasiado ambiciosos para la primera iteración, te centras en lo esencial, y solo entonces le das a construir.

Cuándo usar cada modo de Cursor, sin meterlo todo en Agent:

Verifica sobre la marcha, no al final ¶

Con el plan en marcha y el código apareciendo, no esperes al final para comprobar. Verifica en caliente.

Si estás en una app web, dile al agente que arranque el servidor de desarrollo. Él entiende cómo lanzar tu aplicación, la abre en el navegador integrado y puedes comprobar los cambios al momento. Si algo peta al compilar, no traces el error a mano: copia el mensaje y devuélveselo.

Esta es la gran ventaja de trabajar con lenguajes tipados o con linters. Le pasas el error y el agente sabe arreglarlo:

[pega aquí el stack trace tal cual]
Arréglalo.

Y cuando el diseño está feo, una captura vale más que mil palabras. Le pegas el pantallazo y le dices “haz que estos badges se vean mejor, con iconos y colores acordes a nuestro sistema de diseño”. La imagen le da una señal mucho más rica que cualquier descripción. Ese ciclo de empezar con un plan e ir puliendo detalles a base de idas y vueltas es como se construye la mayoría de las cosas nuevas.

Debug mode: para los bugs que se resisten ¶

Los bugs con un error claro se arreglan pegando el mensaje y pidiendo que lo solucione. Punto. Pero hay bugs sistémicos donde eso no basta, y ahí conviene volver a los fundamentos, valga quien valga que depure, humano o agente:

1. Reproduce el fallo. Si no puedes reproducirlo, no podrás verificar que lo arreglaste.
2. Redúcelo al caso mínimo. Todo lo demás confunde, a ti y al agente.
3. Aísla lo que cambias. Si tocas tres cosas a la vez, no sabrás cuál era la culpable.
4. Ven con hipótesis concretas sobre la causa raíz. Te ayudará a llegar antes.
5. Instrumenta el código. Añade logs o usa un depurador para ver cómo fluyen los datos.
6. Previene regresiones con un test cuando encuentres y arregles el problema.

Debug Mode de Cursor sigue justo esos fundamentos. En lugar de pegar un stack trace, recoge evidencia en tiempo de ejecución: genera hipótesis, instrumenta tu código con logging dirigido, te pide que reproduzcas el bug, analiza los logs y hace un arreglo quirúrgico basado en lo que observó. Se estrenó en la versión 2.2 (diciembre de 2025, según el changelog de Cursor) y ha demostrado ser muy eficaz con los bugs más difíciles.

Un par de trucos que uso mucho. Puedes pedir a varios modelos que arreglen el mismo bug y comparar resultados: cada uno aborda el problema distinto y eliges el mejor. Y puedes conectar herramientas externas por MCP, como Sentry, para traer errores reales de producción al contexto del agente.

Pero el consejo grande es otro: entiende de verdad la solución propuesta. Si no la entiendes, no puedes validar si es correcta. Y aquí TypeScript te tiende una trampa habitual: el agente “resuelve” el tipo poniéndote un any.

// Lo que el agente propone para salir del paso
function applyDiscount(order: any, discount: any): number {
  return order.total - discount.value; // compila, pero no dice nada
}

Ese any compila y calla. No es la solución que quieres. Cuando el agente te proponga algo así, pregúntale hasta entenderlo del todo: “¿es esta la causa raíz o solo el síntoma?”, “¿hay casos que no hemos considerado?”. Los agentes a veces alucinan explicaciones plausibles que no arreglan el fondo. Desarrollar la convicción de que el código es correcto es cosa tuya.

⚠️ Que compile no significa que funcione. “Los tests pasan” tampoco. Significa que no se ha roto del todo. Es un listón demasiado bajo para dar por bueno un cambio.

Tu estándar no baja por la IA

Cómo revisar de verdad el código que escupe el agente

Verás métodos para revisar y verificar lo que genera un agente sin bajar el listón: skills, pruebas en navegador con Playwright, casos Gherkin y adversarial review entre modelos. La revisión cruzada de este post, llevada a fondo.

Ver el método entero →

Masterclass Web Reactiva Premium · métodos de revisión en directo

La revisión no baja el listón porque lo escriba una IA ¶

Tu estándar para lo que entra en main debe ser el mismo lo escriba una IA o lo escribas tú a mano. Los agentes producen mucho código, y con él pueden colar un bug o generar deuda técnica: un informe de Veracode de 2025 encontró que el código generado por IA introduce vulnerabilidades del OWASP Top 10 en el 45% de los casos (Veracode, 2025 GenAI Code Security Report). Ese código puede parecer correcto, seguir tus patrones, compilar y pasar los tests, y estar mal en algún rincón.

El orden que funciona antes de pedir a nadie que mire tu PR:

• Autorevisión primero. Pide al agente “revisa el código que acabamos de generar y busca problemas”. Encuentra cosas como cadenas sin traducir o lógica duplicada.
• Commits semánticos. Pídele que parta tus cambios en commits pequeños y con sentido. Un revisor humano lo agradece: se recorre la historia paso a paso.
• Revisión automática con IA. Antes de mandar el PR a tu equipo, otra pasada.

Para esa pasada automática, BugBot es el revisor de PRs de Cursor. Los datos son elocuentes: cuando salió de beta en julio de 2025 resolvía el 52% de los bugs que señalaba, y hoy roza el 80%, 15 puntos por encima del siguiente producto de revisión con IA (Cursor, “Bugbot learning”). Comenta los problemas inline en el PR y puede empujar el arreglo con una línea.

No dependas de un único par de ojos, ni humanos ni artificiales. Añadir una revisión cruzada con un modelo distinto al que escribió el código pilla cosas que el autor original no ve. Que revise el código un agente distinto del que lo parió no es paranoia, es higiene.

Y ya que estás, pide tests. Los agentes hacen mucho más accesible escribir cobertura: no solo generan el test de la nueva funcionalidad, también verifican que es correcto. Con buenos tests, das al agente margen para trabajar sin introducir regresiones.

Personaliza el agente con rules y skills ¶

Los agentes son listos sin tocar nada. Pero no conocen cómo le gusta a tu equipo escribir software ni el contexto de tu negocio. Ahí entra la personalización, y Cursor la organiza en dos capas que se parecen a onboardear a alguien nuevo.

Las rules son ficheros Markdown que el agente ve al inicio de cada conversación. Instrucciones siempre presentes. Viven en .cursor/rules/ y puedes acotarlas por patrones de fichero, para que solo se cargue lo relevante a lo que se está editando. Una buena regla es corta, específica y apunta a ejemplos de tu código:

# .cursor/rules/testing.md

- Usa Vitest para los tests unitarios
- Coloca el test junto al archivo: `user.ts` → `user.test.ts`
- No uses `any`: si no sabes el tipo, defínelo en `types/`
- Sigue el patrón de `src/pricing/tax.ts` para cálculos de dinero

La tentación es escribir reglas para todo. Resístela. Demasiadas reglas consumen contexto y confunden al agente. Manténlas mínimas y de calidad, compromételas en Git y que todo el equipo se beneficie.

Las skills son la otra capa: conocimiento especializado que se carga cuando hace falta, no siempre. El agente decide cuándo usarlas. En su forma básica son un fichero Markdown, pero pueden incluir scripts. Puedes montar una skill /pr que haga el commit, cree la rama y abra el pull request por ti. Rules, skills, servidores MCP y subagentes se empaquetan y se comparten con tu equipo o con la comunidad a través del marketplace de plugins.

Un último apunte: el agente puede usar casi cualquier CLI instalado en tu terminal. En vez de salir a GitHub a mirar por qué falló el CI, dile “comprueba por qué ha fallado el CI en este PR” y usará el CLI de GitHub para traerte la información.

Todo junto: de la tarea al merge ¶

Imagina que entras en un equipo con una plataforma de e-commerce y tu primera tarea es añadir códigos de descuento al checkout. El código te es desconocido.

Primero entiendes: le pides al agente que te explique el flujo de checkout, qué servicios intervienen y dónde se calcula el total, con preguntas de seguimiento para rellenar huecos. Luego planificas en Plan Mode: revisas el plan, recortas lo ambicioso, te centras en aplicar el código y mostrar el descuento en el resumen. Le das a construir.

Y aparece el bug clásico: un test falla porque el resultado cambia según el orden en que llegan los descuentos.

type Discount =
  | { kind: "percentage"; value: number } // value 0.1 = 10%
  | { kind: "fixed"; value: number };      // value en euros

// Bug: aplicar fijo→porcentaje da distinto que porcentaje→fijo
function applyDiscounts(total: number, discounts: Discount[]): number {
  return discounts.reduce((subtotal, d) => {
    if (d.kind === "percentage") return subtotal * (1 - d.value);
    return subtotal - d.value;
  }, total);
}

Es un bug perfecto para Debug Mode: reproduces, instrumentas, encuentras la causa raíz (el orden importa y no debería) y aplicas un arreglo dirigido, más un test que fije el comportamiento esperado para siempre. Abres el PR, dejas que la revisión con IA haga otra pasada, y cuando mergeas, apuntas lo aprendido en tu fichero de rules para que el próximo que toque descuentos parta con esa ventaja.

🔑 El ciclo es siempre el mismo: entender, planificar, verificar, revisar, y guardar el aprendizaje donde el equipo lo aproveche. Los detalles de la herramienta cambiarán; el ciclo no.

Lo que caduca y lo que no ¶

Las herramientas y los modelos mejoran a un ritmo que deja obsoleto cualquier detalle concreto en cuestión de semanas. Los nombres de los modos, los porcentajes de BugBot, los atajos: todo eso cambiará.

Lo que no caduca es la habilidad de fondo: saber trabajar con un agente. Entender, planificar, verificar, revisar. Es, cada vez más, una de las partes centrales de la ingeniería de software, y la razón por la que el 84% de los desarrolladores ya usa o planea usar herramientas de IA, frente al 76% del año anterior (Stack Overflow, Developer Survey 2025).

Así que coge esto y aplícalo. Abre tu proyecto de verdad, pulsa Shift+Tab y deja de jugar a la tragaperras.

¿A qué esperas para pedirle un plan antes del código?

Preguntas frecuentes ¶

¿Qué es el harness de un agente de programación?

El harness es el sistema que envuelve al modelo y le permite trabajar. Lo forman tres piezas: las instrucciones (prompt de sistema y reglas), las herramientas (editar ficheros, buscar en el código, ejecutar comandos) y el modelo elegido. En Cursor no tienes que configurarlo, pero entenderlo mejora tus prompts.

¿Para qué sirve el Plan Mode de Cursor?

Plan Mode hace que el agente investigue tu código y escriba un plan paso a paso revisable antes de editar nada. Pulsas Shift+Tab para activarlo, editas el plan y luego pulsas build. Es la forma de acordar el qué antes del cómo y evitar que el agente improvise.

¿En qué se diferencia Debug Mode de BugBot?

Son cosas distintas. Debug Mode es un modo dentro del editor que instrumenta tu código y te acompaña a reproducir un bug concreto que estás persiguiendo. BugBot es un revisor automático que actúa sobre pull requests, señala problemas y puede arreglarlos. Uno diagnostica un problema en vivo; el otro revisa diffs terminados.

¿Es fiable la revisión de código con IA?

Cada vez más, pero no la dejes sola. BugBot pasó de resolver el 52% de los bugs que señalaba cuando salió de beta a rozar el 80% en 2026 (Cursor). Aun así, la mejor práctica es sumar tu propia revisión, una revisión cruzada con un modelo distinto y tests, no delegar el criterio por completo.

¿Cómo evito que el agente pierda el contexto?

Empieza una conversación nueva para cada funcionalidad y abre otra en cuanto veas que el agente da vueltas o se equivoca. Para búsquedas grandes, deja que use subagentes: trabajan en su propia ventana de contexto y devuelven solo los hallazgos, sin inflar el hilo principal.

¿Qué diferencia hay entre rules y skills en Cursor?

Las rules se cargan siempre, al inicio de cada conversación, y sirven para convenciones y comandos que el agente debe conocer. Las skills se cargan solo cuando hacen falta y aportan conocimiento especializado o flujos de trabajo. Regla práctica: si algo se necesita siempre, va en rules; si solo a veces, va en una skill.

¿Por qué no debería aceptar un any en TypeScript del agente?

Porque any compila pero desactiva el chequeo de tipos: esconde la forma real de los datos y suele ser un parche, no la solución. Cuando el agente lo proponga, pídele el tipo correcto y pregúntale si ha atacado la causa raíz o solo el síntoma.

¿Cursor sirve para bases de código grandes?

Sí. Indexa tu proyecto en segundo plano y combina búsqueda exacta (tipo grep) con búsqueda semántica, lo que mejora mucho la localización de código en repos grandes. Los subagentes ayudan a explorar sin agotar el contexto de la conversación principal.

¿Necesito escribir tests si el agente ya genera código?

Sí, y el agente te lo pone fácil: puede generar los tests de una funcionalidad y verificar que son correctos. Los tests son lo que te da margen para dejar trabajar al agente sin miedo a regresiones, y lo que fija un bug para que no vuelva.

¿Puedo usar Cursor con mis herramientas de terminal?

Sí. El agente puede invocar casi cualquier CLI instalado: GitHub, Docker, AWS, Kubernetes. En lugar de salir a la web a mirar por qué falló el CI, le pides que lo compruebe y usa el CLI de GitHub para traerte la información.

Fuentes ¶

• Cursor, “Bugbot learning” (blog oficial)
• Cursor, “Debug Mode, Plan Mode Improvements” (changelog 2.2)
• Stack Overflow, “Developer Survey 2025”
• Second Talent, “Vibe Coding Statistics 2026”
• Cursor: coding agents tutorial (2026) (vídeo)
• Veracode, “2025 GenAI Code Security Report”
• Panto, “Vibe Coding Statistics”

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter