Inicio / Una instalación estructurada

AGENTS.md: cuándo lo lee Claude Code y cómo comprobarlo

Con el ajuste por defecto, Claude Code lee AGENTS.md solo cuando ningún CLAUDE.md lo precede en la carpeta de trabajo o por encima, y lo que realmente se ha cargado se comprueba al arrancar la sesión, no en el panel /config.

Un repositorio preparado para otros agentes de código lleva a menudo en su raíz un archivo AGENTS.md: convenciones del proyecto, comando de prueba exacto, archivos que no hay que tocar. Desde la versión 2.1.277 de Claude Code, publicada el 18 de septiembre de 2026, Claude Code lee ese archivo como instrucciones del proyecto, sin importación ni ajuste, con una condición: ningún archivo CLAUDE.md debe ocupar su lugar.

La condición exacta

Con el ajuste por defecto, tres archivos cuentan para esta comprobación: CLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md, en la carpeta de trabajo o en una de las carpetas superiores. Si uno de ellos existe, Claude lee los archivos CLAUDE.md y deja AGENTS.md de lado. El archivo personal ~/.claude/CLAUDE.md, el CLAUDE.md gestionado por la organización y las reglas de .claude/rules/ no cuentan: se cargan junto a AGENTS.md. La documentación señala una trampa: crear un CLAUDE.local.md para anotar en él tus preferencias personales basta para retirar AGENTS.md de la sesión.

Cuando se cumple la condición, Claude lee al arrancar cada AGENTS.md y .claude/AGENTS.md de la carpeta de trabajo y de las carpetas superiores. Lee después el AGENTS.md de una subcarpeta cuando abre en ella un archivo y esa subcarpeta no lleva ninguno de los tres archivos CLAUDE.md. Las importaciones @ruta escritas en un AGENTS.md se expanden como en un CLAUDE.md.

Un ajuste no es un testigo

La entrada Project instructions del panel /config elige lo que se carga. El valor por defecto, claude-md-or-agents-md, aplica la condición anterior; claude-md-and-agents-md lee las dos familias de archivos, los CLAUDE.md de cada carpeta primero; claude-md ignora AGENTS.md; managed-only carga al arrancar el CLAUDE.md gestionado por tu organización y la memoria automática, descartando tus CLAUDE.md de proyecto, local y personal, tus reglas de .claude/rules/ y todo AGENTS.md, pero el CLAUDE.md y las reglas de una subcarpeta se cargan todavía cuando Claude lee en ella un archivo. Este panel dice lo que se pide, no lo que se ha leído. La prueba se lee en otra parte: en sesión interactiva, la documentación da el ejemplo de una línea como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md mostrada en la conversación, y desde la versión 2.1.280, el comando /memory enumera también la ruta del archivo leído.

Quedan dos casos particulares por conocer. Antes de la versión 2.1.281 del 23 de septiembre de 2026, las sesiones en Amazon Bedrock, Google Vertex AI o Microsoft Foundry, detrás de una pasarela o con la telemetría desactivada, solo leían los archivos CLAUDE.md; esa versión las alineó con las demás. Y en ciertos casos, la primera sesión posterior a una actualización desde la versión 2.1.276 o anterior todavía no lee AGENTS.md: la lectura empieza en la sesión siguiente.

La demostración

Crea la carpeta fuera de cualquier proyecto, para que ningún CLAUDE.md de una carpeta superior cuente en la comprobación.

mkdir test-agents-md && cd test-agents-md
printf "# Reglas del proyecto\nResponde siempre en una sola frase.\n" > AGENTS.md
cat AGENTS.md

# Reglas del proyecto
Responde siempre en una sola frase.

Lanza después claude en esa carpeta, lee la línea mostrada al arrancar y escribe /memory. El archivo se carga como el CLAUDE.md descrito en la lección sobre la memoria del proyecto, y sus consignas envejecen de la misma manera, como muestra la lección siguiente.