AGENTS.md en Claude Code: ya lo lee solo, salvo que exista un CLAUDE.md

Desde la v2.1.277 Claude Code lee tu AGENTS.md sin import ni symlink. Pero basta un CLAUDE.md, o tu CLAUDE.local.md personal, en esa carpeta o por encima para que deje de leerlo.

AGENTS.md en Claude Code: el mismo AGENTS.md en tres repos. Sin CLAUDE.md lo lee y responde PELICAN; con un CLAUDE.local.md personal lo ignora y responde NONE; con CLAUDE.md y Project instructions en claude-md-and-agents-md lee los dos y responde PELICAN

TL;DR Sin CLAUDE.md, Claude Code lee tu AGENTS.md directamente desde la v2.1.277. Con un CLAUDE.md o un CLAUDE.local.md en esa carpeta o por encima, solo lee esos. Para que lea los dos, pon Project instructions en claude-md-and-agents-md desde /config. El @AGENTS.md que ya tuvieras sigue funcionando, y no duplica nada.

Durante meses, AGENTS.md fue el archivo que leían Cursor, Codex, Copilot y Gemini CLI, y Claude Code no. Este tip explicaba cómo puentearlo con un import o un symlink. Desde la v2.1.277 ya no hace falta: si tu repo tiene un AGENTS.md y ningún CLAUDE.md, Claude Code lo carga al arrancar.

Pero hay una condición, y es fácil pisarla sin darte cuenta: en cuanto aparece un CLAUDE.md o un CLAUDE.local.md en tu carpeta o en cualquiera por encima, Claude Code deja de leer el AGENTS.md.

Qué lee en cada caso

Lo probé en la v2.1.281 con un repo cuyo AGENTS.md contiene una palabra clave, preguntando a Claude cuál es sin dejarle abrir archivos:

Tu repo tiene	Respuesta
Solo `AGENTS.md`	`PELICAN`
`AGENTS.md` y un `CLAUDE.local.md` con una línea	`NONE`
`AGENTS.md` y un `CLAUDE.md` sin import	`NONE`
`AGENTS.md` y un `CLAUDE.md` con `@AGENTS.md`	`PELICAN`
`AGENTS.md`, `CLAUDE.md` sin import y Project instructions en `claude-md-and-agents-md`	`PELICAN`

La segunda fila es la que más cuesta ver. CLAUDE.local.md es el archivo que usas para tus notas personales del proyecto, fuera de git. Crearlo en un repo que vive de AGENTS.md apaga el archivo del equipo solo para ti, y nada te lo indica.

Lo que no cuenta para esa comprobación: tu ~/.claude/CLAUDE.md, el CLAUDE.md gestionado de tu organización y los archivos de .claude/rules/. Esos siguen cargando junto al AGENTS.md.

Cómo elegir qué lee

1. Mira qué ha cargado

Según la documentación, en una sesión interactiva, cuando lee el AGENTS.md lo dice en la conversación con una línea como no CLAUDE.md found; AGENTS.md loaded: /ruta/AGENTS.md. Si no la ves, /context te enseña la lista de Memory files.

2. Si quieres los dos, cámbialo en /config

Abre /config y busca Project instructions:

Valor	Qué lee
`claude-md-or-agents-md`	`CLAUDE.md`, o `AGENTS.md` si no hay ningún `CLAUDE.md`. Es el valor por defecto
`claude-md-and-agents-md`	Los dos, primero los `CLAUDE.md` de cada carpeta y luego su `AGENTS.md`
`claude-md`	Solo `CLAUDE.md`, como antes de la v2.1.277
`managed-only`	Solo las instrucciones gestionadas de tu organización

El mismo ajuste va en tu ~/.claude/settings.json, bajo el plugin integrado que lo gestiona:

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

En los settings de proyecto o locales no tiene efecto: la decisión es tuya, no del repo.

3. O une los dos con un import

Si tu equipo ya tiene un CLAUDE.md para lo que solo le toca a Claude, un @AGENTS.md en su primera línea sigue siendo la forma de mantener un solo archivo compartido:

@AGENTS.md

## Claude Code
Usa plan mode para cambios en src/billing/.

Qué hacer con el apaño de antes

Un CLAUDE.md con @AGENTS.md: puedes dejarlo. Claude Code no lee dos veces un AGENTS.md que ya ha cargado. Si no tiene nada más, puedes borrarlo.
Un symlink CLAUDE.md → AGENTS.md: igual, el contenido entra una vez.
Un CLAUDE.md que dice en texto "lee AGENTS.md": con esa frase, Claude solo ve el AGENTS.md si decide abrirlo. Bórralo, o cambia la frase por el import.
Un hook SessionStart que imprime el AGENTS.md: quítalo. Ahora añade una segunda copia al contexto.

Cuándo sigue sin leerlo

En versiones anteriores a la v2.1.277, o si desactivaste el plugin agents-md en /plugin.
A veces, en la primera sesión tras actualizar desde la v2.1.276 o anterior. Lo lee desde la siguiente.
Antes de la v2.1.281, en Bedrock, Vertex, Foundry, detrás de un gateway o con la telemetría desactivada.

En cualquiera de esos casos, el @AGENTS.md dentro de un CLAUDE.md es lo que funciona.

Dónde encaja

Qué merece la pena escribir en ese archivo, y qué sobra: tu CLAUDE.md está lleno de basura.
Las normas que solo aplican a una parte del código van mejor en reglas condicionales en .claude/rules/, que además siguen cargando junto al AGENTS.md.

Documentación oficial: How Claude remembers your project · AGENTS.md

Requisitos

Claude Code v2.1.277 o superior para que lea AGENTS.md por su cuenta. Las cinco filas de la tabla las ejecuté en la v2.1.281 con claude -p.