Cómo carga Claude Code AGENTS.md y CLAUDE.md: lo he probado fichero a fichero

Claude Code ya lee AGENTS.md. Por fin.

Pero no en todas partes. Y si, como yo, tienes media vida metida en AGENTS.md porque también usas Codex, te interesa saber exactamente cuándo lo lee y cuándo no.

Lo conté hace unos días en X y la lié: había un error. Mario Sanoguera me avisó, así que me puse a probarlo a fondo y republiqué la versión corregida. Un post en X se pierde en dos días, así que aquí te dejo la versión completa: cómo lo he probado, qué sale y cómo lo tengo montado yo.

Probado con Claude Code 2.1.300, el 16 de octubre de 2026. Esto cambia rápido, así que si tienes otra versión, al final te explico cómo repetir la prueba.

La respuesta corta

• Claude Code solo usa AGENTS.md si no encuentra un CLAUDE.md en la carpeta donde abres la sesión o en las superiores. Es un plan B.
• Al empezar se cargan la carpeta de inicio y las superiores. Las subcarpetas, más tarde: cuando Claude lee un fichero de esa carpeta con su herramienta de lectura.
• ~/.claude/AGENTS.md no se lee nunca. El único fichero global es ~/.claude/CLAUDE.md.
• Y todo esto se puede cambiar: lo gestiona un plugin integrado con cuatro modos.

Cómo lo he probado

Nada de fiarme de la documentación ni de lo que «parece» que hace. Puse una palabra clave distinta en cada fichero y miré cuáles acababan de verdad en el contexto de Claude.

Cada fichero tenía solo esto:

# Instrucciones

Palabra clave de este fichero: KW_A_SUB_AGENTS

Monté varios proyectos de prueba (cada uno con su git init) combinando AGENTS.md y CLAUDE.md en la raíz y en subcarpetas. En cada caso lancé Claude Code en modo no interactivo y le pedí que listara todas las palabras KW_ que tuviera en el contexto. En algunos casos, antes le pedía que leyera un fichero de una subcarpeta, unas veces con su herramienta de lectura y otras con un cat desde la terminal.

Y como el modelo también se puede inventar cosas, no me quedé con su respuesta. En cada caso miré el log de depuración (--debug-file) y el historial de la sesión que guarda Claude Code, donde se ve qué ficheros de instrucciones le han llegado y en qué momento.

Aquí es donde yo me equivoqué en la primera prueba. Comprobé las subcarpetas haciendo un cat, y resulta que eso no activa la carga de AGENTS.md. Conclusión equivocada, post equivocado.

Resultados

AGENTS.md es un plan B

Si Claude Code encuentra un CLAUDE.md en la carpeta donde abres la sesión o en alguna superior, se olvida de todos los AGENTS.md del proyecto. Los de la raíz y los de las subcarpetas.

O sea: si tienes un CLAUDE.md viejo en la raíz con tres líneas, tu AGENTS.md bien trabajado no existe para Claude.

Si no hay ningún CLAUDE.md, entonces sí usa AGENTS.md, y lo carga en los mismos sitios donde cargaría CLAUDE.md. El log lo dice tal cual: no CLAUDE.md found; AGENTS.md loaded.

Eso sí, hay un matiz. Si el único CLAUDE.md está en una subcarpeta (por ejemplo, docs/CLAUDE.md) y abres la sesión en la raíz, el AGENTS.md de la raíz sí se carga. Claude solo mira hacia arriba desde donde abres la sesión, no recorre el proyecto entero.

Carpeta de inicio y carpetas superiores

Sin sorpresas: se cargan al empezar. Si abres Claude Code en paquetes/api/src, también coge el AGENTS.md de paquetes/api y el de la raíz del repo.

Subcarpetas

No se cargan al empezar. Se cargan cuando Claude lee un fichero de esa carpeta.

Ojo: tiene que leerlo con su herramienta de lectura. Si hace un cat desde la terminal, el AGENTS.md de esa carpeta no entra.

Normalmente Claude lee con su herramienta, así que en el día a día se cargará. Pero si tienes reglas importantes en una subcarpeta y el agente solo ha tocado esos ficheros desde la terminal, esas reglas no las ha visto.

Y aquí CLAUDE.md y AGENTS.md no se comportan igual. En mis pruebas, el CLAUDE.md de una subcarpeta sí se cargó después de un cat. Con AGENTS.md, ni una vez.

El global

~/.claude/AGENTS.md no se lee. Nunca. Lo probé en el modo por defecto y en el que carga los dos ficheros, y no entra en ninguno.

El único fichero global que lee Claude Code es ~/.claude/CLAUDE.md. Si tus reglas globales viven en otro sitio, Claude no las está viendo.

Se puede cambiar: el plugin integrado

Esto no está grabado a fuego. Lo hace un plugin que viene con Claude Code, cc-plugin-agents-md, y tiene una opción, instructionFiles, con cuatro modos:

Probé los cuatro con el mismo proyecto (CLAUDE.md y AGENTS.md en la raíz, otro AGENTS.md en una subcarpeta) y hacen lo que dicen.

Para cambiarlo puedes usar /plugin configure cc-plugin-agents-md@builtin dentro de Claude Code, o ponerlo en tu ~/.claude/settings.json:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

Ojo con dónde lo pones. Según el propio log, esta opción se lee de tus ajustes de usuario, de --settings o de los ajustes gestionados por la organización. Si lo metes en los ajustes del proyecto, no hace nada.

Si usas Codex y Claude Code a la vez

Yo trabajo con los dos todos los días, y lo último que quiero es mantener dos ficheros de reglas que acaban diciendo cosas distintas. Así que tengo AGENTS.md como fuente y CLAUDE.md como enlace simbólico:

# En cada proyecto
ln -s AGENTS.md CLAUDE.md

# El global: Claude Code solo lee ~/.claude/CLAUDE.md
ln -s ~/.codex/AGENTS.md ~/.claude/CLAUDE.md

¿Y para qué, si Claude Code ya lee AGENTS.md? Pues porque el enlace me sigue compensando, por tres motivos:

1. El global. ~/.claude/AGENTS.md no existe para Claude Code, así que sin el enlace tus reglas globales de Codex no llegan.
2. No depende del modo. Con el enlace, Claude Code ve un CLAUDE.md y lo carga en cualquiera de los tres primeros modos. En el de los dos ficheros, no lo duplica: lo comprobé.
3. No se rompe si alguien añade un CLAUDE.md. Sin enlace, basta con que alguien cree un CLAUDE.md en la raíz para que todos los AGENTS.md dejen de cargarse.

¿Y un CLAUDE.md que importe AGENTS.md?

La otra opción que más se ve es un CLAUDE.md de una sola línea:

@AGENTS.md

Esta también la he medido, con el mismo método y la misma versión. Y en todo lo que probé se comporta igual que el enlace simbólico:

El import se resuelve desde la carpeta del propio CLAUDE.md. Un sub/CLAUDE.md con @AGENTS.md carga sub/AGENTS.md, no el de la raíz.

Ojo con la penúltima fila, que es donde te la puedes pegar con cualquiera de las dos. En cuanto hay un CLAUDE.md en la raíz, Claude deja de buscar AGENTS.md por su cuenta. Así que cada subcarpeta con su AGENTS.md necesita también su CLAUDE.md (enlace o import) al lado, o cambiar al modo de los dos ficheros.

¿Cuál elegir? Para Claude Code da igual. Yo sigo con el enlace porque es literalmente el mismo fichero y no hay nada que mantener. El import te compensa si los enlaces simbólicos te dan guerra (en Windows, por ejemplo) o si quieres añadir alguna línea que solo lea Claude debajo del @AGENTS.md.

El caso global con import (~/.claude/CLAUDE.md importando tu AGENTS.md de Codex) no lo he probado, porque no quería tocar mi configuración real para esto.

Si quieres ver cómo organizo después esos AGENTS.md por proyectos y especialistas, lo cuento en Mis agentes de Codex también se despistan: así los organizo con AGENTS.md.

Cómo repetir la prueba con tu versión

Esto puede cambiar en la próxima actualización, y ya has visto que yo mismo me equivoqué la primera vez. Si quieres comprobarlo tú:

1. Crea un proyecto con git init y pon una palabra clave distinta en cada AGENTS.md y CLAUDE.md.
2. Lanza claude -p "Lista todas las palabras que empiecen por KW_ que tengas en el contexto" --debug-file debug.log.
3. Para las subcarpetas, pídele antes que lea un fichero de esa carpeta con su herramienta de lectura, y repite con un cat.
4. Busca AGENTS.md en debug.log: verás qué carpetas ha recorrido y qué ha cargado.

Si te sale algo distinto, cuéntamelo.

Gracias a @mariosanoguera por avisarme del error en la primera versión.