Sesgo declarado, como siempre: enseño Claude Code a equipos de ingeniería, así que dónde viven las instrucciones de un repo —y qué fichero lee el agente— me toca de lleno. Precisamente por eso esta pieza va de hechos verificables y de qué te toca decidir, no de vender un cambio de convención como si fuera un lanzamiento de producto.
El cambio de esta semana es pequeño en el diff y grande en la práctica para
cualquier equipo que ya trabaja con más de una herramienta de agentes: Claude
Code ha empezado a leer AGENTS.md.
Los hechos
Según el
changelog oficial de Claude Code,
la versión v2.1.277 (18 de septiembre de 2026) "añade soporte de
AGENTS.md: en un proyecto sin CLAUDE.md, Claude Code lee AGENTS.md en su
lugar; se cambia en «Project instructions» dentro de /config (todavía no en
Bedrock, Vertex ni Foundry)".
Desglosado, son cuatro cosas concretas:
AGENTS.mdes un recambio, no un añadido. Solo entra en juego cuando el proyecto no tieneCLAUDE.md. Si tienesCLAUDE.md, tu comportamiento no cambia: sigue mandando ese fichero.- Cuando no hay
CLAUDE.md, Claude Code cargaAGENTS.mdcomo instrucciones del proyecto, igual que haría conCLAUDE.md. - Puedes ajustar qué fichero se usa desde el apartado "Project instructions"
de
/config. - Aún no está en todos los proveedores. El changelog avisa de que no está disponible todavía en Bedrock, Vertex ni Foundry.
AGENTS.md no es un invento de este cambio: es el nombre de fichero que varias
herramientas de agentes usan como convención común para dejar instrucciones de
proyecto en la raíz del repositorio. Lo nuevo es que Claude Code ahora lo
reconoce cuando no encuentra su propio CLAUDE.md.
Por qué esto importa
El titular fácil es "otro fichero que Claude lee". El titular real, para un
equipo, es que desaparece una fuente de duplicación. Hasta ahora, un repo
que ya mantenía un AGENTS.md para otra herramienta tenía que copiar esas
mismas instrucciones en un CLAUDE.md para que Claude Code las respetara. Dos
ficheros que dicen lo mismo, que se desincronizan a la primera de cambio y que
alguien tiene que acordarse de actualizar a la vez.
Con el recambio, un proyecto sin CLAUDE.md que ya tenga AGENTS.md empieza a
funcionar con Claude Code sin tocar nada. Es interoperabilidad por defecto: las
mismas instrucciones de proyecto sirven para más de un agente, sin mantener dos
copias.
Conviene tener clara la jerarquía, porque es justo donde se cuelan los
malentendidos: CLAUDE.md gana siempre que exista. AGENTS.md solo se lee
cuando CLAUDE.md no está. No es una fusión de ambos ni una suma: es un
recambio. Si quieres que Claude Code combine instrucciones específicas suyas con
un AGENTS.md compartido, la vía no es tener los dos sueltos y esperar que se
mezclen, sino usar los @imports de CLAUDE.md —por ejemplo, un CLAUDE.md
mínimo que importe @AGENTS.md—. Esa jerarquía y los imports son justo lo que
trabajamos en el curso de
CLAUDE.md y memoria.
Qué te afecta, según quién seas
Si tu repo ya tiene CLAUDE.md. Cero deberes. Nada cambia: Claude Code
sigue leyendo tu CLAUDE.md y AGENTS.md ni se mira. Este cambio no te toca
salvo que decidas replantear dónde quieres tus instrucciones.
Si trabajas con varias herramientas de agentes sobre el mismo repo. Aquí es
donde más rinde. Si ya mantienes un AGENTS.md como fuente común y no tenías
CLAUDE.md, Claude Code empieza a respetar esas instrucciones sin que dupliques
nada. Una sola fuente de verdad para el contrato del proyecto, leída por más de
un agente. Antes de darlo por hecho, comprueba que efectivamente no tienes
un CLAUDE.md colgado en el repo que esté ganando la partida sin que te des
cuenta.
Si administras Claude Code para un equipo. Dos cosas que subrayar. Una: este
soporte todavía no llega a Bedrock, Vertex ni Foundry, así que si tu equipo
corre Claude Code a través de esos proveedores, AGENTS.md no se leerá aún ahí;
para esos entornos, de momento, el fichero que manda sigue siendo CLAUDE.md.
Dos: decidir si tu estándar de equipo es CLAUDE.md, AGENTS.md o un
CLAUDE.md que importe lo común no es un detalle cosmético. Marca qué agente
lee qué, en qué entornos, y cómo evitáis que las instrucciones se
desincronicen. Ese tipo de criterio —qué contrato lee el agente y quién lo
gobierna— es parte del terreno que cubrimos en
permisos, settings y seguridad y, en su
raíz, en la intro a Claude Code.
Qué llevarte
AGENTS.mdcomo recambio (v2.1.277): en un proyecto sinCLAUDE.md, Claude Code leeAGENTS.mden su lugar.CLAUDE.mdsigue mandando: si existe,AGENTS.mdni se mira. No hay fusión; es un recambio.- Se ajusta en
/config: apartado "Project instructions". - Aún no en todos los proveedores: no está disponible todavía en Bedrock, Vertex ni Foundry.
- Si quieres combinar ambos: usa
@importsdesdeCLAUDE.mden vez de dejar los dos ficheros sueltos.
Preguntas rápidas
Tengo CLAUDE.md y AGENTS.md en el repo. ¿Cuál lee Claude Code?
CLAUDE.md. AGENTS.md solo se lee cuando no existe CLAUDE.md. No se
combinan solos.
¿Se fusionan los dos ficheros?
No. Es un recambio, no una suma. Si quieres que Claude Code aproveche un
AGENTS.md compartido junto a instrucciones propias, impórtalo desde
CLAUDE.md con @AGENTS.md.
Uso Claude Code a través de Bedrock, Vertex o Foundry. ¿Me sirve ya?
Todavía no. El changelog indica que el soporte de AGENTS.md aún no está
disponible en esos proveedores. Ahí, de momento, usa CLAUDE.md.
¿Vuestro equipo mantiene instrucciones de proyecto para más de un agente?
Decidir dónde viven —CLAUDE.md, AGENTS.md o un contrato importado— y cómo
evitáis que se desincronicen es justo el tipo de criterio que trabajamos en la
formación en directo para equipos — sobre vuestro repo, vuestras
herramientas y vuestra forma real de trabajar.