CLAUDE.md vs AGENTS.md:qué agente lee qué archivo.

Qué es cada archivo

Ambos son Markdown simple que un agente carga en su contexto al empezar una sesión. Escribes comandos de compilación y de pruebas, estilo de código, estructura del proyecto y reglas como «nunca edites archivos generados». Son instrucciones, no ajustes obligatorios: el agente las trata como orientación.

• CLAUDE.md es específico de Claude Code. Puede estar en la raíz del proyecto (./CLAUDE.md o ./.claude/CLAUDE.md), en ~/.claude/CLAUDE.md para todos tus proyectos y en subcarpetas. Un CLAUDE.local.md contiene notas privadas de un proyecto.
• AGENTS.md es un formato abierto descrito en agents.md, un README para agentes. Lo leen Codex, Cursor, el agente de código de GitHub Copilot, Gemini CLI, Zed y muchos otros. En un monorepo, un AGENTS.md en una subcarpeta se aplica a esa parte, y gana el archivo más cercano.

El contenido es del mismo tipo. Lo que cambia es qué herramienta recoge el archivo.

Qué hace Claude Code con AGENTS.md

La documentación de Claude Code describe tres casos, para la versión 2.1.277 o posterior:

• Solo un AGENTS.md en tu proyecto, sin CLAUDE.md: Claude Code lee el AGENTS.md.
• Ambos archivos en tu proyecto: Claude Code lee solo los archivos CLAUDE.md.
• Un CLAUDE.md que importa AGENTS.md con @AGENTS.md: Claude lee el CLAUDE.md con AGENTS.md incluido.

Ese segundo caso es el que sorprende. Si añades un CLAUDE.md, aunque sea diminuto, a un repositorio que tiene un AGENTS.md, Claude deja de leer el AGENTS.md salvo que el CLAUDE.md lo importe. Lo mismo vale para un CLAUDE.local.md. Las versiones antiguas de Claude Code solo leían CLAUDE.md, por eso la importación sigue siendo la opción segura. La documentación también describe un ajuste Project instructions en /config para que Claude lea ambos archivos juntos.

Mantener un solo conjunto de instrucciones

Elige un archivo como fuente de verdad. Hay dos formas documentadas:

1. Importar AGENTS.md desde CLAUDE.md

   Crea un CLAUDE.md junto a AGENTS.md cuya primera línea sea @AGENTS.md y añade debajo las instrucciones exclusivas de Claude. Las importaciones usan la sintaxis @path, las rutas relativas se resuelven desde el archivo que las contiene y los archivos importados pueden importar otros hasta cuatro niveles de profundidad.

2. Enlazar CLAUDE.md a AGENTS.md con un enlace simbólico

   Ejecuta ln -s AGENTS.md CLAUDE.md si no tienes nada específico de Claude que añadir. La documentación advierte de que las herramientas de edición de Claude no escriben a través de un enlace simbólico, y de que en Windows un enlace simbólico confirmado puede extraerse como un archivo de texto de una línea, así que la importación es la opción más segura para un repositorio compartido.

Evita un tercer enfoque: un CLAUDE.md que diga «lee AGENTS.md» con palabras. Claude solo ve el archivo si decide abrirlo, mientras que una importación lo carga siempre.

Un AGENTS.md compartido

Pon en AGENTS.md lo que necesita cualquier agente:

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Que sea corto y concreto. La documentación de Claude Code sugiere no pasar de unas 200 líneas por CLAUDE.md, porque los archivos más largos cuestan contexto y se siguen con menos fiabilidad.

Errores habituales

• Dos archivos que se desincronizan. Una copia se actualiza y la otra no. Usa la importación.
• Añadir un CLAUDE.md y perder el AGENTS.md. Ver arriba: impórtalo.
• Poner secretos en cualquiera de los dos. Se confirman en el repositorio y se cargan en cada sesión.
• Reglas vagas. «Escribe código limpio» no sirve de nada. «Ejecuta npm test antes de decir que has terminado» sí.
• Reglas contradictorias entre el archivo de una carpeta superior y el de una subcarpeta.

Leer y revisar estos archivos

Ambos son Markdown normal, así que DotMD abre CLAUDE.md y AGENTS.md como cualquier archivo .md, con un índice y un historial de cada cambio, y muestra lo que un agente cambió en ellos. Leer es gratis. Consulta también Claude Code y Codex con DotMD.

Preguntas sobre CLAUDE.md y AGENTS.md

Más preguntas