Claude Code ya lee AGENTS.md: un solo archivo de instrucciones para todos tus agentes de código

Si usás más de un agente de código —Claude Code para una cosa, Codex o Cursor para otra— seguro terminaste con el mismo instructivo copiado en dos o tres archivos distintos. Cambiás una regla en uno y te olvidás del resto. Acaba de salir un cambio chico que arregla justo eso.

Qué cambió

Desde la versión 2.1.277, Claude Code agregó soporte para AGENTS.md. La regla es simple: si en una carpeta no hay un archivo CLAUDE.md, Claude Code busca y usa el AGENTS.md. Si ya tenés un CLAUDE.md, ese sigue mandando y no cambia nada.

Dos aclaraciones que importan:

• Es un fallback, no una mezcla. CLAUDE.md tiene prioridad donde exista; AGENTS.md entra solo cuando no hay CLAUDE.md.
• Qué archivo lee lo controlás en /config, en la sección "Project instructions".

¿Por qué es útil? Porque AGENTS.md no es un invento de Anthropic: es un formato que ya adoptaron varios agentes de código (Codex, entre otros). Un solo archivo, en la raíz de tu proyecto, que todas tus herramientas leen igual. Menos reglas duplicadas, menos desincronización.

El archivo es texto plano en Markdown. Ahí ponés lo que querés que el agente sepa siempre de ese repo: cómo se corre el proyecto, qué convenciones seguís, qué NO tocar, cómo escribir los commits, qué comandos usar para testear.

Qué podés hacer con esto hoy

Si trabajás con Claude Code y algún otro agente sobre el mismo código, unificá tus instrucciones en un solo archivo. Paso a paso:

1. Actualizá Claude Code a la 2.1.277 o superior. Si lo instalaste por npm, corré la actualización habitual; si no, revisá que tu versión sea igual o más nueva.
2. En la raíz de tu proyecto, creá (o renombrá tu instructivo existente a) AGENTS.md.
3. Escribí las reglas en lenguaje directo. Un ejemplo mínimo:

# AGENTS.md

## Cómo correr el proyecto
- Instalar: npm install
- Levantar en dev: npm run dev
- Testear antes de dar algo por terminado: npm test

## Convenciones
- TypeScript en todo el código nuevo.
- Nada de dependencias nuevas sin avisar.
- Commits en español, en imperativo ("agrega", "corrige").

## Qué NO tocar
- No modificar /infra ni las variables de entorno.
- No borrar tests existentes para que pase el build.

4. Asegurate de que en esa carpeta no haya un CLAUDE.md, o Claude Code va a ignorar el AGENTS.md. Si querés forzar cuál usa, entrá a /config → "Project instructions".
5. Probalo: abrí Claude Code en el proyecto y pedile algo que dependa de una de tus reglas (por ejemplo, que corra los tests). Si respeta lo que pusiste, quedó bien enganchado.

La ventaja concreta: la próxima vez que cambie una convención, la editás en un solo lado y todos tus agentes quedan alineados.

Qué NO resuelve / cuándo no te sirve

• No es magia contra el contexto largo. Un AGENTS.md de 300 líneas con todo lo que se te ocurre no ayuda: el agente lo lee entero cada vez y las reglas importantes se diluyen. Poné lo esencial y sacá el relleno.
• Si ya tenés CLAUDE.md, no ganás nada automáticamente. El CLAUDE.md sigue teniendo prioridad. Para aprovechar el archivo compartido tenés que decidir con cuál te quedás; no se fusionan.
• No funciona todavía en Bedrock, Vertex ni Foundry. Si corrés Claude Code contra Amazon Bedrock, Google Vertex o Microsoft Foundry, el fallback a AGENTS.md no está disponible por ahora; esas plataformas siguen esperando CLAUDE.md.
• No cuesta nada extra, pero tampoco cambia el precio de usar Claude Code: es una función del cliente, no un producto nuevo. Y funciona igual desde Argentina, porque no depende de región.
• No reemplaza al criterio. El archivo mejora la consistencia, no convierte a un agente flojo en uno confiable. Seguís necesitando revisar lo que produce.

Para cerrar

Es un cambio de plomería, no un anuncio grandilocuente, y por eso mismo es de los que te ahorran fricción real todas las semanas. Si mantenés instrucciones repetidas para dos o tres agentes, esta es la excusa para juntarlas en un AGENTS.md, actualizar Claude Code y dejar de sincronizar archivos a mano.