Los agentes de programación están cambiando cómo se desarrolla software.

Los modelos ahora pueden ejecutarse durante horas, completar refactorizaciones ambiciosas en múltiples archivos e iterar hasta que las pruebas se superen. Pero sacar el máximo partido de los agentes requiere entender cómo funcionan y desarrollar nuevos patrones.

Esta guía cubre técnicas para trabajar con el Agente de Cursor. Tanto si eres nuevo en la programación asistida por agentes como si quieres aprender cómo nuestro equipo utiliza Cursor, aquí veremos las mejores prácticas para programar con agentes.

#Comprender los arneses de agente

Un arnés de agente se basa en tres componentes:

1. Instrucciones: El prompt del sistema y las reglas que guían el comportamiento del agente
2. Herramientas: Edición de archivos, búsqueda en la base de código, ejecución en la terminal y más
3. Mensajes del usuario: Tus prompts y mensajes de seguimiento que dirigen el trabajo

El arnés de agente de Cursor orquesta estos componentes para cada modelo que admitimos. Ajustamos las instrucciones y las herramientas específicamente para cada modelo de vanguardia según evaluaciones internas y benchmarks externos.

El arnés es importante porque distintos modelos responden de manera diferente a los mismos prompts. Un modelo entrenado en gran medida en flujos de trabajo basados en shell podría preferir grep en lugar de una herramienta de búsqueda dedicada. Otro podría necesitar instrucciones explícitas para invocar herramientas de linter después de realizar ediciones. El agente de Cursor se encarga de esto por ti, de modo que, a medida que se lanzan nuevos modelos, puedas concentrarte en desarrollar software.

#Empieza por planificar

La mejora más importante que puedes hacer es planificar antes de programar.

Un estudio de la Universidad de Chicago encontró que los desarrolladores con experiencia tienen más probabilidades de planificar antes de generar código. Planificar obliga a pensar con claridad en lo que estás creando y le da al agente objetivos concretos con los que trabajar.

#Uso del Modo Plan

Pulsa Shift+Tab en el campo de entrada del Agente para activar o desactivar el Modo Plan. En lugar de escribir código de inmediato, el Agente:

1. Analiza tu base de código para encontrar archivos relevantes
2. Hace preguntas para aclarar tus requisitos
3. Crea un plan de implementación detallado con rutas de archivos y referencias de código
4. Espera tu aprobación antes de empezar a implementar

Los planes se abren como archivos Markdown que puedes editar directamente para eliminar pasos innecesarios, ajustar el enfoque o añadir contexto que el Agente haya pasado por alto.

Consejo: Haz clic en «Save to workspace» para guardar los planes en .cursor/plans/. Esto crea documentación para tu equipo, facilita retomar trabajo interrumpido y proporciona contexto para futuros agentes que trabajen en la misma funcionalidad.

No todas las tareas necesitan un plan detallado. Para cambios rápidos o tareas que ya has hecho muchas veces, puedes ir directamente al Agente.

#Empezar de cero a partir de un plan

A veces el agente genera algo que no coincide con lo que querías. En lugar de intentar arreglarlo mediante mensajes posteriores, vuelve al plan.

Revierte los cambios, ajusta el plan para que sea más específico sobre lo que necesitas y ejecútalo de nuevo. Esto suele ser más rápido que corregir un agente en curso y produce resultados más limpios.

#Administrar el contexto

A medida que te sientas más cómodo con que los agentes escriban código, tu trabajo consistirá en darle a cada agente el contexto que necesita para completar su tarea.

#Deja que el agente encuentre el contexto

No necesitas etiquetar manualmente cada archivo en tu prompt.

El agente de Cursor tiene potentes herramientas de búsqueda y obtiene contexto bajo demanda. Cuando preguntas por «el flujo de autenticación», el agente encuentra los archivos relevantes mediante grep y búsqueda semántica, incluso si tu prompt no contiene esas palabras exactas.

Manténlo simple: si sabes el archivo exacto, etiquétalo. Si no, el agente lo encontrará. Incluir archivos que no sean relevantes puede confundir al agente sobre qué es importante.

El agente de Cursor también tiene herramientas útiles, como @Branch, que te permiten darle contexto sobre en qué estás trabajando. «Revisa los cambios en esta rama» o «¿En qué estoy trabajando?» se convierten en formas naturales de orientar al agente en tu tarea actual.

#Cuándo empezar una nueva conversación

Una de las preguntas más comunes: ¿debo continuar esta conversación o empezar una nueva?

Empieza una nueva conversación cuando:

• Estés pasando a una tarea o funcionalidad diferente
• El agente parezca confundido o siga cometiendo los mismos errores
• Hayas terminado una unidad lógica de trabajo

Continúa la conversación cuando:

• Estés iterando sobre la misma funcionalidad
• El agente necesite contexto de mensajes anteriores de la conversación
• Estés depurando algo que el agente acaba de construir

Las conversaciones largas pueden hacer que el agente pierda el enfoque. Después de muchas interacciones y resúmenes, el contexto acumula ruido y el agente puede distraerse o cambiar a tareas no relacionadas. Si notas que la efectividad del agente disminuye, es momento de empezar una nueva conversación.

#Haz referencia a trabajos anteriores

Cuando inicies una nueva conversación, usa @Past Chats para hacer referencia a trabajos anteriores en lugar de copiar y pegar toda la conversación. El Agente puede leer selectivamente el historial del chat para incorporar solo el contexto que necesita.

Esto es más eficiente que duplicar conversaciones enteras.

#Extender el agente

Cursor ofrece dos formas principales de personalizar el comportamiento del agente: Reglas para el contexto estático que se aplica a cada conversación, y Habilidades para capacidades dinámicas que el agente puede usar cuando corresponda.

#Reglas: contexto estático para tu proyecto

Las reglas proporcionan instrucciones persistentes que definen cómo el agente trabaja con tu código. Piénsalas como contexto siempre disponible que el agente ve al inicio de cada conversación.

Crea reglas como archivos Markdown en .cursor/rules/:

# Commands

- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)

# Code style

- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure

# Workflow

- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns

Mantén las reglas centradas en lo esencial: los comandos que ejecutar, los patrones que seguir y referencias a ejemplos canónicos en tu base de código. Haz referencia a archivos en lugar de copiar su contenido; esto mantiene las reglas breves y evita que queden obsoletas a medida que el código cambia.

Qué evitar en las reglas:

• Copiar guías de estilo completas (usa un linter en su lugar)
• Documentar todos los comandos posibles (el agente conoce las herramientas comunes)
• Agregar instrucciones para casos límite o excepcionales que rara vez se aplican

Consejo: Empieza de forma sencilla. Agrega reglas solo cuando notes que el agente comete el mismo error repetidamente. No sobreoptimices antes de entender tus patrones.

Incluye tus reglas en Git para que todo tu equipo pueda beneficiarse de ellas. Cuando veas que el agente comete un error, actualiza la regla. Incluso puedes etiquetar a @cursor en un issue o PR de GitHub para que el agente actualice la regla por ti.

#Habilidades: Capacidades dinámicas y flujos de trabajo

Habilidades del Agente amplían lo que los agentes pueden hacer. Las habilidades empaquetan conocimiento específico de un dominio, flujos de trabajo y scripts que los agentes pueden invocar cuando es relevante.

Las habilidades se definen en archivos SKILL.md y pueden incluir:

• Comandos personalizados: Flujos de trabajo reutilizables activados con / en la entrada del Agente
• Hooks: Scripts que se ejecutan antes o después de las acciones del agente
• Conocimiento del dominio: Instrucciones para tareas específicas que el agente puede incorporar bajo demanda

A diferencia de las Rules, que siempre se incluyen, las habilidades se cargan dinámicamente cuando el agente decide que son relevantes. Esto mantiene limpia tu ventana de contexto y, al mismo tiempo, le da al agente acceso a capacidades especializadas.

#Ejemplo: bucle de agente de larga duración

Un patrón muy potente es usar skills para crear agentes que se ejecutan durante períodos prolongados, iterando hasta que alcanzan un objetivo. A continuación se muestra cómo puedes crear un hook que mantiene a un agente trabajando hasta que todas las pruebas pasen.

Primero, configura el hook en .cursor/hooks.json:

{
  "version": 1,
  "hooks": {
    "stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
  }
}

El script de hook (.cursor/hooks/grind.ts) recibe el contexto a través de stdin y devuelve un followup_message para continuar el bucle:

import { readFileSync, existsSync } from "fs";

interface StopHookInput {
  conversation_id: string;
  status: "completed" | "aborted" | "error";
  loop_count: number;
}

const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;

if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
  console.log(JSON.stringify({}));
  process.exit(0);
}

const scratchpad = existsSync(".cursor/scratchpad.md")
  ? readFileSync(".cursor/scratchpad.md", "utf-8")
  : "";

if (scratchpad.includes("DONE")) {
  console.log(JSON.stringify({}));
} else {
  console.log(JSON.stringify({
    followup_message: `[Iteración ${input.loop_count + 1}/${MAX_ITERATIONS}] Continúa trabajando. Actualiza .cursor/scratchpad.md con DONE cuando hayas terminado.`
  }));
}

Este patrón es útil para:

• Ejecutar (y corregir) hasta que todas las pruebas se superen
• Iterar sobre la UI hasta que coincida con un diseño de maqueta
• Cualquier tarea orientada a objetivos donde el éxito sea verificable

Consejo: Las Skills con hooks pueden integrarse con herramientas de seguridad, administradores de secretos y plataformas de observabilidad. Consulta la documentación de hooks para ver las integraciones con socios.

Las Skills del Agente están disponibles actualmente solo en el canal de versiones Nightly. Abre la configuración de Cursor, selecciona Beta y luego establece tu canal de actualización en Nightly y reinicia.

Más allá de la programación, puedes conectar el agente con otras herramientas que usas a diario. MCP (Model Context Protocol) permite que el agente lea mensajes de Slack, investigue logs de Datadog, depure errores de Sentry, haga consultas a bases de datos y más.

#Incluir imágenes

El agente puede procesar imágenes directamente a partir de tus prompts. Pega capturas de pantalla, arrastra archivos de diseño o usa rutas de imágenes.

#Del diseño al código

Pega un mockup de diseño y pídele al agente que lo implemente. El agente ve la imagen y puede reproducir el layout, los colores y los espacios. También puedes usar el servidor MCP de Figma.

#Depuración visual

Haz una captura de pantalla de un estado de error o de una UI inesperada y pídele al agente que investigue. A menudo esto es más rápido que describir el problema con palabras.

El agente también puede controlar un navegador para hacer sus propias capturas de pantalla, probar aplicaciones y verificar cambios visuales. Consulta la documentación del navegador para más detalles.

#Flujos de trabajo comunes

Estos son patrones de uso del Agente que funcionan bien para distintos tipos de tareas.

#Desarrollo guiado por pruebas

El agente puede escribir código, ejecutar pruebas e iterar automáticamente:

1. Pídele al agente que escriba pruebas basadas en pares de entrada/salida esperados. Sé explícito en que estás haciendo TDD para que evite crear implementaciones simuladas de funcionalidad que aún no existe.
2. Indícale al agente que ejecute las pruebas y confirme que fallan. Dile explícitamente que no escriba código de implementación en esta etapa.
3. Haz commit de las pruebas cuando estés satisfecho con ellas.
4. Pídele al agente que escriba código que supere las pruebas, indicándole que no modifique las pruebas. Dile que siga iterando hasta que todas las pruebas pasen.
5. Haz commit de la implementación una vez que estés satisfecho con los cambios.

Los agentes funcionan mejor cuando tienen un objetivo claro contra el cual iterar. Las pruebas permiten que el agente haga cambios, evalúe los resultados y mejore de forma incremental hasta tener éxito.

#Comprensión de la base de código

Cuando te incorporas a una nueva base de código, usa el agente para aprender y explorar. Haz las mismas preguntas que le harías a un compañero de equipo:

• "¿Cómo funciona el logging en este proyecto?"
• "¿Cómo agrego un nuevo endpoint de API?"
• "¿Qué casos límite maneja CustomerOnboardingFlow?"
• "¿Por qué estamos llamando a setUser() en lugar de createUser() en la línea 1738?"

El agente utiliza tanto grep como búsqueda semántica para examinar la base de código y encontrar respuestas. Esta es una de las formas más rápidas de ponerte al día con un código que no conoces.

#Flujos de trabajo con Git

Los Agentes pueden buscar en el historial de Git, resolver conflictos de fusión y automatizar tu flujo de trabajo con Git.

Por ejemplo, un comando /pr que realiza un commit, hace push y abre una PR (pull request):

Create a pull request for the current changes.

1. Look at the staged and unstaged changes with `git diff`
2. Write a clear commit message based on what changed
3. Commit and push to the current branch
4. Use `gh pr create` to open a pull request with title/description
5. Return the PR URL when done

Los comandos son ideales para flujos de trabajo que ejecutas varias veces al día. Guárdalos como archivos Markdown en .cursor/commands/ y súbelos a Git para que todo tu equipo pueda usarlos.

Otros ejemplos de comandos que usamos:

• /fix-issue [number]: Obtén los detalles del issue con gh issue view, encuentra el código relevante, implementa una solución y abre una PR
• /review: Ejecuta linters, busca problemas comunes y resume qué podría necesitar atención
• /update-deps: Busca dependencias desactualizadas y actualízalas una por una, ejecutando las pruebas después de cada actualización

El Agente puede usar estos comandos de forma autónoma, así que puedes delegar flujos de trabajo de múltiples pasos con una sola invocación de /.

#Revisión de código

El código generado por IA requiere revisión, y Cursor ofrece varias opciones.

#Durante la generación

Observa al agente trabajar. La vista de diff muestra los cambios a medida que se producen. Si ves que el agente toma un rumbo equivocado, pulsa Escape para interrumpirlo y redirigirlo.

#Revisión del Agente

Cuando el Agente termine, haz clic en Review → Find Issues para iniciar una revisión específica. El Agente analiza los cambios propuestos línea por línea y detecta posibles problemas.

Para todos los cambios locales, abre la pestaña Control de código fuente y ejecuta Agent Review para compararlos con tu rama principal.

#Bugbot para pull requests

Sube tus cambios al sistema de control de versiones para obtener revisiones automáticas de tus pull requests (PR). Bugbot realiza análisis avanzados para detectar problemas de forma temprana y sugerir mejoras en cada PR.

#Diagramas de arquitectura

Para cambios significativos, pídele al agente que genere diagramas de arquitectura. Prueba con un prompt como: "Crea un diagrama Mermaid que muestre el flujo de datos de nuestro sistema de autenticación, incluidos los proveedores OAuth, la gestión de sesiones y la renovación de tokens". Estos diagramas son útiles para la documentación y pueden revelar problemas de arquitectura antes de la revisión de código.

#Ejecutar agentes en paralelo

Cursor facilita la ejecución de muchos agentes en paralelo sin que interfieran entre sí. Hemos comprobado que hacer que varios modelos aborden el mismo problema y elegir el mejor de ellos mejora significativamente la calidad del resultado final, especialmente en las tareas más complejas.

#Soporte nativo para worktrees

Cursor crea y gestiona automáticamente git worktrees para ejecutar agentes en paralelo. Cada agente se ejecuta en su propio worktree, con archivos y cambios aislados, de modo que los agentes pueden editar, compilar y probar código sin interferir unos con otros.

Para ejecutar un agente en un worktree, selecciona la opción de worktree en el menú desplegable del agente. Cuando el agente termine, haz clic en Apply para incorporar sus cambios a tu rama de trabajo.

#Ejecutar varios modelos a la vez

Un patrón muy eficaz es ejecutar el mismo prompt en varios modelos simultáneamente. Selecciona varios modelos en el menú desplegable, envía tu prompt y compara los resultados uno al lado del otro. Cursor también sugerirá cuál solución considera mejor.

Esto es especialmente útil para:

• Problemas difíciles en los que distintos modelos pueden adoptar enfoques diferentes
• Comparar la calidad del código entre familias de modelos
• Encontrar casos límite que un modelo podría pasar por alto

Al ejecutar muchos agentes en paralelo, configura las notificaciones y los sonidos para saber cuándo terminen.

#Delegar en agentes en la nube

Los agentes en la nube funcionan bien para tareas que de otro modo agregarías a una lista de pendientes:

• Correcciones de errores que surgieron mientras trabajabas en otra cosa
• Refactorizaciones de cambios de código recientes
• Generar pruebas para código existente
• Actualizaciones de documentación

Puedes cambiar entre agentes locales y en la nube según la tarea. Inicia agentes en la nube desde cursor.com/agents, el editor de Cursor o desde tu teléfono. Revisa las sesiones desde la web o el móvil cuando estés lejos de tu escritorio. Los agentes en la nube se ejecutan en sandboxes remotos, por lo que puedes cerrar tu portátil y revisar los resultados más tarde.

Así es como funcionan los agentes en la nube por dentro:

1. Describe la tarea y cualquier contexto relevante
2. El agente clona tu repo y crea una rama
3. Trabaja de forma autónoma y abre un pull request cuando termina
4. Recibes una notificación cuando termine (por Slack, correo electrónico o la interfaz web)
5. Revisa los cambios y fusiónalos cuando quieras

Consejo: Puedes activar agentes desde Slack con "@Cursor". Más información.

#Debug Mode para bugs complicados

Cuando las interacciones estándar con el agente no consiguen resolver un bug, Debug Mode ofrece un enfoque diferente.

En lugar de ir probando correcciones a ciegas, Debug Mode:

1. Genera múltiples hipótesis sobre qué podría estar fallando
2. Instrumenta tu código con mensajes de logging
3. Te pide que reproduzcas el bug mientras recopila datos en tiempo de ejecución
4. Analiza el comportamiento real para identificar la causa raíz
5. Aplica correcciones específicas basadas en la evidencia

Esto funciona mejor para:

• Bugs que puedes reproducir pero que no logras entender
• Condiciones de carrera y problemas de temporización
• Problemas de rendimiento y fugas de memoria
• Regresiones donde algo antes funcionaba

La clave es proporcionar un contexto detallado sobre cómo reproducir el problema. Cuanto más específico seas, más útil será la instrumentación que añada el agente.

#Desarrollar tu flujo de trabajo

Los desarrolladores que más provecho sacan de los agentes comparten algunos rasgos:

Escriben prompts específicos. La tasa de éxito del agente mejora significativamente con instrucciones precisas. Compara "add tests for auth.ts" con "Write a test case for auth.ts covering the logout edge case, using the patterns in __tests__/ and avoiding mocks."

Iteran sobre su configuración. Empieza de forma sencilla. Agrega reglas solo cuando notes que el agente comete el mismo error repetidamente. Agrega comandos solo después de haber definido un flujo de trabajo que quieras repetir. No sobreoptimices antes de entender tus propios patrones.

Revisan con cuidado. El código generado por IA puede parecer correcto y, sin embargo, estar sutilmente equivocado. Lee los diffs y revisa con atención. Cuanto más rápido trabaje el agente, más importante se vuelve tu proceso de revisión.

Proporcionan objetivos verificables. Los agentes no pueden arreglar lo que no conocen. Usa lenguajes tipados, configura linters y escribe pruebas. Dale al agente señales claras sobre si los cambios son correctos.

Tratan a los agentes como colaboradores capaces. Pide planes. Solicita explicaciones. Cuestiona los enfoques que no te convenzan.

Los agentes están mejorando rápidamente. Aunque los patrones evolucionarán con los modelos más nuevos, esperamos que esto te ayude a ser más productivo hoy al trabajar con agentes de programación.

Empieza con el agente de Cursor para probar estas técnicas.