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. En un repositorio que usan varios agentes de código, la configuración que no falla es tener una sola fuente: las instrucciones en AGENTS.md y un CLAUDE.md con una única importación @AGENTS.md. Eso resuelve qué archivo lee el agente. No resuelve la regla que también debe llegar a un asistente de chat, a otro agente o a una persona fuera del repositorio, ni la regla que cambia sin que cambie el código: esas necesitan vivir fuera de los dos archivos, con quién las decidió y cuándo dejan de valer, y eso es lo que guarda Arroway.
Ú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.
Una fuente para dos archivos
Mantén AGENTS.md como el archivo compartido y deja en CLAUDE.md una línea, @AGENTS.md, seguida de lo que sea específico de Claude Code. La importación se expande al arrancar, Claude Code no lee dos veces el archivo importado, y 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 sirve, 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 la sesión siguiente, ejecuta /context y comprueba que el archivo aparece en Memory files.
Dónde un solo archivo deja de escalar
La importación resuelve qué archivo se lee. Tres cosas no las toca. 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—. El archivo se queda con lo que es del repositorio: cómo compilar, probar y organizar el código.
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. Cambian el CLAUDE.md por una única línea @AGENTS.md, y los dos agentes pasan a leer el mismo archivo. 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 llega 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?
- No, si Claude Code es tu único agente de código: con un CLAUDE.md basta. Si otros agentes del mismo repositorio leen AGENTS.md, mantén AGENTS.md como fuente única y un CLAUDE.md que solo lo importe, más lo que sea específico de Claude Code. Dos archivos independientes es justo la configuración en la que uno de ellos deja de leerse sin que nadie lo sepa.
- ¿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?
- No. El archivo sigue siendo el lugar correcto para lo que es del repositorio. Arroway es para las reglas y decisiones que tienen que llegar a cada herramienta y a cada persona de un proyecto, llevar quién las decidió y salir de la lectura cuando se reemplazan. 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 roadmap.
https://www.arroway.app/es/answers/does-claude-code-read-agents-md