Reglas de Cursor: cómo escribirlas para un proyecto real
Dónde van las reglas de Cursor, los cuatro tipos que existen, qué debe decir una regla útil, por qué el agente las ignora y cómo probarlas y compartirlas.
Read in English →
Las reglas de Cursor que funcionan son instrucciones cortas y concretas del proyecto, guardadas como archivos .mdc en .cursor/rules (o en un AGENTS.md normal), cada una sobre un solo tema. Solo unas pocas deben aplicarse a todas las peticiones; el resto se carga cuando el agente trabaja con los archivos a los que se refieren. Rinden más cuando dicen tu stack y tus comandos, lo que el agente nunca debe hacer sin preguntar y qué significa "terminado", y cuando lo que de verdad no puede pasar también está bloqueado por una configuración o una prueba.
En esta guía verás dónde viven las reglas, cómo funcionan los cuatro tipos, qué escribir en un proyecto real, por qué el agente las ignora y cómo comprobar que una regla hace su trabajo.
¿Dónde se guardan las reglas de Cursor?
Cursor toma instrucciones de varios lugares y las combina, así que conviene saber cuál usar para qué.
| Tipo | Dónde | Sirve para |
|---|---|---|
| Reglas del proyecto | .cursor/rules/*.mdc, dentro del repositorio | Todo lo propio del proyecto: stack, convenciones, límites |
| AGENTS.md | Un Markdown simple en la raíz, y si quieres otros en subcarpetas | Instrucciones que también quieres que lean otras herramientas |
| User Rules | En la configuración de Cursor, en Customize → Rules | Tus preferencias personales en todos tus proyectos |
| Team Rules | En el panel de Cursor, en los planes Team y Enterprise | Reglas de la empresa que un administrador puede imponer |
Hay dos detalles que confunden a mucha gente. Un archivo .md dentro de .cursor/rules se ignora: las reglas del proyecto tienen que ser .mdc. Y las User Rules se aplican al chat del agente, no a las ediciones en línea (Cmd/Ctrl+K). Si dos reglas chocan, mandan las del equipo, luego las del proyecto y al final las personales.
Si tu proyecto todavía tiene un único archivo .cursorrules en la raíz de una configuración vieja, pasa su contenido a .cursor/rules o a AGENTS.md, que es lo que describe la documentación actual de Cursor.
¿Cuáles son los cuatro tipos de regla?
Cada regla del proyecto tiene un pequeño encabezado que decide cuándo se carga. En el editor eliges el tipo en un menú; por debajo son tres campos:
---
description: Cómo consultamos Supabase y cambiamos el esquema de la base de datos
globs: supabase/**
alwaysApply: false
---- Always Apply (
alwaysApply: true): se envía en cada petición. Limítalo a una o dos reglas cortas. - Apply Intelligently: solo lleva
description. El agente la lee y decide si la regla viene al caso. - Apply to Specific Files: lleva un patrón en
globs. Se adjunta cuando un archivo que coincide está en la conversación. - Apply Manually: sin descripción ni globs. Solo se carga cuando la mencionas, por ejemplo
@checklist-de-lanzamiento.
La documentación de reglas de Cursor recomienda que cada regla tenga menos de 500 líneas y dividir las grandes en piezas pequeñas que se puedan combinar.
¿Qué deben decir las reglas en un proyecto real?
Una buena regla se lee como la inducción que le darías a alguien capaz en su primer día. Cinco temas concentran casi todo el valor.
El stack y los comandos
Di con qué está hecho el proyecto y cómo se ejecuta, se prueba y se compila, al pie de la letra. Los agentes pierden mucho tiempo adivinando si es npm run dev o pnpm dev.
Los límites
Enumera lo que no puede pasar sin tu aprobación: editar migraciones que ya se aplicaron, tocar archivos .env, agregar dependencias, cambiar el código de autenticación o de pagos, borrar archivos. Prevenir cada una de estas cosas es barato; deshacerlas después no tanto.
Las convenciones
Dónde van los componentes nuevos, cómo se nombran los archivos, qué función usar para llamar a la API, qué librería de interfaz ya está instalada. Así evitas que el agente cree una segunda función para formatear fechas al lado de la que ya existía.
Qué significa "terminado"
Dile qué tiene que hacer antes de anunciar que acabó: compilar, correr las pruebas y listar los archivos que cambió.
Las trampas conocidas
Anota los errores que ya pasaron una vez. "Toda tabla nueva necesita políticas de Row Level Security" vale más que una página de consejos de estilo.
Este es un ejemplo compacto de regla siempre activa para una app con Vite y Supabase:
---
description: Reglas base del proyecto
alwaysApply: true
---
- Stack: React + Vite + TypeScript, Supabase para auth y datos, Tailwind.
- Ejecutar: `npm run dev`. Antes de dar una tarea por terminada deben pasar `npm run build` y `npm test`.
- Nunca edites archivos existentes en supabase/migrations. Crea una migración nueva.
- Nunca leas ni cambies archivos .env. Pregúntame si hace falta una variable de entorno nueva.
- Pregunta antes de instalar paquetes de npm, borrar archivos o cambiar código de auth o de pagos.
- Reutiliza las funciones de src/lib antes de escribir otras nuevas.
- Al final de cada tarea, lista cada archivo que cambiaste y por qué.¿Por qué el agente ignora mis reglas?
Casi siempre por alguno de estos motivos:
- Son muy largas. Una regla de 900 líneas compite con lo que de verdad le estás pidiendo. El agente se queda con la idea general y suelta los detalles.
- Son muy vagas. "Escribe código limpio y seguro" no le da nada concreto. "Toda consulta a
invoicesdebe filtrar pororg_id", sí. - Se contradicen. Una regla pide usar la función compartida para llamadas HTTP y un ejemplo de otra usa
axios. El agente elige una. - Están desactualizadas. La regla todavía describe una carpeta que renombraste hace dos meses.
- Las usas como candado. Las reglas son contexto, no un bloqueo. Si algo nunca debe ocurrir, bloquéalo también con una configuración. Los modos de ejecución de Cursor incluyen File-Deletion Protection, y
.cursorignorealeja archivos de las herramientas de archivos del agente, aunque la documentación aclara que no impide el acceso desde la terminal ni desde MCP.
¿Cómo pruebo que una regla funciona?
- Abre un chat nuevo para que el contexto anterior no ayude.
- Pide una tarea que debería activar la regla, por ejemplo "agrega una columna
notesa invoices". - Mira qué hizo: ¿creó una migración nueva en lugar de editar una vieja?
- Si no, haz la regla más concreta o cambia su tipo, y vuelve a probar.
- Haz commit de la regla junto con el código, para que la próxima persona (o el próximo agente) la tenga.
Revisa tus reglas cada vez que cambies la estructura del proyecto, igual que actualizarías un README.
¿Puedo compartir las reglas con Claude Code, Copilot y otras herramientas?
En buena parte sí, con AGENTS.md. Cursor lo lee, GitHub Copilot lo toma como instrucciones para el agente y Claude Code lo lee cuando el proyecto no tiene CLAUDE.md. Si mantienes un CLAUDE.md, puede importar el archivo compartido con una línea como @AGENTS.md. Lo específico de cada herramienta, como las reglas por patrón de archivos de Cursor, déjalo en su propio formato.
Respuestas rápidas
¿Cuántas reglas necesita un proyecto? Empieza con una regla corta siempre activa y dos o tres por patrón de archivos para las zonas de más riesgo, como la base de datos y los pagos. Agrega más solo cuando un error se repita.
¿Las reglas tienen algún costo? Las que están siempre activas viajan con cada petición, así que ocupan parte del contexto cada vez. Otra razón para que sean cortas.
¿Las escribo en inglés? Escríbelas en el idioma en que piensas con más claridad. Lo importante es que sean concretas.
¿Las reglas reemplazan la revisión de código? No. Reducen los cambios malos; no atrapan los que igual se cuelan.
¿Quieres que alguien revise tu configuración?
Si el agente se pierde en un proyecto grande, lee cómo usar Cursor o Claude Code en un proyecto grande y cómo revisar código generado por IA. Si prefieres que alguien arme contigo reglas, pruebas y protecciones, en nuestra página de ayuda con proyectos de Cursor te contamos cómo trabajamos, y puedes escribirle a una persona aquí.
