Claude Code ya lee AGENTS.md: cómo usarlo y cuándo tu CLAUDE.md lo bloquea

Claude Code
, , , ,
1

Claude Code ya lee AGENTS.md de forma nativa: desde la versión 2.1.277, si tu proyecto no tiene CLAUDE.md, carga AGENTS.md como instrucciones del proyecto, sin imports ni symlinks. El detalle está en ese “no tiene”: un CLAUDE.md —o incluso un CLAUDE.local.md privado— en tu directorio de trabajo o en cualquiera superior basta para que Claude ignore AGENTS.md por defecto.

Si tu repositorio ya alimenta a Codex, Cursor o Amp con un AGENTS.md compartido, este es el cambio que te permite borrar ese CLAUDE.md de una sola línea que mantenías solo para Claude. Aquí tienes cómo funciona exactamente, cómo cambiar el comportamiento por defecto y qué workarounds antiguos puedes eliminar.

¿Qué es AGENTS.md?

AGENTS.md es un archivo Markdown en la raíz del repositorio con las instrucciones que un agente de código necesita para trabajar en ese proyecto: comandos de build y test, convenciones, estructura. A diferencia de CLAUDE.md, no pertenece a ninguna herramienta: Codex, Amp y Cursor ya lo leen, y por eso se convirtió en el formato compartido para equipos que usan varios agentes a la vez.

Claude Code, el agente de terminal de Anthropic, tenía su propio archivo de instrucciones —CLAUDE.md— y hasta ahora ignoraba AGENTS.md salvo que lo importaras a mano. Si todavía no lo usas, empieza por nuestra guía Claude Code: qué es, por qué importa y cómo empezar.

¿Cómo usar AGENTS.md en Claude Code?

No tienes que hacer nada: actualiza a la versión 2.1.277 o posterior y, si tu proyecto no tiene CLAUDE.md, Claude Code lee tu AGENTS.md automáticamente. La entrada del changelog del 18 de septiembre de 2026 lo resume en una línea: “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under ‘Project instructions’ in /config (not yet on Bedrock, Vertex or Foundry).”

Por dentro, es un plugin integrado llamado agents-md, y Anthropic publicó su código en el repositorio de Claude Code, en mods/agents-md. Un AGENTS.md cargado así se trata como un archivo de instrucciones del proyecto: mismo lugar en el contexto y mismo tratamiento que un CLAUDE.md.

En la práctica, Claude lo lee en estos momentos:

  • Al iniciar la sesión, carga cada AGENTS.md y .claude/AGENTS.md de tu directorio de trabajo y de los directorios superiores. En una sesión interactiva verás una línea como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
  • Mientras trabaja en subdirectorios, carga el AGENTS.md de ese subdirectorio cuando abre un archivo ahí con la herramienta Read, siempre que el subdirectorio no tenga su propio CLAUDE.md.
  • Dentro de cada AGENTS.md, los imports @path se expanden y los patrones de claudeMdExcludes se aplican, igual que con CLAUDE.md.

Lo que no lee: AGENTS.local.md, AGENTS.override.md ni nada dentro de un directorio .agents/. Así que si esperabas que Claude también tomara .agents/skills, no lo hará; fue una de las primeras quejas en el hilo de Hacker News.

¿AGENTS.md o CLAUDE.md: cuál lee Claude Code?

Por defecto gana CLAUDE.md y AGENTS.md se ignora por completo. La documentación oficial lo resume así:

Tu repositorio tiene Claude lee
Un AGENTS.md, y ningún CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo o superiores Tu AGENTS.md
Un AGENTS.md y un CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o superiores Solo tus archivos CLAUDE.md
Un CLAUDE.md que ya importa AGENTS.md Tu CLAUDE.md, con AGENTS.md incluido mediante el import

Lo importante es qué archivos cuentan para esa comprobación:

  • Cuentan (bloquean AGENTS.md): CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o en cualquier directorio superior.
  • No cuentan (se cargan junto con AGENTS.md): tu ~/.claude/CLAUDE.md personal, el CLAUDE.md gestionado por tu organización y los archivos de .claude/rules/.

Esa segunda lista es una buena noticia: tus instrucciones globales personales siguen funcionando en un repositorio que solo tiene AGENTS.md.

La trampa es CLAUDE.local.md. Es el archivo que creas para notas personales que no se suben al repositorio y, como cuenta, añadir uno a un proyecto que depende de AGENTS.md hace que Claude deje de leer AGENTS.md para ti, sin avisar, mientras tus compañeros lo siguen recibiendo. Si quieres ambos, cambia el ajuste de la siguiente sección.

¿Cómo hacer que Claude Code lea CLAUDE.md y AGENTS.md a la vez?

Abre /config en una sesión de Claude Code y cambia Project instructions a claude-md-and-agents-md. Hay cuatro valores posibles:

Valor Qué lee Claude
claude-md-or-agents-md Tus archivos CLAUDE.md, o tus AGENTS.md cuando no hay CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo o superiores. Valor por defecto.
claude-md-and-agents-md Ambos. En cada directorio, primero CLAUDE.md y después AGENTS.md. Un AGENTS.md que tu CLAUDE.md ya importa o enlaza con symlink no se carga dos veces.
claude-md Solo CLAUDE.md: el comportamiento anterior.
managed-only Solo el CLAUDE.md gestionado por tu organización y la memoria automática al iniciar.

También puedes configurarlo en un archivo de settings, bajo el ID del plugin integrado en pluginConfigs:

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

Funciona en ~/.claude/settings.json, en un archivo pasado con --settings o en los managed settings de tu organización. Se ignora en el .claude/settings.json del proyecto y en los settings locales, así que no puedes subirlo al repositorio para todo el equipo. El cambio se aplica desde tu siguiente mensaje y en cada sesión nueva.

Para la mayoría de los equipos que mezclan herramientas, claude-md-and-agents-md es el ajuste que realmente quieres: reglas compartidas en AGENTS.md, extras específicos de Claude en CLAUDE.md y nada duplicado.

¿Por qué Claude Code no lee mi AGENTS.md?

Casi siempre es porque hay un CLAUDE.md en algún punto de la ruta. La lista de comprobación de la documentación, en orden:

  1. Busca un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o en cualquier directorio superior (sin contar ~/.claude/CLAUDE.md). Si existe, Claude lo lee en lugar de AGENTS.md, salvo que cambies a claude-md-and-agents-md.
  2. Ejecuta claude --version y confirma que tienes la versión 2.1.277 o posterior.
  3. Revisa si tu sesión es una de las que no admiten la función (siguiente sección).
  4. Abre /config y comprueba que Project instructions no esté en claude-md ni en managed-only. Si el ajuste no aparece, tu sesión no lo admite.

Otro detalle que te va a confundir: cuando Claude lee AGENTS.md directamente, no aparece en /context ni en /memory. Busca la línea AGENTS.md loaded al inicio de la sesión, o simplemente pregúntale a Claude qué dicen sus instrucciones del proyecto.

¿Funciona AGENTS.md en Bedrock, Vertex o sin telemetría?

Todavía no. Según la documentación al 19 de septiembre de 2026, Claude Code solo lee CLAUDE.md en estos casos:

  • Usas una versión anterior a la 2.1.277.
  • Tu sesión no descarga feature flags de Anthropic: por ejemplo en Amazon Bedrock u otro proveedor externo, o con la telemetría desactivada. (El changelog menciona Bedrock, Vertex y Foundry.)
  • Es tu primera sesión después de instalar o actualizar. Claude lee AGENTS.md a partir de la siguiente.
  • Desactivaste el plugin integrado agents-md en /plugin.

En cualquiera de esos casos, mantén un CLAUDE.md junto a tu AGENTS.md con el import:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude lee primero el archivo importado y después todo lo que agregues debajo.

¿Puedo borrar el symlink o el @AGENTS.md de mi CLAUDE.md?

En la mayoría de los casos, sí. La documentación cubre cada configuración habitual:

  • Un CLAUDE.md que solo contiene @AGENTS.md: puedes dejarlo; Claude nunca lee AGENTS.md dos veces, sea cual sea el ajuste. Bórralo si no tiene nada más, salvo que parte de tus sesiones corran en Bedrock, Vertex o sin telemetría.
  • Un CLAUDE.md que le pide a Claude con palabras que lea AGENTS.md: bórralo, o reemplaza la frase por un import @AGENTS.md real. Una frase solo funciona si Claude decide abrir el archivo.
  • Un CLAUDE.md que es symlink de AGENTS.md: no se rompe nada; bórralo si quieres. Si alguien del equipo usa Windows, elimínalo: Git hace checkout de un symlink versionado como un archivo de texto plano, salvo que core.symlinks esté activado.
  • Un hook SessionStart que imprime AGENTS.md: quítalo. Ahora que Claude lee el archivo directamente, el hook añade una segunda copia a tu contexto.

Si vienes de Cursor, cubrimos la migración completa en Cómo cambiar de Cursor a Claude Code sin perder el contexto del proyecto.

¿Por qué Anthropic tardó tanto en soportar AGENTS.md?

El issue de GitHub #6235, “Feature Request: Support AGENTS.md”, pedía exactamente esto y señalaba que Codex, Amp, Cursor y otros se estaban estandarizando en ese archivo. [VERIFICAR: fecha de apertura / número de reacciones] Los propios comentaristas lo describen como el issue más votado del repositorio.

Terminó cerrado, pero no con una solución, sino con una respuesta de Boris Cherny que remitía a los dos workarounds: un CLAUDE.md con @AGENTS.md o un symlink. El hilo no lo recibió bien. La objeción más repetida: el import es trivial para un solo archivo en la raíz, pero un monorepo con decenas de AGENTS.md anidados necesitaría un CLAUDE.md de relleno junto a cada uno.

La versión 2.1.277 es la solución real que ese cierre no entregó. La reacción en Hacker News fue sobre todo alivio con un toque de reproche: “Time to delete the symlinks” junto a “it’s the absolute bare minimum”.

La lectura de Grego: esto nunca fue por un nombre de archivo

Dos líneas de lógica de fallback tardaron más de un año, y nadie en ese hilo de GitHub creía que fuera un problema de ingeniería. Un CLAUDE.md en un repositorio público es una pequeña valla publicitaria: cada desarrollador que lo clona ve qué herramienta usa el equipo. AGENTS.md es terreno neutral: Codex, Cursor y Amp ya lo leen.

Dar soporte nativo es que Anthropic reconozca que ese terreno neutral es donde va a vivir la configuración de los equipos. Pero fíjate en la forma de la concesión: CLAUDE.md sigue ganando por defecto, el ajuste no se puede versionar a nivel de proyecto y .agents/ sigue ignorado. Es interoperabilidad en los términos de Claude.

Para un CTO, la conclusión práctica es más simple que la política: si tus equipos combinan agentes de código, adopta AGENTS.md como fuente de verdad ahora y trata el archivo propio de cada herramienta como una capa opcional encima. Todas las herramientas principales ya lo leen. El archivo del que depende tu repositorio no debería llevar el nombre de un proveedor.

Para otro ángulo de la misma pelea por la configuración entre herramientas, mira cómo Codex fue en la dirección contraria y empezó a importar la configuración de Claude Code: Un Comando y Codex Se Trae Toda tu Config de Cursor y Claude Code.