Cursor Rules y AGENTS.md en el mismo repo: quién manda a quién

La documentación oficial de Cursor ya ni menciona .cursorrules en su página de reglas de contexto: esa ausencia, junto con las guías de terceros que sí lo etiquetan como legacy, apunta a que el debate de hace unos meses entre .cursorrules y el formato modular .mdc ya está zanjado a favor de este último, aunque no hay un anuncio explícito de deprecación que lo confirme con la misma autoridad. La pregunta que importa ahora es otra, y la mayoría de guías de Cursor Rules todavía no la responden: si tu equipo ya tiene un AGENTS.md porque además de Cursor usa Codex CLI, Claude Code o el modo agente de Copilot, ¿lo sustituyes por reglas de Cursor, los combinas, y quién gana cuando los dos dicen cosas distintas sobre el mismo archivo?

Un archivo .mdc en .cursor/rules/ es Markdown con frontmatter YAML (description, globs, alwaysApply) que Cursor inyecta de forma condicional según esos tres campos; un AGENTS.md es Markdown plano sin metadatos que se aplica de forma incondicional a todo el árbol de directorios donde vive, y que además leen otras herramientas aparte de Cursor. Esa diferencia de alcance, condicional contra incondicional, es la que decide cuál usar para cada regla, no una preferencia de formato.

Los tres formatos que Cursor lee hoy, y por qué dos siguen vivos

Cursor lee hoy tres formatos distintos, y los tres pueden coexistir en el mismo repositorio:

• .cursorrules (raíz, legacy). Sigue funcionando en la práctica, pero la documentación oficial actual de Cursor ya no lo menciona en ningún punto de su página de reglas de contexto: ni lo etiqueta como heredado ni explica cómo migrar desde él, simplemente ha dejado de aparecer. Quien sí lo documenta es una guía de terceros, no de Cursor: la describe como "una migración controlada, no una retirada de emergencia", con el archivo viejo funcionando mientras pruebas el nuevo, según la guía de migración de .cursorrules a Cursor Rules. Tómalo como guía de la comunidad, no como confirmación oficial: no tiene metadatos, así que tampoco podrías limitar una regla a un subconjunto de archivos con este formato aunque quisieras seguir usándolo.
• .cursor/rules/*.mdc (modular, el recomendado por Cursor para reglas propias de Cursor). Cada archivo tiene frontmatter y puede vivir en subdirectorios (.cursor/rules/frontend/react.mdc), así que puedes tener reglas distintas para backend y frontend en el mismo repo.
• AGENTS.md (raíz o subdirectorios, estándar abierto multi-herramienta). No es una invención de Cursor: es un estándar respaldado por la Agentic AI Foundation, bajo la Linux Foundation, con más de 60.000 repositorios que ya lo usan y con soporte nativo en Cursor, Codex, el modo agente de Copilot, Aider, Zed y otros, según la especificación oficial de AGENTS.md. Si tu equipo usa más de un asistente de código, este es el único de los tres formatos que no vas a tener que duplicar por herramienta.

El .mdc sin frontmatter no cuenta como regla: un archivo .md normal dentro de .cursor/rules/ se ignora, según confirma directamente la documentación oficial de Cursor sobre reglas de contexto. La extensión no es cosmética, es el mecanismo que activa el parser de frontmatter.

La tabla que decide cuál usar

Qué archivo usar depende de lo que necesitas, no de cuál escribiste la semana pasada; conviene decidirlo antes de escribir la primera regla:

AGENTS.md anidado: la pieza que la mayoría de tutoriales de 2025 no cubre

Hasta hace poco, la única forma de aplicar reglas distintas por directorio en Cursor era vía globs en un .mdc. Eso ya no es así: "el soporte de AGENTS.md anidado en subdirectorios ya está disponible. Puedes colocar archivos AGENTS.md en cualquier subdirectorio de tu proyecto, y se aplicarán automáticamente al trabajar con archivos de ese directorio o sus hijos", según la documentación oficial de reglas de Cursor. Las instrucciones de archivos anidados se combinan de forma jerárquica, con la instrucción más específica ganando sobre la más general.

La diferencia práctica con los globs de un .mdc es el criterio de activación: AGENTS.md anidado se activa por ubicación en el árbol de directorios (cualquier archivo bajo backend/), mientras que globs se activa por patrón de nombre de archivo independientemente de dónde esté (cualquier archivo *.test.ts, esté en backend/ o en frontend/). Son complementarios, no sustitutos: usa AGENTS.md anidado para "todo lo que vive aquí" y .mdc con globs para "todo lo que tiene esta forma, viva donde viva".

Estructura real combinando los dos mecanismos en un proyecto con backend Python y frontend TypeScript:

.
├── AGENTS.md                    # raíz: stack, convenciones globales, comandos de build/test
├── backend/
│   └── AGENTS.md                # anidado: convenciones específicas de Python/FastAPI
├── frontend/
│   └── AGENTS.md                # anidado: convenciones específicas de React/TypeScript
└── .cursor/
    └── rules/
        ├── testing.mdc          # globs: **/*.test.*, **/*.spec.* (cruza backend y frontend)
        └── api-design.mdc       # description, sin globs: Agent Requested para diseño de endpoints

Precedencia real cuando varias fuentes hablan a la vez

Con tres formatos activos a la vez, hace falta saber en qué orden gana cada uno cuando se contradicen. Para reglas de equipo, la documentación oficial de Cursor es explícita: "Team Rules → Project Rules → User Rules. Todas las reglas aplicables se combinan; las fuentes anteriores tienen prioridad cuando la guía entra en conflicto", según la documentación oficial de Cursor sobre gestión de reglas. Los planes Team y Enterprise permiten marcar una regla como obligatoria desde el panel de Cursor, de forma que los miembros del equipo no puedan desactivarla.

Dentro de un mismo repositorio, sin reglas de equipo de por medio, el orden que importa es otro: entre varios AGENTS.md anidados, gana el más específico (el de backend/ sobre el de la raíz para archivos dentro de backend/); entre un .mdc con alwaysApply: true y un AGENTS.md, ambos se inyectan y se combinan, no se sustituyen, así que una contradicción directa entre los dos no la resuelve Cursor por ti. La heurística que evita ese problema en la práctica: pon en AGENTS.md lo que es cierto para cualquier herramienta y en .mdc solo lo que depende de activación por patrón de archivo o de decisión del agente; si una misma frase podría ir en cualquiera de los dos, va en AGENTS.md, para no arriesgarte a mantenerla en dos sitios y que se desincronicen.

Migrar .cursorrules sin romper nada

Si todavía tienes un .cursorrules en la raíz y decides migrar, el orden que minimiza riesgo:

1. Divide el contenido actual por tema, no por tamaño: un bloque para stack y convenciones globales, otro por lenguaje o capa, otro para patrones específicos (testing, API design).
2. Decide para cada bloque si es "cierto para cualquier herramienta" (va a AGENTS.md) o "solo activable por patrón de archivo o decisión del agente de Cursor" (va a un .mdc con globs o description).
3. Crea los archivos nuevos y déjalos convivir con el .cursorrules viejo unos días; verifica en sesiones reales del agente que el comportamiento no cambió.
4. Borra .cursorrules solo cuando confirmes que ningún flujo dependía de él. No hay urgencia real: sigue soportado.

Un ejemplo de AGENTS.md de raíz que sustituye directamente al bloque "global" de un .cursorrules típico:

# AGENTS.md

## Stack
- Backend: Python 3.13, FastAPI, PostgreSQL 17
- Frontend: React 19, TypeScript 5.7
- Testing: pytest (backend), Vitest (frontend)

## Comandos
- Instalar: `pnpm install` (frontend), `uv sync` (backend)
- Tests: `pnpm test`, `uv run pytest`
- Lint: `pnpm lint:fix`

## Convenciones
- Commits: Conventional Commits
- Errores: early return con guard clauses, nunca try/except genérico
- Nunca usar `Any` como tipo en Python fuera de decoradores

Y el .mdc que cubre lo que AGENTS.md no puede: activación por patrón de archivo, no por directorio.

---
description:
globs: **/*.test.*, **/*.spec.*
alwaysApply: false
---

# Convenciones de testing

- Un assert lógico por test; si necesitas varios, son varios tests
- Nombra el test por el comportamiento, no por el método (`rechaza_email_invalido`, no `test_validate`)
- Mocks solo en los bordes del sistema (red, reloj, filesystem), nunca en la lógica de dominio

El coste de contexto de alwaysApply: la regla que se paga en cada petición

Nada de lo anterior importa si no se tiene en cuenta el coste real de alwaysApply: true: cada palabra de una regla marcada así se envía en cada petición al modelo, se use o no ese turno. Veinte reglas globales de tamaño moderado pueden sumar varios miles de tokens que se gastan antes de que el agente lea una sola línea de tu código, en cada mensaje de la sesión, no solo en el primero. La consecuencia no es solo de coste económico:

• Compresión de contexto. Si las reglas ocupan una fracción fija de la ventana, el resto del pipeline —tu código, el historial de la conversación, la salida de otras herramientas— dispone de menos espacio para el mismo trabajo.
• Pérdida del medio. Los modelos de lenguaje no tratan todas las posiciones del prompt por igual: atienden mejor a lo que está al principio y al final que a lo que queda en medio, un efecto documentado en la literatura de "lost in the middle" y consistente con lo que el informe Context Rot de Chroma mide para ventanas largas en general. Una regla alwaysApply que cae en mitad de un prompt ya cargado de contexto tiene más probabilidad de ser ignorada que una situada al principio.
• Sobrecarga de reglas. Cuantas más reglas evalúa el agente a la vez, más probable es que la calidad de la respuesta se degrade de forma medible, incluso si cada regla individual es correcta.

La solución no es escribir menos reglas en abstracto, es ser tacaño específicamente con alwaysApply: true: reserválo para lo que de verdad aplica al 100% de los archivos del repo (stack, convenciones de commits, reglas de estilo transversales) y deja que todo lo demás sea .mdc con globs o description, que solo entra en el prompt cuando toca. Un AGENTS.md de raíz tiene el mismo problema en versión más simple: se aplica siempre a todo el árbol, así que las mismas reglas de tacañería aplican ahí también, no solo en .mdc.

Ese coste no es estático: crece con cada regla que alguien añade y nadie retira. Auditar las reglas cada 2-4 semanas —no solo cuando algo falla— es la única forma de que el conjunto no se infle indefinidamente. Si el agente ya genera código correcto sin una regla concreta, porque el modelo mejoró o porque el patrón ya es estándar en la industria, esa regla ha dejado de pagar su propio coste de contexto y toca borrarla, no archivarla "por si acaso".

Cuándo Cursor Rules no es la respuesta

Si el asistente principal de tu equipo es Claude Code o Codex CLI y Cursor es una herramienta secundaria que solo usa una persona del equipo de forma esporádica, invertir tiempo en .mdc con globs finos tiene poco retorno: escribe un único AGENTS.md en la raíz, que van a leer todas las herramientas por igual, y no abras .cursor/rules/ hasta que de verdad necesites una regla que solo tenga sentido activada por tipo de archivo. Tampoco tiene sentido en un prototipo de vida corta o en un repo de un solo desarrollador sin convenciones que defender todavía: el coste de mantenimiento de varios archivos de reglas supera el beneficio si no hay nada que un agente pueda romper por desconocer contexto compartido.

Casos borde que conviene tener resueltos antes de que aparezcan en mitad de una sesión de trabajo:

• Un .mdc con description y globs a la vez: la documentación de Cursor no define un comportamiento único para esa combinación y distintas guías de la comunidad reportan que el agente evalúa más reglas de las necesarias en ese caso; la práctica más segura es no combinarlos nunca en el mismo archivo, y separar en dos si necesitas ambos criterios.
• Un submódulo git con su propio AGENTS.md heredado de otro repositorio: como la activación es por árbol de directorios, ese AGENTS.md del submódulo se sigue aplicando dentro de su propia carpeta aunque el repo padre tenga uno distinto en la raíz; si el submódulo pertenece a otro equipo con otras convenciones, ese archivo puede contradecir al de tu raíz sin que nadie lo note hasta que el agente genera código con el estilo equivocado justo ahí.
• .cursorrules y AGENTS.md coexistiendo en la misma raíz durante una migración a medias: ambos se inyectan, así que una frase distinta sobre lo mismo en cada uno produce instrucciones contradictorias en el mismo prompt; esto es exactamente el escenario que el paso 3 de migración de arriba está pensado para detectar antes de borrar el archivo viejo.