Claude Code ahora lee AGENTS.md: qué cambió en la versión 2.1.277

El 18 de septiembre de 2026 se añadió compatibilidad con AGENTS.md en Claude Code 2.1.277. Si la función está disponible en la sesión y en el directorio de trabajo, y no hay ningún CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en la cadena de directorios por encima, Claude Code lee AGENTS.md de forma predeterminada, sin necesidad de importarlo manualmente. Antes, esto se hacía mediante una importación @AGENTS.md en CLAUDE.md o mediante un enlace simbólico de CLAUDE.md a AGENTS.md. Para más detalles, consulta el artículo sobre un archivo de instrucciones para varios agentes.

Si utilizas Claude Code y una o dos herramientas más en el mismo repositorio, el modo Project instructions que elijas determina qué archivos de instrucciones lee Claude Code. A continuación se indican las condiciones de cada uno de los cuatro modos y los pasos para cambiar desde la configuración anterior.

Encontrarás más materiales sobre cómo configurar herramientas en la documentación de Ailoot.

¿Qué cambió en la versión 2.1.277?#

El CHANGELOG.md oficial del proyecto Claude Code en GitHub lo expresa así:

Traducción: se añadió compatibilidad con AGENTS.md; en un proyecto sin CLAUDE.md, Claude Code ahora lee AGENTS.md en su lugar. Esto se puede cambiar en «Project instructions», dentro de /config (todavía no disponible en Bedrock, Vertex ni Foundry).

Antes de esta versión, la ausencia de CLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md en la carpeta de trabajo y en los directorios superiores no bastaba por sí sola para que se leyera AGENTS.md. Hacía falta una importación explícita, un enlace simbólico o un hook manual. Ahora, cuando la función está disponible, el agente carga el archivo automáticamente.

¿Qué archivos impiden que Claude Code lea AGENTS.md automáticamente?#

Si tienes un ~/.claude/CLAUDE.md personal con ajustes de estilo de código, no impedirá que Claude Code lea el AGENTS.md del proyecto. Sin embargo, cualquier CLAUDE.local.md en la carpeta de trabajo —aunque no esté añadido a Git y lo uses para notas personales— impide la lectura automática de AGENTS.md en el modo predeterminado. La importación explícita sigue funcionando; para leer ambos archivos directamente, debes cambiar de modo.

Si se selecciona un modo de lectura directa en Project instructions (consulta «4 modos de Project instructions: cuál elegir» más abajo) y no hay ningún CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo ni en los superiores, Claude Code lee al iniciar la sesión todos los archivos AGENTS.md y .claude/AGENTS.md de esos directorios. Si no hay archivos que bloqueen la lectura, la documentación muestra una línea como esta en una sesión interactiva:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

Un archivo AGENTS.md de un subdirectorio se carga cuando Claude abre allí un archivo con la herramienta Read. En el modo claude-md-or-agents-md, esto solo ocurre si ese subdirectorio no tiene su propio CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md. Para claude-md-and-agents-md, la documentación describe la regla general: CLAUDE.md y AGENTS.md se leen juntos, primero CLAUDE.md y después AGENTS.md en cada directorio. AGENTS.local.md, AGENTS.override.md y cualquier contenido del directorio .agents/ no se leen automáticamente.

En la documentación de Ailoot encontrarás materiales sobre cómo configurar el espacio de trabajo de un agente de IA, incluidos archivos de instrucciones con contexto del proyecto.

4 modos de Project instructions: cuál elegir#

El comportamiento de los modos de la tabla se describe en la documentación de Anthropic. La columna de la derecha ofrece recomendaciones para elegir uno:

También puedes elegir el modo sin usar la interfaz, mediante settings.json:

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

Claude Code ignora este valor en la configuración project y local. Según la documentación de Anthropic, se puede establecer en ~/.claude/settings.json, en un archivo --settings o en la configuración administrada por la organización.

Si ya has configurado un archivo de instrucciones compartido para varias herramientas de IA en un repositorio, las instrucciones para las versiones anteriores a 2.1.277 explican cómo funciona la importación @. Este método sigue funcionando.

Por qué no aparece Project instructions en /config#

Primero, comprueba la versión con el comando claude --version. Si es anterior a 2.1.277, actualiza Claude Code. Si la versión es adecuada pero la sección sigue sin aparecer, comprueba los otros motivos indicados arriba. Mientras la función no esté disponible, importar @AGENTS.md en CLAUDE.md sigue siendo una alternativa funcional.

Qué hacer con la antigua importación @AGENTS.md#

Los siguientes pasos dependen de la configuración anterior. Primero, asegúrate de que la función esté disponible en tu sesión, tal como se explica en la sección anterior.

• CLAUDE.md con una importación @AGENTS.md. Puedes dejarlo como está: Claude Code no leerá el archivo dos veces con ningún valor de Project instructions. Eliminar CLAUDE.md es opcional: la importación ya da acceso a Claude al contenido de AGENTS.md. Sigue comprobando la carga mediante la importación con /memory; preguntarle directamente a Claude por el contenido de las instrucciones es una comprobación poco fiable.
• CLAUDE.md que pide con palabras que se lea AGENTS.md. Esa petición no es una importación y, por sí sola, no garantiza que se cargue el archivo. Si quieres conservar CLAUDE.md (por ejemplo, para las herramientas que también lo leen), sustituye la indicación por una importación @AGENTS.md. Si decides eliminar CLAUDE.md por completo y está seleccionado el modo claude-md-or-agents-md, comprueba primero que CLAUDE.md no contenga instrucciones únicas y que no haya otro CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo ni en los superiores; de lo contrario, Claude Code seguirá leyendo el archivo restante en lugar de AGENTS.md. Después de eliminarlo, asegúrate de que el cambio se haya aplicado: cuando ya no queden archivos que bloqueen la lectura, aparecerá la línea AGENTS.md loaded en una sesión interactiva. Si CLAUDE.md sigue presente y se leen ambos archivos en el modo claude-md-and-agents-md, comprueba /memory (en la versión 2.1.280 o posterior). Una pregunta directa a Claude no permite distinguir la lectura directa de una importación.
• Enlace simbólico de CLAUDE.md a AGENTS.md. Puedes conservarlo: ningún modo provocará una lectura duplicada. Antes de eliminar el enlace en el modo claude-md-or-agents-md, comprueba que se conserven las instrucciones necesarias y que no haya otro CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo ni en los superiores. Comprueba la carga de la misma manera: con la línea AGENTS.md loaded al iniciar la sesión cuando no haya archivos que bloqueen la lectura, o con /memory (versión 2.1.280 o posterior). Si CLAUDE.md sigue presente en el modo claude-md-and-agents-md, preguntarle directamente a Claude es una comprobación poco fiable. Que no aparezca ningún error no basta para confirmar la carga.
• Un hook SessionStart que mostraba manualmente el contenido de AGENTS.md. Cuando el archivo se lee directamente, ese hook añade una segunda copia al contexto. Mientras el hook siga activo, la pregunta «¿qué contienen tus instrucciones?» no confirma la lectura directa: Claude puede responder a partir del texto añadido por el hook. Cambia de configuración en este orden:
  1. Comprueba que la función esté disponible: versión 2.1.277 o posterior, la sesión recibe feature flags, el plugin está habilitado y ya terminó la primera sesión tras la instalación o actualización. Elige un modo de lectura directa: ni claude-md ni managed-only. Si usas el modo predeterminado, comprueba también que no haya archivos que bloqueen la lectura.
  2. Elimina el hook.
  3. Cierra la sesión y abre una nueva. El hook SessionStart añade su texto al inicio, por lo que su contenido permanece en el contexto de una sesión ya abierta. La respuesta de Claude sobre el contenido de las instrucciones en esa sesión no confirmará la lectura directa.
  4. Comprueba la carga en la nueva sesión. A partir de la versión 2.1.280, la ruta a AGENTS.md aparece en /memory. En las versiones 2.1.277–2.1.279, si no hay archivos que bloqueen la lectura, busca al inicio la línea AGENTS.md loaded: la documentación la describe específicamente para el caso en que no se encontró ningún CLAUDE.md. Si conservas CLAUDE.md y usas el modo claude-md-and-agents-md, la comprobación es limitada: /memory no muestra AGENTS.md en esas versiones, la documentación no describe una línea de carga para ese caso y una paráfrasis de las instrucciones no permite distinguir la lectura directa de una importación @ dentro de CLAUDE.md. En ese caso, actualiza a la versión 2.1.280 o posterior y comprueba /memory.

Cómo comprobar si se ha cargado AGENTS.md#

Hay otras dos diferencias respecto a un CLAUDE.md normal: los hooks InstructionsLoaded no se ejecutan para este tipo de AGENTS.md (sí funcionan para un AGENTS.md importado mediante la sintaxis @ desde CLAUDE.md o conectado mediante un enlace simbólico de CLAUDE.md); los directorios añadidos con la opción --add-dir junto con la variable CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD solo cargan el CLAUDE.md de ese directorio; no se incluye su AGENTS.md.

Si necesitas revisar el contenido de un archivo de instrucciones de proyecto extenso, consulta el análisis aparte sobre cómo configurar CLAUDE.md sin que se vuelva demasiado largo. Trata la estructura de las instrucciones; las condiciones para cargar AGENTS.md se describen arriba. Para tomar notas de trabajo entre sesiones, consulta el análisis sobre un segundo cerebro en Claude Code, dedicado a la memoria personal que se añade a las instrucciones del proyecto.

Qué hacer ahora#

La función se publicó el 18 de septiembre de 2026 en la versión 2.1.277. Anthropic podría aclarar los detalles de los modos en futuras versiones. Por eso, antes de cambiar la configuración de un proyecto importante, compara este artículo con la versión actual de /config y el changelog oficial.