Claude Code sigue sin ofrecer soporte nativo para AGENTS.md, pese a que este formato se ha extendido como archivo común para dar instrucciones a los agentes de programación con inteligencia artificial. La decisión de Anthropic contrasta con una adopción que ya supera los 60.000 proyectos de código abierto, pero existe una solución sencilla: importar AGENTS.md desde CLAUDE.md y mantener así una única fuente de instrucciones para varias herramientas.
Las claves de AGENTS.md y Claude Code en 20 segundos
- AGENTS.md permite guardar instrucciones de desarrollo que pueden compartir diferentes agentes de IA.
- La Linux Foundation señala que ya está presente en más de 60.000 proyectos open source.
- Claude Code continúa utilizando CLAUDE.md como archivo propio de memoria e instrucciones.
- La alternativa práctica consiste en añadir
@AGENTS.mddentro de CLAUDE.md. - Así puede mantenerse AGENTS.md como fuente común sin duplicar las reglas del proyecto.
La cuestión parece menor hasta que en un mismo repositorio empiezan a trabajar varios asistentes. Un equipo puede utilizar Claude Code para desarrollar una funcionalidad, Codex para revisar cambios y otra herramienta integrada en el editor para tareas más pequeñas. Si cada agente necesita su propio archivo de instrucciones, mantenerlos sincronizados acaba convirtiéndose en trabajo adicional.
Y precisamente eso es lo que AGENTS.md intenta evitar.
Qué es AGENTS.md y por qué se está extendiendo
AGENTS.md es básicamente un archivo Markdown destinado a explicar a los agentes de programación cómo deben trabajar dentro de un repositorio.
Puede contener información como esta:
# AGENTS.md## Instalaciónnpm install## Desarrollonpm run dev## Testsnpm test## Reglas- Utilizar TypeScript en modo strict.- Añadir tests para cualquier funcionalidad nueva.- Ejecutar lint antes de terminar una tarea.- No modificar archivos de producción sin revisar los tests.
No requiere una sintaxis especial ni una estructura obligatoria. Es, en cierto modo, el equivalente de un README pensado para agentes.
El formato surgió alrededor de herramientas como OpenAI Codex y posteriormente pasó a estar bajo la tutela de la Agentic AI Foundation (AAIF) de la Linux Foundation.
La propia Linux Foundation anunció en diciembre de 2025 que AGENTS.md se incorporaba como uno de los proyectos fundacionales de AAIF junto con Model Context Protocol (MCP), aportado por Anthropic, y goose, de Block.
Según la fundación, AGENTS.md ya había sido adoptado entonces por más de 60.000 proyectos de código abierto, además de herramientas como Codex, Cursor, Gemini CLI, GitHub Copilot, Jules, VS Code, Factory o Amp.
Hay otra característica interesante para repositorios grandes: pueden existir varios AGENTS.md.
Un proyecto puede tener uno en su raíz y otros dentro de determinados subdirectorios. De esta manera es posible establecer instrucciones específicas para un paquete o componente concreto.
El problema aparece al introducir Claude Code.
Claude Code continúa apostando por CLAUDE.md
Claude Code dispone desde hace tiempo de su propio mecanismo, CLAUDE.md.
Su finalidad es parecida: proporcionar al agente información persistente sobre el proyecto, comandos, arquitectura, convenciones y cualquier otra instrucción que deba conocer antes de modificar código.
Pero CLAUDE.md dispone de mecanismos propios que permiten construir configuraciones más elaboradas.
Entre ellos está precisamente la posibilidad de importar otros archivos utilizando @.
Esto permite, por ejemplo:
@README.md@docs/architecture.md
También hace posible organizar instrucciones específicas de Claude alrededor de la configuración general del proyecto.
El problema no es por tanto que Claude Code carezca de una forma de almacenar contexto. Es justamente lo contrario: Anthropic ya dispone de su propio sistema y continúa desarrollándolo.
Eso explica parcialmente por qué no ha adoptado directamente AGENTS.md.
Las peticiones de soporte llevan meses apareciendo en el repositorio de Claude Code. Una solicitud de abril de 2026 proponía que Claude leyera automáticamente tanto AGENTS.md como .agents/skills/, manteniendo simultáneamente compatibilidad con CLAUDE.md y .claude/skills/.
La propuesta señalaba precisamente uno de los problemas habituales: proyectos que trabajan simultáneamente con Claude Code, Cursor, Aider y Codex terminan manteniendo archivos con gran parte del contenido duplicado.
Varias solicitudes relacionadas han terminado cerradas como duplicadas o como funcionalidades no previstas. Esto confirma la falta de soporte nativo, aunque no permite concluir que Anthropic haya descartado definitivamente AGENTS.md ni atribuirle una explicación oficial concreta sobre sus motivos.
Cómo utilizar AGENTS.md con Claude Code
Afortunadamente no hace falta copiar las instrucciones.
Puede crearse un CLAUDE.md mínimo que contenga:
@AGENTS.md
Claude Code importará entonces las instrucciones de AGENTS.md dentro de su contexto.
El resultado permite utilizar una estructura muy sencilla:
mi-proyecto/├── AGENTS.md├── CLAUDE.md├── package.json├── src/└── tests/
El contenido principal reside en AGENTS.md.
CLAUDE.md funciona simplemente como puente.
Una configuración algo más completa podría quedar así:
@AGENTS.md# Instrucciones específicas para Claude CodeUtiliza Plan Mode antes de realizar cambios importantes.No modifiques la configuración de producción sin solicitar confirmación.
Esta fórmula tiene una ventaja importante.
AGENTS.md se convierte en la fuente común de instrucciones, mientras CLAUDE.md contiene únicamente aquello que tenga sentido para Claude Code.
Si mañana el equipo cambia las instrucciones para ejecutar los tests, solamente necesita modificar AGENTS.md.
No hay que recordar actualizar dos documentos prácticamente iguales.
Otra solución: utilizar un enlace simbólico
Existe una alternativa todavía más directa para proyectos donde no sean necesarias instrucciones específicas para Claude.
En Linux y macOS puede crearse un enlace simbólico:
ln-s AGENTS.md CLAUDE.md
Desde el punto de vista del repositorio existen ambos nombres, pero realmente apuntan al mismo contenido.
Tiene una desventaja: los enlaces simbólicos son menos cómodos en equipos multiplataforma, especialmente en Windows, donde pueden depender de la configuración del sistema, permisos o Developer Mode.
El sistema de importación evita ese inconveniente y permite además añadir posteriormente reglas exclusivas para Claude Code.
Por eso resulta normalmente más flexible utilizar:
@AGENTS.md
AGENTS.md tampoco es exactamente equivalente a CLAUDE.md
Adoptar AGENTS.md como archivo común no implica necesariamente eliminar todas las funciones específicas de cada agente.
Claude Code dispone de una arquitectura de memoria y configuración propia que puede resultar útil en proyectos complejos. AGENTS.md, por su parte, busca deliberadamente ser sencillo y transportable.
Son objetivos diferentes.
Para una empresa que trabaja exclusivamente con Claude Code puede tener sentido estructurar toda su documentación alrededor de CLAUDE.md y las capacidades específicas de la herramienta.
La situación cambia cuando aparecen varios agentes.
Si un mismo repositorio va a ser utilizado desde Claude Code, Codex, un IDE con funciones agénticas y automatizaciones de integración continua, disponer de una base común de instrucciones reduce las posibilidades de que cada herramienta trabaje bajo reglas diferentes.
Hay además una cuestión que conviene tener presente con Claude Code: las instrucciones del proyecto cargadas en la sesión principal no deben darse por heredadas automáticamente por todos los subagentes. Varias incidencias documentadas en el repositorio de Anthropic han tratado precisamente este comportamiento.
Por tanto, AGENTS.md o CLAUDE.md no sustituyen la necesidad de comprobar cómo recibe contexto cada agente o subagente cuando se diseñan flujos automatizados más complejos.
La batalla real está en la interoperabilidad entre agentes
La discusión sobre el nombre de un archivo es en realidad una pequeña muestra de un problema bastante mayor.
Los desarrolladores empiezan a utilizar varios agentes sobre un mismo código.
Un programador puede escribir código con Claude Code, solicitar una segunda revisión a Codex, trabajar desde un editor compatible con agentes y dejar que otro sistema revise posteriormente el pull request.
En ese escenario mantener reglas diferentes para cada producto tiene cada vez menos sentido.
La Linux Foundation está intentando precisamente normalizar distintas capas de esta nueva infraestructura. MCP busca estandarizar la conexión entre modelos y herramientas; Agent2Agent (A2A) aborda la comunicación entre agentes; y AGENTS.md intenta resolver algo mucho más sencillo: que todos sepan cómo deben trabajar cuando llegan a un repositorio.
Claude Code todavía mantiene su propio archivo.
Pero eso no obliga a elegir entre uno u otro.
Un CLAUDE.md de una sola línea puede ser suficiente para mantener las capacidades propias de Claude y, al mismo tiempo, utilizar AGENTS.md como documento común para el resto de herramientas.
Para equipos que empiezan a mezclar agentes de diferentes proveedores, probablemente sea la solución más sencilla mientras la industria decide hasta dónde llegará la estandarización.
Preguntas frecuentes
¿Claude Code lee AGENTS.md automáticamente?
Actualmente Claude Code utiliza CLAUDE.md como archivo propio de instrucciones. Para reutilizar AGENTS.md puede importarse explícitamente desde CLAUDE.md.
¿Cómo se importa AGENTS.md en Claude Code?
Basta con crear un archivo CLAUDE.md en el proyecto y añadir:
@AGENTS.md
Claude Code podrá cargar así las instrucciones del archivo compartido.
¿Es mejor utilizar AGENTS.md o CLAUDE.md?
Depende del entorno. CLAUDE.md permite aprovechar características específicas de Claude Code, mientras que AGENTS.md resulta especialmente útil cuando el mismo repositorio se utiliza con agentes de diferentes proveedores.
¿Quién mantiene actualmente AGENTS.md?
AGENTS.md está bajo la Agentic AI Foundation de la Linux Foundation. La fundación informó de que el formato ya era utilizado por más de 60.000 proyectos de código abierto cuando anunció su incorporación en diciembre de 2025.
