Reglas de Cursor: cómo mantener la IA alineada con tu base de código

Abres un chat nuevo en Cursor y pegas el mismo bloque de instrucciones de siempre. Tu stack, tus convenciones de nombres y la estructura de carpetas que la IA sigue interpretando mal. Luego genera una clase de 40 líneas con tres capas de abstracción para algo que necesitaba una simple función.

Toca despertar de esta pesadilla. Las reglas de Cursor son archivos de proyecto que hacen innecesario pegar instrucciones. Escribe tus convenciones una vez y el resultado de la IA se ajustará a tu base de código en lugar de llevarte la contraria.

Este tutorial crea un conjunto de archivos de reglas .mdc para un proyecto web en Python con FastAPI y pytest, abarcando contexto del proyecto, simplicidad del código y formato de errores de la API. Si eres nuevo en Cursor, te recomiendo hacer primero nuestro curso Software Development with Cursor, luego abre un proyecto y sigue los pasos.

¿Qué son las reglas de Cursor?

Las reglas de Cursor son archivos markdown con frontmatter específico de MDC que viven en tu proyecto en .cursor/rules/. Antes de que tu prompt llegue al modelo, Cursor comprueba qué reglas coinciden y antepone su contenido a la ventana de contexto. Tus instrucciones entran primero, siempre.

Cada archivo .mdc tiene tres campos de frontmatter que controlan su activación: description, globs y alwaysApply. Una regla puede activarse en cada conversación o solo cuando hay ciertos archivos abiertos. Una tercera opción, Apply Intelligently, permite que el agente lea la descripción y decida por sí mismo si la regla es relevante. En la siguiente sección verás cada tipo en la práctica.

Cursor admite cuatro categorías de reglas:

Las reglas de proyecto sustituyeron al antiguo archivo .cursorrules, un único archivo en la raíz sin ámbito ni metadatos, al dividir las reglas en varios archivos .mdc con frontmatter.

AGENTS.md es la alternativa más simple para proyectos que no necesitan delimitar con globs. Es markdown plano reconocido por herramientas de codificación con IA más allá de Cursor, y los archivos más profundos en subdirectorios tienen prioridad sobre los de niveles superiores.

Puedes aprender más sobre cómo los flujos de trabajo basados en agentes se conectan con tu proceso de desarrollo en nuestro itinerario de habilidades AI Agent Fundamentals.

Creación y configuración de reglas de proyecto en Cursor

El resto de este tutorial construye archivos de reglas para un proyecto FastAPI con pytest. Los patrones se pueden aplicar a cualquier stack.

Configurar el directorio y los archivos de reglas

Crea un directorio .cursor/rules/ en la raíz de tu proyecto. Cada archivo .mdc que coloques aquí se convierte en una regla que Cursor detecta al instante, sin necesidad de reiniciar.

El primer archivo de regla, project-context.mdc, da a la IA conciencia persistente de tu stack y la organización de carpetas:

---
description: ""
alwaysApply: true
globs:
---
 
# Project Context
 
This is a FastAPI web application with pytest for testing.
 
## Tech Stack
- Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0
- pytest with pytest-asyncio for async test support
- Alembic for database migrations
 
## Project Structure
- app/main.py: FastAPI application entry point
- app/routers/: API route handlers
- app/models/: SQLAlchemy models
- app/schemas/: Pydantic request/response schemas
- tests/: pytest test files mirroring app/ structure
 
## Patterns
- All endpoints are async
- Use dependency injection for database sessions
- Response models are always Pydantic schemas, not raw dicts

Escribir /create-rule en un chat con el agente es otra vía: Cursor te redacta una a través de un panel de chat.

El frontmatter alwaysApply: true significa que esta regla se carga en todas las conversaciones. Nombra los archivos en kebab-case por temática (project-context.mdc, simplicity.mdc, error-responses.mdc) y mantén cada uno por debajo de las 500 líneas. Un archivo de reglas inflado se come el espacio de la ventana de contexto que necesitas para tu código y tus prompts. Haz commit del directorio .cursor/rules/ en git.

Configurar los metadatos de las reglas para un acierto preciso

La regla project-context.mdc anterior usa alwaysApply: true, el modo más simple: se carga en todas las conversaciones sin importar en qué archivos estés trabajando. Es lo adecuado para el contexto global del proyecto.

Algunas reglas solo aplican a partes concretas del código. Configura alwaysApply: false y añade patrones glob como lista separada por comas para acotarlas. Una regla con globs: app/routers/**/*.py se activa solo cuando aparecen en contexto archivos coincidentes (aquí: archivos Python en app/routers/ o subcarpetas), manteniendo las convenciones de API fuera de chats no relacionados.

Apply Intelligently prescinde de patrones de archivo. Dejas globs vacío y escribes una description detallada; el agente decide si la regla es relevante para la conversación actual. La calidad de la descripción importa: "Error handling rules" es demasiado vaga para que el agente la aplique con fiabilidad, pero "Conventions for FastAPI error responses including HTTP status codes, error body structure, and exception handler patterns" tiene señales claras.

Las reglas sin globs, sin una descripción útil y con alwaysApply: false pasan a ser solo manuales: se cargan cuando escribes @rule-name en el chat. Son útiles como material de referencia que llamas bajo demanda.

Redactar el contenido de las reglas y sus restricciones

Las reglas escritas con lenguaje blando ("intenta mantener las funciones pequeñas", "prefiere endpoints async") le dan permiso a la IA para ignorarlas. Escribe mandatos: "Las funciones deben tener menos de 30 líneas. Todos los endpoints deben ser async".

En la introducción se mencionaba que la IA generaba una clase de 40 líneas con tres capas de abstracción. La regla que evita ese comportamiento es simplicity.mdc:

---
description: ""
alwaysApply: true
globs:
---
 
# Code Simplicity
 
Write the simplest code that solves the problem. Every abstraction must earn its place.
 
## Constraints
- No base classes with one child class
- No interfaces or abstract classes with one implementation
- No factory or strategy patterns when an if statement works
- No wrapper functions that just call another function
- No configurable parameters that nothing passes
- No "just in case" error handling for impossible conditions
 
## When modifying existing code
- Match the patterns already in the codebase
- Do not refactor surrounding code unless asked
- Do not add type annotations to unchanged code
- Do not add docstrings to unchanged functions
 
## Code size
- Functions under 30 lines
- If a function needs a comment explaining what a block does, extract that block into a named function instead

La diferencia es inmediata. La IA deja de recurrir a clases base abstractas cuando solo hay una implementación y usa if cuando hay dos casos.

La tercera regla, error-responses.mdc, está delimitada por globs para activarse solo cuando trabajas con archivos de rutas de API:

---
description: "Standard error response format for all API endpoints"
alwaysApply: false
globs: app/routers/**/*.py
---
 
# API Error Responses
 
All error responses must follow this structure:
 
{
  "detail": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "field": "optional_field_name"
}
 
## Rules
- Never return raw exception messages to clients
- Use HTTPException with a detail dict matching the structure above
- 400 for validation errors, 404 for missing resources, 409 for conflicts
- Log the full traceback server-side before returning the sanitized response

Siempre que puedas, señala archivos existentes en tu base de código en lugar de copiar código dentro de las reglas. Una línea como «Consulta app/routers/users.py para la estructura canónica del endpoint» se mantiene actualizada a medida que el código evoluciona, mientras que un fragmento copiado se queda obsoleto en cuanto alguien refactoriza el original.

Probar y verificar la vinculación de reglas

Cursor no tiene un indicador integrado que muestre qué reglas están activas en una conversación. Lo verificas probando el comportamiento.

Abre un chat nuevo con el agente y escribe un prompt que debería activar una de tus reglas. Para error-responses.mdc, prueba: «Añade un endpoint DELETE para eliminar un usuario por ID en app/routers/users.py». Si el manejo de errores generado no se parece en nada a la estructura JSON de tu regla o se salta HTTPException con el diccionario detail, algo falla en la coincidencia.

Las reglas acotadas por globs necesitan un archivo coincidente referenciado en tu prompt o abierto en el editor. Si pruebas error-responses.mdc sin mencionar ningún archivo bajo app/routers/, la regla no se activa. 

Las reglas "Apply Intelligently" se basan en el tema: prueba un prompt relacionado con la descripción de la regla y luego otro que no lo esté, y compara las respuestas. El agente debería seguir la regla en el primero e ignorarla en el segundo.

Mantener tus reglas de Cursor efectivas

Unas reglas que funcionaban el mes pasado pueden confundir a la IA tras un refactor o un cambio de nombre de carpeta.

Solucionar fallos de coincidencia

La razón más común por la que una regla no se activa es la extensión del archivo: las reglas deben usar .mdc, y los archivos .md en .cursor/rules/ se ignoran silenciosamente.

Además:

• Globs demasiado amplios como **/*.py adjuntan la regla a todos los archivos Python del proyecto. Restringe a app/routers/**/*.py o tests/**/*.py para que la regla solo se ejecute donde corresponde.

• Notarás que las reglas "Apply Intelligently" se saltan conversaciones cuando la descripción es demasiado genérica. Los ejemplos de buenas/malas descripciones de la sección de metadatos aplican aquí también.

• Las reglas en conflicto son más difíciles de detectar. Cuando dos reglas dan instrucciones contradictorias para los mismos archivos, la IA elige una (normalmente la que se cargó más tarde). Soluciona afinando el ámbito de los globs para que no se solapen o consolidando la guía relacionada en un solo archivo.

Un detalle a tener en cuenta: los cambios en archivos .mdc a veces desaparecen sin guardar. Si las ediciones no se conservan, cierra Cursor por completo, selecciona «Override» en la ventana emergente de cambios no guardados y vuelve a abrir.

Hacer que las reglas se mantengan a mitad de conversación

Una regla puede activarse bien al inicio de una conversación y aun así ignorarse cinco mensajes después. La causa es el sesgo de recencia en la ventana de contexto: a medida que crece la conversación, el modelo da prioridad a los mensajes recientes sobre las instrucciones inyectadas al principio. Es la queja más común en la comunidad de Cursor y no hay un ajuste que lo arregle.

La solución es reforzar. Cuando la salida empiece a desviarse de tus reglas, añade una línea como «sigue las reglas del proyecto para las respuestas de error» en tu siguiente prompt. Así devuelves la instrucción al contexto reciente del modelo. 

Para reglas que importan en cada respuesta (formato, nombres), las formulaciones más cortas y directas aguantan mejor en conversaciones largas que los párrafos detallados.

Las reglas con ejemplos de código también resisten mejor la deriva que las instrucciones solo en texto. En lugar de escribir «usa retornos tempranos para el manejo de errores», incluye un bloque breve de antes/después mostrando el patrón deseado. El modelo se ancla con mayor fiabilidad a código real que a descripciones en prosa, especialmente cuando el contexto crece.

Mantener y podar reglas

Revisa las reglas tras cualquier refactor importante, actualización de dependencias o reestructuración de carpetas. Una regla que hace referencia a APIs obsoletas o a archivos eliminados dará instrucciones erróneas a la IA. Los globs obsoletos fallan aún más en silencio: si renombras app/api/ a app/routers/, una regla acotada a la ruta antigua dejará de activarse sin avisar.

La poda va en la otra dirección. A medida que los modelos mejoran, adoptan convenciones comunes sin que se las indiques. Si la IA ya sigue la orientación de una regla sin pedírselo, elimina la regla y recupera esos tokens. Un conjunto de reglas sano se reduce con el tiempo, no solo crece.

Escalar reglas en entornos de equipo

Trata las reglas como código de aplicación. Los cambios pasan por pull requests y el equipo acuerda el patrón antes de que llegue a .cursor/rules/.

Para organizaciones con planes Business o Enterprise, Team Rules permite a los administradores aplicar reglas a todos los miembros desde el panel de Cursor. «Enable immediately» activa una regla por defecto permitiendo que los usuarios la desactiven. «Enforce this rule» elimina la posibilidad de excluirla, útil para convenciones no negociables como prácticas de seguridad y requisitos de cumplimiento.

Conclusión

Empieza con una o dos reglas para los patrones que más corriges. Si en cada sesión acabas editando el mismo tipo de salida de la IA (formato de error incorrecto, abstracciones innecesarias), ahí tienes una regla por escribir. Añade más cuando detectes errores recurrentes y elimina las que dejen de aportar.

Los archivos .mdc de este tutorial encajan con un proyecto FastAPI. Los tuyos se verán diferentes para un frontend en Next.js o una herramienta CLI en Rust, y esa es la idea: codifican las convenciones de tu equipo, no «mejores prácticas» genéricas. 

Si quieres profundizar con Cursor, echa un vistazo a nuestra guía de Cursor 2.0. Para compararlo con otros asistentes de codificación con IA, te recomiendo leer estos análisis comparativos:

• Cursor vs GitHub Copilot
• Claude Code vs Cursor
• Cline vs Cursor
• Cursor vs. Windsurf