Cursor Rules: Configura el Agente para tu Codebase
Cursor Rules son archivos .mdc en .cursor/rules/ que inyectan contexto persistente en cada petición al modelo de IA. Definen las convenciones, la arquitectura y los anti-patrones de tu proyecto para que el agente genere código consistente. En esta guía aprenderás los 4 tipos de reglas, cómo estructurarlas para proyectos Python y TypeScript, y qué consideraciones de producción evitan el "token tax" que degrada la calidad de las respuestas.
El problema: tu agente no entiende tu proyecto
El agente de Cursor genera código que no sigue tus convenciones. Usa var en lugar de const, ignora tu estructura de carpetas, importa librerías que no están en tu stack. No es un fallo del modelo: es que no tiene contexto. Los LLMs no retienen memoria entre completions, y cada conversación nueva empieza desde cero.
Un agente de IA sin contexto de proyecto es como un desarrollador senior en su primer día: tiene las habilidades, pero no conoce tus convenciones ni tus decisiones de diseño. Las Cursor Rules son ese documento de onboarding que convierte al agente genérico en un miembro productivo del equipo.
¿Qué son las Cursor Rules?
Cursor Rules son archivos de configuración en formato Markdown con metadatos (extensión .mdc) que se incluyen automáticamente en el prompt del sistema de cada petición al modelo de IA en Cursor. Funcionan como instrucciones persistentes que el agente lee antes de procesar tu solicitud.
Cursor soporta dos formatos: el archivo único .cursorrules en la raíz del proyecto (legacy, en proceso de deprecación) y el directorio modular .cursor/rules/ con archivos .mdc independientes. A marzo de 2026, el formato modular es el recomendado y el único con soporte activo de nuevas funcionalidades.
Si todavía usas .cursorrules, la migración es directa: divide el contenido en archivos temáticos dentro de .cursor/rules/ y añade el frontmatter correspondiente a cada uno. Cursor dejará de leer el archivo legacy en una versión futura.
Los 4 tipos de Cursor Rules
Cada archivo .mdc tiene un frontmatter que determina cuándo se activa. No existe un campo "tipo" explícito en el archivo. El tipo se infiere de la combinación de tres campos: description, globs y alwaysApply.
| Tipo | Configuración | Cuándo se activa | Caso de uso |
|---|---|---|---|
| Always | alwaysApply: true |
En cada petición, sin excepción | Stack tecnológico, convenciones globales |
| Auto Attached | globs definidos |
Cuando un archivo coincide con el patrón glob | Reglas por tipo de archivo o directorio |
| Agent Requested | description presente, sin globs |
Cuando el agente decide que es relevante | Workflows específicos, patrones condicionales |
| Manual | Todos los campos vacíos o false | Solo con @nombre-regla en el chat |
Templates, checklists, referencias puntuales |
El frontmatter de un archivo .mdc tiene esta estructura:
---
description: Cuándo debe aplicarse esta regla
globs: src/**/*.py
alwaysApply: false
---Un detalle que la documentación oficial no aclara del todo: no combines globs y description en la misma regla. Si defines ambos, el agente tiene que evaluar más reglas de las necesarias, y la probabilidad de que ignore alguna sube.
Estructura de .cursor/rules/ en un proyecto real
La clave de una buena configuración es separar las reglas por contexto, no por tamaño. Un archivo core.mdc con 400 líneas es peor que cuatro archivos de 100 líneas cada uno, porque con el enfoque modular solo se cargan las reglas relevantes para cada petición.
Esta es la estructura que funciona en un proyecto full-stack con Python en backend y TypeScript en frontend:
.cursor/
└── rules/
├── core.mdc # Always: stack, convenciones globales
├── python-backend.mdc # Auto Attached: **/*.py
├── typescript-frontend.mdc # Auto Attached: **/*.tsx, **/*.ts
├── testing.mdc # Auto Attached: **/*.test.*, **/*.spec.*
├── api-design.mdc # Agent Requested: diseño de endpoints
└── migration-checklist.mdc # Manual: checklist de migracionesEjemplo: regla global (Always)
---
description:
globs:
alwaysApply: true
---
# Stack del proyecto
- Backend: Python 3.12, FastAPI 0.115, SQLAlchemy 2.0, PostgreSQL 16
- Frontend: React 19, TypeScript 5.7, Tailwind CSS 4
- Testing: pytest (backend), Vitest (frontend)
- Infraestructura: Docker, GitHub Actions CI/CD
# Convenciones
- Imports: stdlib, terceros, locales, separados por línea en blanco
- Nombres: snake_case en Python, camelCase en TypeScript
- Commits: Conventional Commits (feat, fix, chore, docs)
- Errores: early return con guard clauses, nunca try/except genérico
- NUNCA usar print() en producción, usar logging
- NUNCA usar Any como tipo en Python excepto en decoradoresEjemplo: regla para Python/FastAPI (Auto Attached)
---
description:
globs: **/*.py
alwaysApply: false
---
# Patrones Python/FastAPI
- Usar async def para endpoints, def para funciones puras
- Validación de entrada con Pydantic BaseModel, no dicts
- Inyección de dependencias para DB, auth y configuración
- Patrón RORO: recibir un objeto, devolver un objeto
- Status codes explícitos: 201 para creación, 404 para no encontrado
- Background tasks para operaciones no bloqueantes
# Anti-patrones (prohibidos)
- NO usar from fastapi import *
- NO definir lógica de negocio en el router, extraer a services/
- NO usar sesiones de DB sin context manager (with)
- NO retornar dicts crudos, usar response_modelEjemplo: regla Agent Requested
---
description: USE WHEN creating or modifying API endpoints, designing REST resources, or working with OpenAPI schemas
globs:
alwaysApply: false
---
# Diseño de API REST
- Recursos en plural: /users, /orders
- Versionado en URL: /api/v1/
- Paginación: cursor-based para listas grandes, offset para pequeñas
- Respuestas de error: {detail, code, field}
- Documentar endpoints con docstrings para OpenAPI automáticoFíjate en la description del último ejemplo: usa verbos en gerundio en inglés ("creating", "modifying", "designing") porque el agente procesa la descripción como señal semántica para decidir si aplica la regla. Una descripción vaga como "API rules" reduce la probabilidad de activación.
Genera Cursor Rules desde conversaciones
Si después de una sesión de pair programming con el agente has definido patrones que quieres reutilizar, no hace falta escribir el archivo .mdc a mano. Escribe /Generate Cursor Rules en el chat o pide "convierte esto en una regla", y Cursor creará el archivo con el frontmatter adecuado en .cursor/rules/.
También puedes usar el Command Palette (Cmd+Shift+P en Mac, Ctrl+Shift+P en Linux/Windows) y buscar "New Cursor Rule" para crear un archivo vacío con la estructura correcta. Esta generación automática es útil cuando descubres un patrón durante el desarrollo: en lugar de documentarlo después, captúralo en el momento.
Cursor Rules vs CLAUDE.md vs Copilot Instructions
Cada herramienta de coding con IA lee un archivo diferente para entender tu proyecto. El concepto es el mismo, un documento Markdown que configura el comportamiento del agente, pero el formato y las capacidades varían. Si usas más de una herramienta, como planteamos en la comparativa de Claude Code, Cursor y Copilot, necesitas entender las diferencias.
| Característica | Cursor Rules | CLAUDE.md | copilot-instructions.md |
|---|---|---|---|
| Herramienta | Cursor IDE | Claude Code (CLI) | GitHub Copilot |
| Formato | .mdc con frontmatter | Markdown + imports @path | Markdown + YAML frontmatter |
| Scope | Glob patterns por archivo | Jerárquico (recorre directorios) | Repo + path-scoped |
| Aplica a | Chat, Agent, edición | Cada sesión de CLI | Chat, code review, agent (no autocomplete) |
| Reglas modulares | .cursor/rules/*.mdc | .claude/rules/ con paths | .github/copilot-instructions/ con globs |
| Mejor para | IDE-first, control granular | Tareas agénticas profundas | Convenciones de equipo, onboarding |
La estrategia más práctica si usas múltiples herramientas: mantén un documento canónico de estándares y genera los formatos específicos desde él. Algunos equipos usan un pre-commit hook que sincroniza un archivo base a los tres formatos automáticamente. Si trabajas con Copilot, revisa cómo el equipo de VS Code usa Agent Mode para entender las diferencias de contexto entre herramientas.
En Producción
El "Token Tax" de las reglas
Cada palabra en tus reglas consume tokens del contexto. Si tienes 20 reglas globales con alwaysApply: true, podrías estar enviando 2.000 tokens extra en cada petición, antes de que el agente lea una sola línea de tu código. Las consecuencias son directas:
- Compresión de contexto: si las reglas ocupan el 25% de la ventana de contexto, el agente tiene un 25% menos de espacio para tu código fuente.
- Pérdida del medio: los modelos procesan mejor las instrucciones al principio y al final del prompt. Las reglas en posiciones intermedias tienen más probabilidad de ser ignoradas.
- Sobrecarga de reglas: cuando el agente evalúa demasiadas reglas simultáneamente, la calidad de las respuestas baja de forma medible.
La solución no es tener menos reglas, sino tener reglas más precisas. Usa alwaysApply: true solo para lo que aplica al 100% de los archivos. Todo lo demás debería ser Auto Attached o Agent Requested. La gestión del contexto en agentes IA es una de las áreas donde más impacto puedes tener en la calidad del output.
Reglas de equipo y versionado
Los archivos en .cursor/rules/ son versionables con Git. Haz commit de las reglas compartidas y añade las personales a .gitignore:
# .gitignore
.cursor/rules/personal.mdcEn planes Team/Enterprise de Cursor, las Team Rules se configuran desde el dashboard con la opción de forzar reglas que los miembros no pueden desactivar. Para equipos más pequeños, el versionado con Git es suficiente.
Auditoría periódica
Revisa tus reglas cada 2-4 semanas. Si el agente ya genera código correcto sin una regla específica (porque el modelo ha mejorado o porque el patrón es estándar), elimínala. Menos reglas, menos tokens, mejores respuestas. Reglas como "escribe código mantenible" o "sigue SOLID" son redundantes: los modelos actuales ya están entrenados en esos principios.
Errores Comunes y Depuración
Error: las reglas en .cursor/rules/ no se aplican.
Causa: asumir que todas las reglas se activan automáticamente. Solo las reglas con alwaysApply: true o con globs que coinciden se inyectan en el contexto.
Solución: verifica el frontmatter. Para reglas Agent Requested, asegúrate de que la description es específica y usa verbos de acción en inglés.
Error: la regla tiene description y globs a la vez y el agente la ignora.
Causa: desde Cursor 0.45+, combinar ambos campos deja la regla en estado ambiguo.
Solución: separa en dos archivos: uno con globs para activación por archivo, otro con description para activación por contexto.
Error: el agente sigue patrones antiguos después de actualizar las reglas.
Causa: el archivo .cursorrules legacy en la raíz puede sobreescribir tus cambios en .cursor/rules/.
Solución: elimina el archivo .cursorrules y migra todo el contenido al formato modular.
Error: la edición del frontmatter desde Cursor rompe la estructura del archivo.
Causa: el editor integrado de archivos .mdc tiene bugs conocidos con el parsing del frontmatter.
Solución: edita los archivos .mdc externamente o añade "workbench.editorAssociations": {"*.mdc": "default"} en la configuración de Cursor.
Preguntas Frecuentes
¿Cuántas Cursor Rules debería tener mi proyecto?
Entre 4 y 10 archivos .mdc es lo recomendado en la práctica. El criterio clave es que cada regla con alwaysApply: true consume tokens en cada petición. Mantén 1-2 reglas globales y el resto como Auto Attached o Agent Requested para minimizar el coste de contexto.
¿Puedo usar Cursor Rules y CLAUDE.md en el mismo proyecto?
Sí. Cada herramienta lee su propio archivo de configuración: .cursor/rules/ para Cursor, CLAUDE.md para Claude Code, .github/copilot-instructions.md para Copilot. No interfieren entre sí. Para mantener consistencia, algunos equipos sincronizan desde un documento base común con un pre-commit hook.
¿Las Cursor Rules funcionan con todos los modelos disponibles en Cursor?
Sí, pero la calidad de interpretación varía. Modelos con mayor capacidad de razonamiento (como Claude Sonnet 4.6 o GPT-4.1) aplican las reglas con más precisión que modelos ligeros. Si una regla se ignora de forma consistente, prueba con un modelo más capaz antes de reescribir la regla.
Las Cursor Rules son la diferencia entre un agente que genera código genérico y uno que entiende tu proyecto. El formato .mdc con frontmatter te da control granular sobre qué contexto se carga y cuándo, lo que evita desperdiciar tokens en instrucciones irrelevantes. La clave está en empezar con pocas reglas concretas, usar el tipo correcto para cada una y auditar periódicamente para eliminar las que ya no aportan valor.
Si usas varias herramientas de coding con IA, una estrategia de sincronización entre formatos evita duplicar trabajo. Para una comparativa detallada, revisa la guía de Claude Code vs Cursor vs Copilot en 2026.
¿Ya usas Cursor Rules en tu proyecto? ¿Qué patrones te han funcionado mejor? Cuéntamelo en Twitter @sergiomarquezp_. En el próximo post exploraremos cómo VS Code está evolucionando como hub unificado para múltiples agentes de coding.