Cursor Rules como contrato de ingeniería

Definir Cursor Rules es el paso que convierte tu PRD y tus specs en un contrato de ingeniería real: reglas claras que agentes y humanos usan para escribir código con criterios consistentes. Aquí verás cómo estructurarlas, qué scope darles y cómo complementarlas con un archivo agents.md que sirva de punto de entrada.

¿Qué son las Cursor Rules y por qué las necesitas?

Cuando ya tienes el PRD y los specs listos, falta un elemento crítico: las limitantes bajo las cuales cada agente puede trabajar. Sin esas reglas, cada prompt puede generar código con estilos, arquitecturas o convenciones distintas.

Cursor resuelve esto con un sistema de reglas que se carga automáticamente dentro del contexto de la conversación. La idea es que tanto tú como cualquier subagente lean lo mismo y produzcan resultados alineados.

¿Qué son las Cursor Rules? Son archivos .mdc dentro de .cursor/rules que definen convenciones de código, arquitectura y estilo. Cursor los inyecta al contexto del agente según su configuración de scope.

¿Cuáles son los cuatro tipos de reglas en Cursor?

La documentación oficial de Cursor distingue cuatro niveles, y entender cada uno te ayuda a decidir dónde escribir qué.

• Reglas por proyecto: viven en .cursor/rules y aplican solo a ese repositorio.
• Reglas por usuario: se instalan en tu máquina y aplican a todos tus proyectos.
• Reglas por team: cuando tu organización paga Cursor, define reglas comunes para todo el equipo.
• agents.md: archivo de entrada que los modelos LLM cargan primero al iniciar cualquier tarea.

En Claude Code ese archivo se llama cloud.md. Para el resto de modelos, el estándar es agents.md.

¿Cómo funciona el scope de una regla con always apply y globs?

Cada archivo .mdc acepta un encabezado con tres campos que deciden cuándo se carga la regla. Usar .mdc en lugar de Markdown plano es lo que habilita ese formatter.

El always apply define si la regla entra siempre al contexto. Los globs son patrones tipo regex que indican en qué archivos aplica. La description funciona como pista semántica para que el agente decida si cargarla.

• always apply: true sin globs: la regla se carga en cada prompt. Ideal para arquitectura y convenciones transversales.
• always apply: false con globs: se adjunta solo cuando el archivo activo coincide con el patrón, por ejemplo *.ts o *.tsx.
• always apply: false con descripción y sin globs: el agente lee la descripción y decide cargarla si hace match con la tarea.
• always apply: false sin descripción ni globs: solo se incluye si la mencionas con @.

¿Cuándo debo usar always apply true? Úsalo para reglas transversales como arquitectura, TypeScript base o estilo de agentes, donde necesitas que cada prompt las vea sin importar el archivo.

¿Cómo generar las reglas del proyecto con un prompt?

El flujo empieza en el modo Agent de Cursor, con el modelo Opus corriendo. El prompt le pide usar el PRD y toda la carpeta de specs como contexto, no un spec individual, para que el agente lea el proyecto completo.

La instrucción clave es: crear el contrato de ingeniería del proyecto como Cursor Rules en .cursor/rules, fácil de leer para humanos y agentes. A partir de ahí se listan las categorías del stack.

• Reglas de TypeScript, React y Vitest.
• Lógica de evaluación de feature flags.
• Estilos de CSS.
• Reglas de arquitectura transversales.

Un detalle importante del prompt: pedirle que antes de generar los archivos te muestre qué globs va a asignar a cada regla. Así validas el scope antes de escribir nada en disco.

¿Qué globs tienen sentido para cada categoría?

Cuando el agente devuelve la propuesta, revísala regla por regla. Por ejemplo, en la de arquitectura pone always apply: true sin globs, lo cual encaja porque cada prompt necesita ver esa regla.

En cambio, la regla de React frontend queda con always apply: false y globs limitados a .ts y .tsx. Eso también tiene sentido: si estás trabajando en documentación, no quieres que Cursor cargue reglas de componentes React.

¿Qué contiene un archivo de regla bien hecho?

Una vez confirmas los globs, el agente crea la carpeta .cursor/rules con los archivos .mdc. Al abrir la regla de frontend encuentras el encabezado con description, globs y always apply, seguido del cuerpo con las convenciones.

El tamaño importa. La documentación de Cursor recomienda que cada regla tenga menos de 500 líneas. Un archivo de 35 líneas como el generado para frontend pasa la validación sin problema y sigue siendo legible.

Tu trabajo aquí no termina con generar los archivos. Debes leer cada regla, contrastarla con lo que realmente quieres en el proyecto y ajustar lo que no encaje.

¿Qué debe llevar el archivo agents.md y qué no?

El agents.md es distinto: es Markdown plano, vive en la raíz del proyecto y funciona como el primer documento que cualquier agente lee. Se carga en toda conversación y en cada subagente, así que debe ser breve.

El prompt para generarlo pide una descripción corta del producto, el stack, la estructura del monorepo y cómo correr los tests. La instrucción explícita es: no repitas el detalle que ya está en cada regla, remítete a ellas.

¿Qué diferencia hay entre agents.md y las Cursor Rules? El agents.md es un punto de entrada corto que se carga siempre. Las rules son modulares y se cargan según scope. Uno da contexto general, las otras dan convenciones específicas.

¿Qué conviene quitar del agents.md generado?

Cuando revisas el archivo generado, hay bloques que sobran. Los comandos ya viven en tu package.json, y las reglas del proyecto ya las conoce Cursor por su system prompt.

• Mantén: título del proyecto, descripción corta, stack.
• Quita: lista de comandos duplicados del package.json.
• Quita: instrucciones sobre cómo leer las reglas, Cursor ya las tiene en su system prompt.
• Quita: flujo de trabajo detallado si ya vive en los specs.

Cada línea extra en agents.md es contexto que se carga en cada conversación. Menos es más.

Ahora te toca a ti: escribe las reglas de tu proyecto y define cómo quieres que cada subagente escriba el código. ¿Qué globs vas a usar tú para separar frontend, backend y tests? Cuéntamelo en los comentarios.