EN

CLAUDE.md vs AGENTS.md: qué archivo usar y cómo hacerlos convivir

CLAUDE.md vs AGENTS.md: qué lee Claude Code, Codex, Cursor, Copilot y Gemini CLI, y cómo tener un solo archivo de instrucciones sin duplicar nada.

· 8 min lectura
CLAUDE.md vs AGENTS.md: qué archivo usar y cómo hacerlos convivir

CLAUDE.md es el archivo Markdown que Claude Code carga al empezar cada sesión con las instrucciones de tu proyecto. AGENTS.md es lo mismo pero como formato abierto, pensado para que cualquier agente de código lo lea. Hoy Claude Code también lee AGENTS.md, con una condición que conviene conocer antes de crear el segundo archivo.

¿Trabajas en un repositorio donde un compañero usa Cursor, otro Codex y tú Claude Code? Entonces la pregunta práctica no es qué diferencia a Claude Code, Codex y Cursor, sino cuántos archivos de instrucciones mantienes. Mi respuesta corta es uno, escrito donde lo lean todos, y como mucho un segundo archivo que apunte al primero.

Qué lee cada agente de código

Un archivo de instrucciones es texto que el agente mete en su ventana de contexto antes de tu primer mensaje: comandos de build, convenciones, lo que no debe tocar. Cada herramienta busca uno con nombre distinto, y esta tabla resume lo que he podido comprobar en la documentación oficial a fecha de octubre de 2026.

HerramientaQué archivo leeDónde lo buscaNotas
Claude CodeCLAUDE.md y, si no hay ninguno, AGENTS.md~/.claude/CLAUDE.md (personal), ./CLAUDE.md o ./.claude/CLAUDE.md (proyecto), CLAUDE.local.md (tuyo, sin commit) y subcarpetas bajo demanda [1]Admite imports con @ruta, hasta cuatro saltos
OpenAI CodexAGENTS.md (y AGENTS.override.md)~/.codex y desde la raíz del repo hasta tu carpeta actual, un archivo por directorio [3]Otros nombres solo si los añades en project_doc_fallback_filenames; límite combinado por defecto de 32 KiB
Cursor.cursor/rules y AGENTS.mdReglas en .cursor/rules, AGENTS.md en la raíz [4]Su CLI lee además CLAUDE.md en la raíz [5]
Copilot cloud agent (GitHub).github/copilot-instructions.md, AGENTS.mdAGENTS.md en cualquier carpeta; gana el más cercano [6]Acepta como alternativa un único CLAUDE.md o GEMINI.md en la raíz
Gemini CLIGEMINI.md~/.gemini/GEMINI.md y las carpetas del proyecto [7]Lee AGENTS.md si lo configuras en context.fileName

AGENTS.md no es de ninguna empresa: nació entre Codex, Amp, Jules, Cursor y Factory, y hoy lo custodia la Agentic AI Foundation, bajo la Linux Foundation [2]. No tiene campos obligatorios. Es Markdown normal con los encabezados que quieras.

La fila de Claude Code es la que tiene letra pequeña, y es la que decide cómo organizas el repositorio.

Cuándo lee Claude Code tu AGENTS.md

Desde la versión 2.1.277, Claude Code lee AGENTS.md de forma nativa mediante un plugin integrado, sin import ni configuración [1]. Pero el comportamiento por defecto es excluyente: si encuentra un CLAUDE.md, un .claude/CLAUDE.md o un CLAUDE.local.md en tu directorio de trabajo o en alguno superior, lee esos y se olvida de AGENTS.md.

Tu repositorio tieneClaude Code lee
Solo AGENTS.mdAGENTS.md
AGENTS.md y un CLAUDE.mdSolo CLAUDE.md
Un CLAUDE.md que importa @AGENTS.mdCLAUDE.md, con AGENTS.md dentro

Tu ~/.claude/CLAUDE.md personal y las reglas de .claude/rules/ no cuentan para esa comprobación, así que siguen cargando junto a AGENTS.md. El que sí cuenta, y el que me parece la trampa más fácil de pisar, es CLAUDE.local.md: creas uno para apuntar la URL de tu entorno de pruebas y, sin aviso, Claude deja de leer el AGENTS.md de todo el equipo. La documentación lo dice tal cual, y la salida es cambiar el ajuste Project instructions en /config a claude-md-and-agents-md, que carga los dos [1].

En versiones anteriores a la 2.1.277, o si desactivaste ese plugin, solo lee CLAUDE.md. Lo compruebas con /context, que lista los archivos de instrucciones cargados.

Cuál elegir según tu caso

La regla que sigo es poner el contenido en el archivo que lee más gente y dejar los demás como punteros.

Solo usas Claude Code. Un CLAUDE.md y listo. Tienes imports y CLAUDE.local.md para lo personal, y no ganas nada con un segundo nombre.

Tu equipo mezcla agentes. Escribe las instrucciones en AGENTS.md. Codex y Cursor lo leen sin tocar nada, Copilot cloud agent también, y Claude Code lo carga mientras no exista un CLAUDE.md. Gemini CLI es la excepción: lo lee solo si lo añades en context.fileName de su configuración. Si no tienes nada específico de Claude que decir, no crees CLAUDE.md.

Mezclas agentes y quieres instrucciones solo para Claude. Aquí entra el import, que es el patrón que recomienda la documentación de Claude Code.

Cómo hacerlos convivir sin duplicar

El patrón oficial es un CLAUDE.md mínimo que importa AGENTS.md en la primera línea y añade debajo solo lo que afecta a Claude Code [1]:

@AGENTS.md

## Claude Code

Usa plan mode para cualquier cambio dentro de `src/billing/`.

Plan mode es el modo en el que Claude Code analiza y propone un plan sin modificar archivos hasta que lo apruebas. Claude lee primero el archivo importado y después el resto. La ruta del import es relativa al archivo que la contiene, no a la carpeta desde la que lanzas Claude. Si escribes @AGENTS.md entre comillas invertidas, no se importa: se queda como texto, y eso sirve para mencionar un archivo sin cargarlo.

Si no tienes nada específico de Claude, la documentación acepta también un enlace simbólico:

# CLAUDE.md apunta a AGENTS.md; no imprime nada si va bien
ln -s AGENTS.md CLAUDE.md

Yo prefiero el import. En Windows, crear el enlace exige permisos de administrador o el modo desarrollador, y un clon sin core.symlinks activado acaba con un CLAUDE.md de una línea que contiene la ruta en vez de tus instrucciones. Con un equipo mixto, eso pasa antes o después.

Para Gemini CLI el puente es configuración, no un archivo. Va en .gemini/settings.json [7]:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Codex no lee CLAUDE.md por defecto. Si tu repositorio ya vive en CLAUDE.md y quieres que Codex lo use, puedes añadir ese nombre en project_doc_fallback_filenames de ~/.codex/config.toml [3], aunque me parece más limpio mover el contenido a AGENTS.md.

Qué va en cada archivo y qué no se repite

En AGENTS.md va todo lo que cualquier agente necesita: cómo se instala, cómo se ejecutan los tests, la arquitectura en dos párrafos y las convenciones que el linter no comprueba. Cómo escribir bien ese contenido está contado en la guía para escribir un AGENTS.md que no empeore a tu agente, y no lo repito aquí.

En CLAUDE.md va lo que solo tiene sentido en Claude Code: cuándo usar plan mode o referencias a skills y subagentes que solo existen en .claude/. Una skill es un paquete de instrucciones que Claude carga solo cuando la tarea lo pide (qué es una skill), y un subagente es otra instancia con su propio contexto a la que Claude delega trabajo (agente frente a subagente en Claude Code). Si una línea tendría sentido para Codex, pertenece a AGENTS.md.

Lo que nunca debe pasar es tener el mismo bloque copiado en los dos. Con la configuración por defecto Claude Code solo lee uno, así que la copia que no lee se va desactualizando sin que nadie lo note, y el día que alguien cambia el ajuste a cargar ambos, el modelo recibe dos versiones distintas de la misma regla. La documentación avisa de que, ante dos instrucciones contradictorias, Claude puede elegir una de forma arbitraria [1].

Y algo que olvidamos con frecuencia: estos archivos son contexto, no reglas que el agente esté obligado a cumplir. Si algo no puede pasar nunca, como tocar la carpeta de migraciones, eso va en un hook de Claude Code que lo bloquea siempre, no en una frase del CLAUDE.md. Esa diferencia entre pedir y garantizar es justo lo que trabajamos en el curso de patrones agénticos.

Fuentes

Comportamiento comprobado el 2026-10-12 en la documentación oficial de cada herramienta. Cambia a menudo, así que revisa la versión que usas.

  1. How Claude remembers your project — Claude Code Docs — ubicaciones de CLAUDE.md, sintaxis de imports, lectura nativa de AGENTS.md desde la v2.1.277, ajuste Project instructions, import frente a enlace simbólico.
  2. agentsmd/agents.md — repositorio oficial del formato — formato sin campos obligatorios, origen y custodia por la Agentic AI Foundation.
  3. Custom instructions with AGENTS.md — OpenAI Codex — orden de descubrimiento, AGENTS.override.md, project_doc_fallback_filenames y límite de 32 KiB.
  4. Rules — Cursor Docs — reglas de proyecto en .cursor/rules y AGENTS.md como alternativa simple.
  5. Using Agent in CLI — Cursor Docs — la CLI de Cursor aplica AGENTS.md y CLAUDE.md de la raíz como reglas.
  6. Adding repository custom instructions for GitHub Copilot — GitHub Docs — copilot-instructions.md, AGENTS.md con precedencia del más cercano y CLAUDE.md o GEMINI.md como alternativa.
  7. Provide context with GEMINI.md files — Gemini CLI — jerarquía de GEMINI.md y context.fileName para usar AGENTS.md.

Preguntas Frecuentes

¿Qué es CLAUDE.md?

CLAUDE.md es un archivo Markdown que Claude Code carga al inicio de cada sesión con instrucciones persistentes, como los comandos de build y test o las convenciones del equipo. Puede vivir en tu carpeta personal (~/.claude/CLAUDE.md), en la raíz del repositorio o en subcarpetas, y /init genera uno inicial analizando el código.

¿Claude Code lee AGENTS.md?

Sí, desde la versión 2.1.277, pero por defecto solo si no hay ningún CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu carpeta o por encima. Si tienes los dos, lee solo CLAUDE.md, salvo que lo importes con @AGENTS.md o cambies el ajuste Project instructions.

¿CLAUDE.md o AGENTS.md: cuál uso?

Si solo usas Claude Code, CLAUDE.md. Si tu equipo mezcla agentes, escribe las instrucciones en AGENTS.md y crea un CLAUDE.md que lo importe con @AGENTS.md solo si necesitas algo específico de Claude.

¿Qué diferencia hay entre CLAUDE.md y AGENTS.md?

Lo que cambia es quién los lee. CLAUDE.md es el nombre propio de Claude Code y admite sus imports; AGENTS.md es un formato abierto que leen muchos agentes, así que es el sitio para las instrucciones comunes. Por defecto Claude Code lee uno u otro, no los dos: si existe un CLAUDE.md, ignora AGENTS.md salvo que lo importes o cambies el ajuste Project instructions.

¿Cursor rules o AGENTS.md?

Para instrucciones que valen para todo el proyecto, AGENTS.md, porque además lo leen otros agentes. Las reglas de .cursor/rules tienen sentido cuando quieres algo que solo afecte a Cursor o que se aplique únicamente a ciertos archivos.

¿copilot-instructions.md o AGENTS.md?

Copilot cloud agent lee ambos. Si tu equipo solo usa Copilot, .github/copilot-instructions.md basta; si conviven varios agentes, pon lo común en AGENTS.md y deja en copilot-instructions.md solo lo que sea exclusivo de Copilot.

Sigue explorando

Artículos relacionados