Respuestas
¿Claude Code lee AGENTS.md?
Sí, desde la versión 2.1.277 (18 de septiembre de 2026), pero por defecto solo cuando el proyecto no tiene CLAUDE.md. Si hay un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o en cualquier directorio por encima, Claude Code lee esos y deja fuera AGENTS.md, sin ningún error. El comportamiento por defecto se cambia en "Project instructions" dentro de /config, por ejemplo para leer los dos archivos, y una versión del 24 de septiembre extendió el soporte a Amazon Bedrock, Google Vertex AI, Microsoft Foundry, gateways de LLM y sesiones con la telemetría desactivada. Qué archivo se carga decide qué instrucciones rigen, y nada se lo avisa al equipo. La recomendación de Arroway es dejar los dos archivos vacíos: lo que hay en ellos rige cada sesión sin que nadie lo vea ni lo apruebe, y nunca llega a un asistente de chat, a otro agente ni a una persona fuera del repositorio. Lo que vale va a Arroway, con quién lo decidió y cuándo deja de valer, y cada herramienta conectada lo lee antes de actuar, cargue el archivo que cargue.
Última actualización 29 de septiembre de 2026
Qué archivo gana, y por qué el fallo es silencioso
La comprobación es simple. Claude Code busca CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo y en todos los directorios por encima. Si encuentra uno, esas son las instrucciones del proyecto y AGENTS.md no se carga. Si no encuentra ninguno, carga cada AGENTS.md de esa ruta, y la sesión interactiva muestra una línea que lo avisa. El caso silencioso es CLAUDE.local.md: una persona del equipo crea un archivo personal, fuera del control de versiones, y desde entonces Claude Code deja de leer el AGENTS.md del equipo solo para ella. Nadie más ve la diferencia y nada lo avisa. El ajuste que lo cambia se lee de la configuración de usuario de cada persona, no del repositorio —la documentación dice que los archivos de configuración de proyecto y locales lo ignoran—, así que el equipo no puede hacer commit del arreglo.
Lo que la documentación describe para dos archivos
La documentación de Claude Code describe dos maneras de que los dos archivos se lean como uno. Un CLAUDE.md que importa AGENTS.md con una línea @AGENTS.md se expande al arrancar, el archivo importado no se lee dos veces, y la importación funciona también en las sesiones donde el soporte directo de AGENTS.md no está disponible. Un enlace simbólico de CLAUDE.md a AGENTS.md también funciona, con dos trampas que la documentación enumera: las herramientas de edición se niegan a escribir a través del enlace, y en Windows un enlace con commit puede llegar al clon como un archivo de texto de una línea. En los dos casos, /context muestra en Memory files qué archivo cargó la sesión. Los dos resuelven qué archivo se lee; ninguno dice quién puso cada línea ahí ni si alguien la aprobó.
Dónde un solo archivo deja de escalar
La importación o el enlace resuelven qué archivo se lee. Tres cosas no las tocan. El archivo solo llega a los agentes de código que trabajan en ese repositorio: quien fija precios en una ventana de chat, o un agente en otro repositorio, nunca lo carga. Una línea suya no puede decir que quedó superada, así que la regla del mes pasado se lee igual que la de hoy. Y nada en él distingue la regla que aprobó una persona de la que anotó un asistente. Arroway guarda esa parte: reglas y decisiones por proyecto, cada una con quién la aprobó y la condición que la termina, leídas antes de actuar por cada herramienta conectada —Claude, ChatGPT, Codex, Cursor o cualquiera por MCP—. Por eso la recomendación de Arroway es dejar el archivo vacío.
Cómo se ve en la práctica
Un equipo de tres personas comparte un repositorio en el que trabaja con Claude Code y con otro agente de código. En agosto pasaron sus instrucciones a AGENTS.md y conservaron un CLAUDE.md antiguo con los comandos de build. En septiembre añaden una regla a AGENTS.md: las migraciones nunca se ejecutan desde una rama de feature. El otro agente la sigue. Claude Code encuentra primero el CLAUDE.md antiguo y nunca ve la regla. Llevan la regla a Arroway, escrita una vez con el nombre de quien la decidió, y los dos agentes la leen al empezar cada sesión, carguen el archivo de instrucciones que carguen. Una semana después, la responsable de producto decide en un chat que el plan gratuito baja de cinco proyectos a tres. Esa decisión no trata del código y nunca habría llegado a AGENTS.md. En Arroway se escribe una vez, con su nombre, como reemplazo de la regla de los cinco proyectos, y cada asistente que usa el equipo, dentro o fuera del repositorio, abre su siguiente sesión con ella.
Preguntas que la gente hace sobre esto
- ¿Necesito mantener CLAUDE.md y AGENTS.md?
- Para reglas, ninguno de los dos. Con dos archivos independientes, uno de ellos deja de leerse sin que nadie lo sepa: Claude Code solo lee AGENTS.md cuando no hay un CLAUDE.md en el camino, salvo que el ajuste Project instructions diga otra cosa. La recomendación de Arroway es dejar los dos vacíos y poner lo que vale en Arroway, que cada agente conectado lee al empezar el trabajo, cargue el archivo que cargue.
- ¿Cómo compruebo qué archivo cargó realmente Claude Code?
- Ejecuta /context o /memory en una sesión y busca la ruta del archivo. Cuando Claude Code lee AGENTS.md porque no hay CLAUDE.md, la sesión interactiva también muestra una línea que dice que no se encontró CLAUDE.md y que se cargó AGENTS.md. La documentación avisa que antes de la v2.1.280 esas listas no mostraban un AGENTS.md leído directamente; en versiones anteriores, pregúntale al asistente qué dicen sus instrucciones de proyecto.
- ¿Arroway reemplaza AGENTS.md?
- Para todo lo que tiene que valer, sí: la recomendación de Arroway es que nada se quede en el archivo. Lo que hay en AGENTS.md rige cada sesión sin que nadie lo vea ni lo apruebe. En Arroway cada regla y cada decisión lleva quién la decidió, llega a cada herramienta y a cada persona del proyecto y sale de la lectura cuando se reemplaza. Instálala en la herramienta que ya usas —la página de instalación tiene la ruta de cada una— y la siguiente sesión abre leyendo el proyecto.
Dónde se puede comprobar
Changelog de Claude Code (code.claude.com/docs/en/changelog), entradas 2.1.277 del 18 de septiembre de 2026 y 2.1.282 del 24 de septiembre de 2026; la documentación de memoria de Claude Code (code.claude.com/docs/en/memory), en las secciones sobre AGENTS.md, el ajuste Project instructions, las importaciones y la resolución de problemas, leída el 29 de septiembre de 2026; la documentación de producto en este sitio (Cómo funciona, Instalación); y las reglas de sanción, reemplazo y condición de fin de la especificación sancionada del producto. Claude Code se describe como su propia documentación lo describe en esa fecha, y su comportamiento puede cambiar en cualquier versión. Todo lo descrito aquí sobre Arroway es comportamiento que las herramientas aplican hoy, no hoja de ruta.
https://www.arroway.app/es/answers/does-claude-code-read-agents-md