Cómo hacer que Claude Code lea CLAUDE.md y AGENTS.md a la vez
· 6 min de lectura
Para que Claude Code lea CLAUDE.md y AGENTS.md a la vez, actualiza a la versión 2.1.277 o posterior, escribe /config en una sesión y pon el ajuste Project instructions en claude-md-and-agents-md. Si ese ajuste no aparece en tu sesión, importa AGENTS.md desde tu CLAUDE.md con una línea @AGENTS.md, que funciona en cualquier versión.
Si trabajas con Claude Code y con otro agente de programación en el mismo proyecto, seguramente tienes dos archivos de instrucciones: CLAUDE.md para Claude y AGENTS.md para el resto. Desde la versión 2.1.277 Claude Code sabe leer AGENTS.md, pero por defecto no lee los dos a la vez. Esta guía te enseña a elegir qué lee, paso a paso.
Qué lee Claude Code por defecto
La documentación de Claude Code lo resume en tres casos:
Tienes AGENTS.md y ningún CLAUDE.md ni CLAUDE.local.md en tu carpeta o por encima: Claude lee tu AGENTS.md.
Tienes AGENTS.md y además un CLAUDE.md o un CLAUDE.local.md: Claude lee solo tus CLAUDE.md.
Tu CLAUDE.md importa AGENTS.md con una línea @AGENTS.md: Claude lee tu CLAUDE.md con AGENTS.md incluido por la importación.
El segundo caso es el que sorprende: basta con un CLAUDE.local.md de notas personales para que AGENTS.md deje de cargarse.
Paso a paso: cambiar el ajuste Project instructions
1. Actualiza Claude Code a la versión 2.1.277 o posterior. En versiones anteriores este ajuste no existe.
2. Abre una sesión de Claude Code dentro de tu proyecto y escribe /config para abrir el panel de ajustes.
3. Busca el ajuste Project instructions.
4. Elige uno de estos cuatro valores.
claude-md-or-agents-md: el valor por defecto. Lee tus CLAUDE.md, o tu AGENTS.md solo si no hay CLAUDE.md ni CLAUDE.local.md.
claude-md-and-agents-md: lee los dos. En cada carpeta, primero los CLAUDE.md y después AGENTS.md. Si tu CLAUDE.md ya importa AGENTS.md, no lo lee dos veces.
claude-md: solo tus CLAUDE.md, como antes de la versión 2.1.277.
managed-only: solo las instrucciones gestionadas por tu organización y la memoria automática al arrancar.
Para la mayoría de equipos que usan varios agentes, el valor útil es claude-md-and-agents-md. El cambio se aplica desde el siguiente mensaje que envíes y en cada sesión nueva.
La misma opción, escrita en un archivo de ajustes
Si prefieres dejarlo escrito, el valor va bajo el plugin integrado agents-md dentro de pluginConfigs, en tu archivo de ajustes de usuario de Claude Code, en un archivo pasado con la opción de ajustes o en los ajustes gestionados. Estas son las tres claves, de fuera hacia dentro:
Ojo con un detalle de la documentación: Claude Code ignora este valor en los archivos de ajustes del proyecto y en los locales. Si lo pones en la configuración del repositorio, no hace nada.
Cuándo no aparece el ajuste
Según la documentación, Claude lee solo CLAUDE.md, y Project instructions ni siquiera aparece en /config, en estos casos:
Tu versión es anterior a la 2.1.277.
Desactivaste el plugin integrado agents-md desde /plugin.
Es tu primera sesión después de actualizar desde la 2.1.276 o anterior. En algunos casos lo lee desde la sesión siguiente.
En cualquiera de esos casos, la salida es importar AGENTS.md desde un CLAUDE.md, que funciona en cualquier versión.
La alternativa que funciona siempre: importar AGENTS.md
Crea o abre el CLAUDE.md que está junto a tu AGENTS.md y pon esto en la primera línea:
@AGENTS.md
Debajo puedes añadir lo que solo le sirve a Claude, por ejemplo cuándo usar el modo plan. Claude lee primero el archivo importado y después el resto. Si no necesitas nada exclusivo para Claude, la documentación también acepta un enlace simbólico de CLAUDE.md hacia AGENTS.md.
Cómo comprobar que funcionó
En una sesión interactiva en la que Claude lee AGENTS.md directamente, al arrancar aparece una línea del tipo «no CLAUDE.md found; AGENTS.md loaded» con la ruta del archivo. Si usas la importación desde CLAUDE.md, pregúntale a Claude por una regla que solo esté en AGENTS.md: si la conoce sin abrir el archivo, se cargó.
Y si antes montaste un truco para que Claude leyera AGENTS.md, revísalo: la documentación recomienda quitar el hook de inicio de sesión que imprimía AGENTS.md, porque ahora metería una segunda copia en el contexto. Un CLAUDE.md que solo dice «lee AGENTS.md» con palabras tampoco basta, porque Claude solo lo abre si decide hacerlo; cámbialo por la importación.
Preguntas frecuentes
¿Cuál es el valor por defecto de Project instructions en Claude Code?
El valor por defecto es claude-md-or-agents-md. Con él, Claude Code lee tus archivos CLAUDE.md y solo recurre a AGENTS.md cuando no hay ningún CLAUDE.md ni CLAUDE.local.md en tu carpeta de trabajo ni en las carpetas por encima. Para leer los dos a la vez hay que cambiarlo a claude-md-and-agents-md.
¿Puedo poner el ajuste de AGENTS.md en la configuración del repositorio?
No sirve. Según la documentación de Claude Code, el valor instructionFiles se lee en tu archivo de ajustes de usuario, en un archivo pasado con la opción de ajustes o en los ajustes gestionados, pero se ignora en los archivos de ajustes del proyecto y en los locales. Cada persona del equipo lo elige en su propia máquina.
Si importo @AGENTS.md y además activo claude-md-and-agents-md, ¿se lee dos veces?
No. La documentación indica que Claude Code se salta un AGENTS.md que ya cargó, así que uno que tu CLAUDE.md importa o al que apunta con un enlace simbólico no se lee dos veces, uses el valor de Project instructions que uses. Puedes dejar la importación sin riesgo de duplicar contexto.
¿Por qué no me aparece Project instructions en /config?
Pasa en tres casos según la documentación: tienes una versión de Claude Code anterior a la 2.1.277, desactivaste el plugin integrado agents-md desde /plugin, o es tu primera sesión después de actualizar desde la 2.1.276 o anterior. En los tres casos puedes importar AGENTS.md desde un CLAUDE.md mientras tanto.