# Claude Code ahora lee AGENTS.md: qué cambió en la versión 2.1.277
> El 18 de septiembre de 2026, Claude Code 2.1.277 incorporó compatibilidad directa con AGENTS.md: cuándo se carga el archivo, cómo elegir uno de los 4 modos y qué hacer con las importaciones.
Source: https://ailoot.ai/blog/es/claude-code-agents-md-support/
Canonical: https://ailoot.ai/blog/es/claude-code-agents-md-support/
Language: es
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-041
Revision: sha256-222951a6f751e26d27144d993c37854eebef4dab3cb44bdc655cf08692d9fbaa
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](https://ailoot.ai/blog/es/agents-md-claude-md-one-instruction-file/).
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](https://ailoot.ai/docs/).
[Guías de Ailoot](https://ailoot.ai/docs/)
## ¿Qué cambió en la versión 2.1.277?
Lo esencial
Desde el 18 de septiembre de 2026, Claude Code lee `AGENTS.md` de forma predeterminada si no hay ningún `CLAUDE.md`, `.claude/CLAUDE.md` o `CLAUDE.local.md` en la cadena de directorios, desde la carpeta de trabajo hacia arriba. Si existe alguno de esos archivos, Project instructions no activa la lectura automática de `AGENTS.md`. La importación explícita `@AGENTS.md` desde `CLAUDE.md` sigue funcionando. El archivo personal `~/.claude/CLAUDE.md`, el `CLAUDE.md` administrado por la organización y los archivos de `.claude/rules/` se cargan independientemente de la elección entre los archivos del proyecto. El modo se cambia mediante `/config`. La función todavía no está disponible en Bedrock, Vertex ni Foundry.
El CHANGELOG.md oficial del proyecto Claude Code en GitHub lo expresa así:
Se añadió compatibilidad con AGENTS.md: en un proyecto sin CLAUDE.md, Claude Code lee AGENTS.md en su lugar; cámbialo en «Project instructions», dentro de /config (todavía no disponible en Bedrock, Vertex ni Foundry)
— Anthropic, commit del CHANGELOG.md de claude-code, ca02e7d, https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3
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?
Lo esencial
En el modo predeterminado, se buscan `CLAUDE.md`, `.claude/CLAUDE.md` y `CLAUDE.local.md` en el directorio de trabajo y en los directorios superiores. El archivo personal `~/.claude/CLAUDE.md`, el `CLAUDE.md` administrado por la organización y los archivos de `.claude/rules/` no impiden que se lea `AGENTS.md`; se cargan junto con él.
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](https://ailoot.ai/docs/) encontrarás materiales sobre cómo configurar el espacio de trabajo de un agente de IA, incluidos archivos de instrucciones con contexto del proyecto.
[Guías de Ailoot](https://ailoot.ai/docs/)
## 4 modos de Project instructions: cuál elegir
Lo esencial
En la sección Project instructions del comando `/config` hay cuatro valores: `claude-md-or-agents-md` (predeterminado: uno de los dos archivos), `claude-md-and-agents-md` (ambos juntos), `claude-md` (solo se lee automáticamente `CLAUDE.md`, aunque el proyecto solo tenga `AGENTS.md`) y `managed-only` (al iniciar, solo el `CLAUDE.md` administrado por la organización y la memoria automática; no se incluyen archivos del proyecto ni personales). El cambio se aplica a partir del siguiente mensaje enviado y en cada sesión nueva.
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:
| Valor | Qué lee Claude Code | Cuándo usarlo |
|----|----|----|
| `claude-md-or-agents-md` | `CLAUDE.md` o `AGENTS.md` si no hay ningún `CLAUDE.md`, `.claude/CLAUDE.md` o `CLAUDE.local.md` en el directorio de trabajo ni en los superiores | El modo predeterminado, si el repositorio usa solo uno de los dos archivos y no hay archivos que bloqueen la lectura en los directorios superiores |
| `claude-md-and-agents-md` | Ambos archivos juntos: en cada directorio, primero `CLAUDE.md` y después `AGENTS.md` | Necesitas un `AGENTS.md` común para todas las herramientas y un `CLAUDE.md` breve solo para Claude; o necesitas leer `AGENTS.md` cuando existe `CLAUDE.local.md` |
| `claude-md` | Solo `CLAUDE.md`; se desactiva la lectura automática de `AGENTS.md` mediante Project instructions, aunque `AGENTS.md` sea el único archivo (la importación explícita `@AGENTS.md` desde `CLAUDE.md` sigue funcionando) | `AGENTS.md` está escrito para otra herramienta y podría confundir a Claude |
| `managed-only` | Al iniciar la sesión, solo el `CLAUDE.md` administrado por la organización y la memoria automática; se excluyen del conjunto inicial los archivos `CLAUDE.md` del proyecto, locales y personales, los archivos de `.claude/rules/` y todos los archivos `AGENTS.md`. Sin embargo, los archivos `CLAUDE.md` y `.claude/rules/` de los subdirectorios siguen cargándose más adelante cuando Claude abre allí un archivo. El modo limita el conjunto inicial, pero no aísla por completo de los archivos del proyecto | Para organizaciones que quieren controlar qué conjunto de instrucciones usa Claude Code al iniciar una sesión, independientemente de que el proyecto contenga `CLAUDE.md` o `AGENTS.md` |
También puedes elegir el modo sin usar la interfaz, mediante `settings.json`:
```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](https://ailoot.ai/blog/es/agents-md-claude-md-one-instruction-file/) explican cómo funciona la importación `@`. Este método sigue funcionando.
## Por qué no aparece Project instructions en /config
Lo esencial
Según la documentación de Anthropic, es posible que la sección Project instructions no aparezca por los siguientes motivos:
- Claude Code es anterior a la versión 2.1.277.
- La sesión no recibe feature flags de Anthropic; por ejemplo, si se usa Bedrock u otro proveedor externo, o si la telemetría está desactivada.
- Es la primera sesión justo después de instalar o actualizar desde una versión anterior. Si este es el único motivo, la función aparecerá en la siguiente sesión. `AGENTS.md` solo se cargará si se cumplen las condiciones del modo seleccionado.
- El plugin integrado `agents-md` está desactivado en `/plugin`.
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
Lo esencial
Puedes conservar la importación `@AGENTS.md` en `CLAUDE.md` y el enlace simbólico: el archivo no se leerá dos veces en ningún modo. Si mantienes `CLAUDE.md`, sustituye una indicación textual para «leer AGENTS.md» por una importación. Antes de eliminar un archivo, guarda todas las instrucciones necesarias y comprueba las condiciones del modo seleccionado. Si cambias a la lectura directa, elimina cualquier hook `SessionStart` que haya mostrado manualmente el contenido de `AGENTS.md`; de lo contrario, se añadirá al contexto una segunda copia del archivo. Después, comprueba la carga en una sesión nueva; el método depende de la versión y de si hay archivos que bloqueen la lectura.
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
Lo esencial
Desde la versión 2.1.280, `AGENTS.md` cargado mediante Project instructions aparece en `/memory` y en la lista de archivos Memory del comando `/context`. En las versiones 2.1.277–2.1.279 no aparece ahí, aunque los comandos sí funcionan y muestran el `CLAUDE.md` y otros archivos de memoria cargados. En esas versiones, si no hay archivos que bloqueen la lectura, comprueba al iniciar la sesión si aparece la línea `AGENTS.md loaded`. Preguntarle a Claude por el contenido de las instrucciones es una comprobación poco fiable: la respuesta no permite distinguir la lectura directa de una importación `@` y puede basarse en texto añadido por un hook `SessionStart`. Por tanto, conviene hacer esa pregunta solo en una sesión nueva, después de eliminar ese hook.
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](https://ailoot.ai/blog/es/claude-md-template/). 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](https://ailoot.ai/blog/es/claude-code-second-brain/), 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.
### Fuentes
- [Claude Code, commit del CHANGELOG.md con la entrada 2.1.277 en GitHub (18 de septiembre de 2026)](https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3)
- [Documentación de Claude Code: cómo recuerda Claude tu proyecto — sección AGENTS.md](https://code.claude.com/docs/en/memory)
[Guías de Ailoot](https://ailoot.ai/docs/)
[Ir a Ailoot](https://ailoot.ai/)
## Preguntas sobre Claude Code y AGENTS.md
### ¿Por qué no se carga AGENTS.md aunque exista?
En el modo predeterminado, un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo o un ancestro bloquea la selección automática de AGENTS.md. Comprueba también la versión, la disponibilidad de la función y el modo Project instructions de /config.
### ¿Cómo verifico la carga directa tras quitar un hook manual?
Abre otra sesión para que no esté la salida del SessionStart anterior. Desde 2.1.280, revisa /memory o Memory files en /context; en 2.1.277–2.1.279, sirve la línea de carga inicial cuando no hay CLAUDE.md que la bloquee. Una paráfrasis de Claude por sí sola es una prueba débil.
## Ailoot · La empresa y su cartera de proyectos
Ailoot se apoya en la experiencia operativa acumulada, una amplia base de clientes, un servicio estable y el seguimiento continuo de KPI.
La empresa y su cartera de proyectos: millones de clientes; ventas por miles de millones al mes.
Ailoot aplica esa experiencia operativa al acceso por API a funciones de IA en productos de clientes, agentes, aplicaciones y automatizaciones.