Cursor Rules vs CLAUDE.md vs AGENTS.md: Probamos una Configuración en las Tres Herramientas (2026)

Cursor Rules vs CLAUDE.md vs AGENTS.md: Probamos una Configuración en las Tres Herramientas (2026)

La pregunta de cursor rules vs claude md trae una trampa incorporada: no son dos opciones entre las que eliges. Son dos archivos, leídos por dos herramientas distintas, que casualmente hacen el mismo trabajo. Coloca un CLAUDE.md en un proyecto de Cursor y Cursor lo ignora. Coloca un AGENTS.md en Claude Code y tampoco pasa nada. A nosotros también nos sorprendió. AGENTS.md ya está en más de 60.000 repositorios como estándar abierto, impulsado por la Agentic AI Foundation bajo la Linux Foundation, y aun así Claude Code no lo lee por sí solo. Aquí está el mapa de compatibilidad, probado en nuestro propio repositorio.

Puntos Clave

• Cursor lee .cursor/rules/*.mdc y AGENTS.md, no CLAUDE.md.
• Claude Code solo lee CLAUDE.md, no AGENTS.md de forma nativa.
• Para compartir un único archivo: enlaza AGENTS.md a CLAUDE.md con un symlink, o impórtalo con @AGENTS.md.
• Estandariza en AGENTS.md (estándar abierto, más de 60k repos) y añade overrides específicos por herramienta.

¿Qué Formato de Configuración Deberías Usar? La Decisión de 30 Segundos

Elige tu formato según la forma de tu equipo, no según la moda. Si usas una sola herramienta, usa su archivo nativo. Si usas dos o más, adopta AGENTS.md como fuente de verdad y añade overrides por herramienta solo donde una necesite algo que las demás no. Esa única regla resuelve la mayoría de la confusión.

¿Aún decidiendo qué asistente usar antes de preocuparte por su configuración? Empieza con nuestra guía sobre cómo elegir qué agente de codificación con IA usar, y luego vuelve para configurar el archivo.

El eje de decisión que importa es la portabilidad. Un archivo .cursor/rules es potente dentro de Cursor e inútil en cualquier otro sitio. Un AGENTS.md viaja contigo. Así que, salvo que estés atado a una sola herramienta para siempre, el archivo agnóstico a la herramienta es la apuesta más segura.

Qué Es Realmente Cada Formato (en 30 Segundos Cada Uno)

Estos tres archivos hacen una sola cosa: entregarle a una herramienta de codificación con IA las reglas, convenciones y trampas de tu proyecto antes de que escriba una línea. La diferencia está en quién los lee y cómo delimitan su alcance. Aquí va la versión corta. La guía completa de cada uno vive en su propio artículo.

Cursor Rules son archivos .mdc dentro de .cursor/rules/. Cursor admite cuatro tipos de regla (siempre activa, solicitada por el agente, con alcance por glob y mención manual con @), así que puedes vincular una regla solo a tus archivos *.tsx o solo a tus migraciones. Para el frontmatter, los globs y el presupuesto de tokens, lee nuestra guía sobre cómo escribir realmente archivos .cursor/rules.

CLAUDE.md es el archivo de memoria de Claude Code. Claude sube por el árbol de directorios desde tu carpeta de trabajo y concatena cada CLAUDE.md que encuentra. Es Markdown plano, sin frontmatter necesario. Para la estructura y las reglas que evitan que Claude lo ignore, revisa qué hace que un CLAUDE.md no sea ignorado por Claude.

AGENTS.md es el estándar abierto. Un único archivo Markdown plano en la raíz de tu repositorio, leído de forma nativa por Cursor, Codex, Copilot, Windsurf, Zed, Aider y decenas más. Está impulsado por la Agentic AI Foundation y ya vive en más de 60.000 proyectos.

Aquí va el replanteamiento que vale la pena recordar: AGENTS.md, CLAUDE.md y .cursor/rules no son competidores, son la misma instrucción, dirigida a distintos lectores.

Cursor Rules vs CLAUDE.md vs AGENTS.md: La Comparación Completa

La forma más rápida de ver la diferencia es lado a lado. La columna decisiva es la portabilidad: qué herramientas leen el archivo sin configuración adicional. AGENTS.md gana en alcance, Cursor Rules gana en precisión de delimitación, y CLAUDE.md gana para quien va todo dentro en Claude Code.

Fíjate en la fila de .cursorrules. Ese único archivo raíz todavía funciona en Cursor, pero desapareció de la documentación, así que trátalo como legado. Los proyectos nuevos deberían usar .cursor/rules/*.mdc o AGENTS.md.

¿Qué Herramienta Lee Qué Archivo? (Desmontando el Mito de AGENTS.md)

Aquí va el dato que la mitad de internet tiene mal: Claude Code no lee AGENTS.md de forma nativa, y Cursor no lee CLAUDE.md. Cursor lee .cursor/rules/*.mdc más AGENTS.md. Claude Code lee CLAUDE.md y nada más. No hay respaldo automático en ninguna dirección, y eso hace tropezar a los equipos que asumen que un solo archivo estándar lo cubre todo.

Esto se pregunta constantemente, así que vayamos al grano. Poner un AGENTS.md en un proyecto de Claude Code no hace nada por sí solo. Claude Code lee CLAUDE.md y solo CLAUDE.md. La documentación de memoria de Claude Code de Anthropic describe el comportamiento de carga de archivos sin mencionar AGENTS.md, la especificación de AGENTS.md enumera a Cursor y Codex entre los lectores nativos pero no a Claude Code, la documentación de reglas de Cursor confirma la división, y los issues de Claude Code en GitHub están llenos de desarrolladores que chocan justo con esta pared.

Entonces, ¿lee Cursor claude.md? No. ¿Lee Claude Code agents.md? No sin ayuda. Esa "ayuda" es toda la razón de ser de este artículo, y son dos comandos cortos que verás a continuación.

Cómo Funcionan la Precedencia y el Anidamiento, Lado a Lado

Cada herramienta resuelve los conflictos de forma distinta, y equivocarse aquí es la principal causa de "¿por qué se ignora mi regla?". Cursor combina reglas por prioridad de origen. Claude Code concatena por profundidad de directorio. AGENTS.md elige el archivo más cercano en el árbol. Una buena gestión de claude md empieza por saber en qué modelo mental estás.

En nuestra configuración, la conclusión práctica es simple: coloca las reglas generales arriba (raíz del repositorio) y las específicas abajo (dentro de una carpeta de paquete). Tanto para Claude Code como para AGENTS.md, el archivo más cercano a donde estás trabajando tiene prioridad, así que un packages/api/AGENTS.md sustituye al de la raíz para todo lo que hay dentro de esa carpeta. Cursor es la excepción, ya que resuelve por nivel de origen en lugar de por profundidad de carpeta.

Ejecutamos una Configuración en Cursor y Claude Code, Esto Cargó Realmente Cada Herramienta

Lo probamos en un repositorio real de un cliente de Techsy (un backend en Next.js 15) usando Cursor 3.7 (build del 17 de junio de 2026) y Claude Code v2.1.x (principios de julio de 2026). Un AGENTS.md, tres configuraciones de reparto, el mismo prompt abierto en ambas herramientas. Esto es exactamente lo que cargó cada una.

Empezamos con un archivo mínimo:

# AGENTS.md
- Package manager: pnpm, never npm.
- Tests: Vitest. Run `pnpm test` before any commit.
- DB access goes through `lib/db.ts` only, no inline SQL.

Configuración 1: solo AGENTS.md. Cursor lo detectó de inmediato. El archivo apareció en su contexto y, en efecto, se negó a sugerir npm install. Claude Code no hizo nada con él. Ejecutar /memory en Claude Code mostró cero archivos de memoria de proyecto: ningún CLAUDE.md encontrado, y AGENTS.md ni siquiera fue reconocido. Confirmado: no hay respaldo nativo.

Configuración 2: symlink. Apuntamos CLAUDE.md al mismo archivo:

ln -s AGENTS.md CLAUDE.md

Ahora /memory en Claude Code mostraba ./CLAUDE.md como memoria de Proyecto, y el contenido cargado era nuestro AGENTS.md byte por byte. Cursor seguía leyendo AGENTS.md directamente. Un solo archivo físico, ambas herramientas contentas. En Windows esto necesita el Modo Administrador o Modo Desarrollador activado, o ln/mklink falla en silencio.

Configuración 3: @import. Borramos el symlink y en su lugar pusimos una sola línea en la parte superior de un CLAUDE.md real:

@AGENTS.md

/memory mostró entonces CLAUDE.md como el archivo cargado, con AGENTS.md incorporado como referencia importada debajo. Este es el camino que Anthropic realmente documenta, y no necesita permisos especiales del sistema operativo.

El veredicto de nuestra prueba: el symlink hace que Claude Code lea AGENTS.md byte por byte; la importación con @AGENTS.md es la versión segura para Windows que Anthropic realmente recomienda. Ambas te dan una única fuente de verdad. Elige el symlink en macOS/Linux para eliminar toda indirección, o la línea de importación si alguien del equipo usa Windows.

Migrar Entre Formatos: .cursorrules → .cursor/rules → AGENTS.md

La mayoría de los equipos llegan aquí con un archivo .cursorrules heredado y quieren salir de la trampa del archivo único. La migración es breve en cualquier dirección, y los movimientos son de copiar y pegar. El único detalle que muerde a la gente: un archivo .md dentro de .cursor/rules sin frontmatter se ignora en silencio, así que tiene que ser .mdc.

Para modernizar un .cursorrules antiguo, tienes dos caminos claros:

• A .cursor/rules/*.mdc: crea .cursor/rules/general.mdc, añade frontmatter (alwaysApply: true para una regla global) y pega tu contenido anterior debajo. Elimina .cursorrules una vez verificado.
• A AGENTS.md (recomendado para equipos con varias herramientas): para convertir cursorrules a agents.md, copia el cuerpo de .cursorrules en un nuevo AGENTS.md en la raíz de tu repositorio. No necesita frontmatter; es Markdown plano. Luego añade el symlink o la importación @AGENTS.md para que Claude Code también lo lea.

Si te quedas dentro de Cursor y quieres sacarle más partido, nuestra guía sobre cómo sacar más partido a Cursor en el día a día cubre la delimitación de reglas en la práctica.

Ir en la otra dirección (AGENTS.md → CLAUDE.md) es solo el symlink o la importación de la sección anterior. No hay conversión con pérdida porque las tres son Markdown por debajo.

¿Dónde Encajan SKILL.md y las Instrucciones de Copilot?

Aparecen dos formatos más en esta conversación, y skills md es una búsqueda que está despegando ahora mismo, así que merece una ubicación rápida. Ninguno reemplaza a los tres archivos principales; se sitúan junto a ellos.

SKILL.md es el formato de Skills de Anthropic: instrucciones específicas de tarea agrupadas en .claude/skills/*/SKILL.md que Claude carga bajo demanda cuando una tarea coincide, en lugar de estar siempre activo como CLAUDE.md. Piénsalo como un manual especializado al que Claude recurre, no un archivo de memoria de todo el proyecto. El alcance todavía está en evolución, así que no inviertas demasiado todavía. Para ver cómo encaja en un flujo de trabajo real, consulta dónde encaja CLAUDE.md en un flujo de trabajo real de Claude Code.

Las instrucciones de Copilot viven en .github/copilot-instructions.md para GitHub Copilot. Buena noticia: Copilot también lee AGENTS.md, así que si ya estandarizaste en el estándar abierto, Copilot ya está cubierto sin necesidad de un archivo separado.

¿Cuál Deberías Usar? (Según la Forma de tu Equipo)

Ajusta el formato a cómo trabaja realmente tu equipo:

• Usuario solo de Claude Code: usa simplemente CLAUDE.md. No hay razón para añadir AGENTS.md a menos que planees incorporar Cursor o Codex más adelante.
• Usuario solo de Cursor: .cursor/rules/*.mdc para la delimitación por glob, o un único AGENTS.md si quieres portabilidad desde el primer día.
• Equipo con herramientas mixtas: un AGENTS.md como fuente de verdad, enlazado con symlink o importado en CLAUDE.md. Añade un pequeño .cursor/rules solo para comportamiento específico de Cursor.
• Monorepo: AGENTS.md en la raíz más archivos anidados por paquete, para que cada subproyecto se describa a sí mismo y gane el archivo más cercano.

En Techsy estandarizamos la configuración de IA para codificación en equipos con herramientas mixtas, normalmente un AGENTS.md como fuente de verdad con overrides por herramienta donde se necesitan. Si tu equipo está gestionando tres archivos de configuración a mano, pide una consulta gratuita y te lo organizamos.

Un último apunte: este artículo compara los archivos de configuración. Si en realidad estás intentando decidir entre las herramientas en sí, lee comparando los asistentes en sí, no su configuración.

Preguntas Frecuentes

¿Lee Cursor el archivo CLAUDE.md?

No. Cursor lee .cursor/rules/*.mdc y AGENTS.md de forma nativa, pero CLAUDE.md nunca se menciona en la documentación de Cursor y no se carga. Si usas Cursor y quieres compartir configuración con usuarios de Claude Code, pon tus reglas en AGENTS.md (que Cursor sí lee) en lugar de en CLAUDE.md.

¿Lee Claude Code el archivo AGENTS.md?

No de forma nativa. Claude Code solo lee CLAUDE.md, sin respaldo automático a AGENTS.md. Para que funcione, enlaza los archivos con un symlink (ln -s AGENTS.md CLAUDE.md) para que Claude lea AGENTS.md byte por byte, o añade @AGENTS.md en la línea 1 de un CLAUDE.md para importarlo. La importación es la opción recomendada por Anthropic, segura para Windows.

¿Puedo usar un solo archivo para las tres herramientas?

Sí. Adopta AGENTS.md como tu única fuente de verdad, y Cursor y Codex lo leerán directamente. Para Claude Code, añade un puente: enlaza AGENTS.md a CLAUDE.md con un symlink, o coloca @AGENTS.md en la parte superior de un CLAUDE.md. Mantienes un solo archivo, y cada herramienta carga las mismas reglas. Esa es toda la receta para compartir una configuración.

¿Está .cursorrules obsoleto?

Semi-obsoleto. El archivo único .cursorrules en la raíz de tu repositorio todavía funciona en Cursor, pero ya no aparece en la documentación oficial, que es la señal habitual de que un formato está de salida. Los proyectos nuevos deberían usar .cursor/rules/*.mdc para reglas delimitadas o AGENTS.md para portabilidad.

¿Cómo convierto .cursorrules a AGENTS.md?

Copia el cuerpo de tu archivo .cursorrules en un nuevo AGENTS.md en la raíz de tu repositorio. Es Markdown plano, así que no necesita frontmatter ni reformateo. Luego añade un symlink o una importación @AGENTS.md para que Claude Code también lo lea, y elimina el antiguo .cursorrules una vez que confirmes que Cursor detecta el archivo nuevo.

¿Cuál es la diferencia entre CLAUDE.md y AGENTS.md?

CLAUDE.md es el archivo de memoria propietario de Claude Code, leído solo por Claude Code. AGENTS.md es un estándar abierto leído por Cursor, Codex, Copilot y más de 20 herramientas más, pero no por Claude Code de forma nativa. Mismo formato Markdown, mismo trabajo. La diferencia está en el alcance. AGENTS.md viaja entre herramientas; CLAUDE.md se queda dentro de Claude Code.

¿En qué formato debería estandarizar un equipo que usa varias herramientas de IA?

En AGENTS.md. Es el estándar abierto, leído de forma nativa por la mayoría de las herramientas y ya presente en más de 60.000 repositorios. Estandariza ahí tus reglas compartidas, tiéndele un puente a Claude Code con un symlink o una importación, y añade pequeños archivos específicos por herramienta (como .cursor/rules) solo donde una herramienta necesite un comportamiento que las demás no tienen.

¿Cómo funciona la precedencia cuando tengo archivos de configuración anidados?

Tanto para Claude Code como para AGENTS.md, gana el archivo más cercano a tu directorio de trabajo, así que una regla en packages/api/AGENTS.md sustituye al archivo de la raíz del repositorio para todo lo que hay dentro de esa carpeta. Cursor es distinto: combina reglas de Equipo, Proyecto y Usuario por nivel de origen en lugar de por profundidad de carpeta, y las fuentes anteriores ganan los conflictos.

¿Dónde encaja SKILL.md?

SKILL.md es el formato emergente de Skills de Anthropic: instrucciones específicas de tarea en .claude/skills/*/SKILL.md que Claude carga bajo demanda cuando una tarea coincide, en lugar de estar siempre activo como CLAUDE.md. Complementa a CLAUDE.md en lugar de reemplazarlo. El alcance todavía está en evolución en 2026, así que trátalo como un complemento especializado, no como un cuarto archivo que todo proyecto necesita.