Claude Code ahora lee AGENTS.md, pero solo sin un CLAUDE.md: los tres archivos que lo cancelan silenciosamente (2026)

La nota de lanzamiento es un solo punto. La página de documentación detrás de ella, titulada "Cómo recuerda Claude tu proyecto", detalla el mecanismo y comienza con el alcance: "Claude Code puede leer AGENTS.md como tus instrucciones de proyecto, de modo que un repositorio ya configurado para otros agentes de programación funcione sin agregar un CLAUDE.md, una importación o una configuración".

Luego viene una tabla de tres filas, que resume toda la historia. Un repositorio con "Un AGENTS.md y ningún CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o por encima de este" obtiene "Tu AGENTS.md". Un repositorio con "Un AGENTS.md y un CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o por encima de este" obtiene "Solo tus archivos CLAUDE.md". Y un repositorio con "Un CLAUDE.md que ya importa AGENTS.md" obtiene "Tu CLAUDE.md, con AGENTS.md incluido a través de la importación".

La regla de conteo se detalla por separado, y es la parte que vale la pena copiar en tus propias notas. Los archivos que "Cuentan, por lo que Claude los lee en lugar de AGENTS.md" son "un CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o en cualquier directorio por encima de este". Los archivos que "No cuentan y se siguen cargando junto con AGENTS.md" son "tu ~/.claude/CLAUDE.md, el CLAUDE.md administrado de tu organización y los archivos .claude/rules/".

Anthropic también redactó la trampa en un lenguaje sencillo, en una nota propia: "Debido a que CLAUDE.local.md cuenta, agregar uno para mantener tus propias instrucciones no confirmadas en un proyecto que depende de AGENTS.md impide que Claude lea AGENTS.md por ti".

Y hay una superficie de confirmación. Cuando nada cuenta, la documentación dice que al inicio de la sesión Claude lee "cada AGENTS.md y .claude/AGENTS.md en tu directorio de trabajo y en los directorios por encima de este", y que "En una sesión interactiva verás una línea como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md en la conversación".

Hay un segundo cambio de la misma semana con la misma forma. La versión 2.1.275, publicada un día antes, "Agregó la sincronización de las habilidades (skills) y complementos (plugins) habilitados en tu cuenta de claude.ai a las sesiones de terminal en las que hayas iniciado sesión; desactívalo con syncClaudeAiSkills: false o syncClaudeAiPlugins: false". Lee ambos cambios juntos y el patrón quedará claro: aquello con lo que comienza tu sesión se ha movido, dos veces, sin que nadie edite un archivo en el repositorio.

Cambia qué archivo tiene autoridad, no lo que dicen los archivos. Si tu repositorio solo tiene un AGENTS.md, el comportamiento mejora y no tienes que hacer nada. Si tiene ambos archivos, no ha cambiado nada en absoluto: Claude lee el CLAUDE.md que siempre leyó, y el AGENTS.md que está al lado sigue llegando únicamente a las otras herramientas. Las personas que probablemente se sorprendan más son las que hicieron más trabajo: quienquiera que haya creado una importación o un enlace simbólico para que ambos mundos se mantuvieran sincronizados ahora tiene dos mecanismos haciendo el mismo trabajo.

No cambia cómo se analizan los archivos. Dentro de cada AGENTS.md, "se expanden las importaciones @path, se aplican los patrones claudeMdExcludes y los subagentes que omiten las instrucciones del proyecto también omiten estos archivos".

Sí cambia cómo realizas la verificación. Un AGENTS.md leído a través de la configuración se comporta de manera diferente a un CLAUDE.md en cuatro lugares documentados. En /memory y en la lista de Memory files en /context, un CLAUDE.md aparece como "Listado", mientras que el AGENTS.md aparece como "No listado. Para confirmar que Claude lo leyó, busca la línea AGENTS.md loaded debajo del valor predeterminado, o pregúntale a Claude qué dicen las instrucciones de su proyecto". Los ganchos InstructionsLoaded se "activan" para uno y "no se activan" para el otro, aunque "se activan como de costumbre para un AGENTS.md que un CLAUDE.md importa o al que enlaza simbólicamente". Los directorios agregados con --add-dir cargan su CLAUDE.md pero no su AGENTS.md. Y una importación @path de un archivo fuera de tu directorio de trabajo "se carga solo si ya aprobaste las importaciones externas para este proyecto, sin previo aviso".

Tampoco llega a todas partes a la vez. La documentación enumera las sesiones donde "Claude lee únicamente archivos CLAUDE.md, y Project instructions no aparece en el panel de configuración de /config": versiones anteriores a la v2.1.277, sesiones que no "obtienen flags de características de Anthropic, por ejemplo porque usas Amazon Bedrock u otro proveedor externo, o porque desactivaste la telemetría", tu "primera sesión después de instalar o actualizar", y configuraciones donde "tú o tu organización establecieron disableAllHooks o allowManagedHooksOnly, o desactivaste el complemento integrado agents-md".

"Ya puedo eliminar mi CLAUDE.md". Solo si el repositorio no tiene nada específico de Claude. La documentación describe mantener un CLAUDE.md cuando "algunas de tus sesiones no pueden cargar AGENTS.md directamente", lo cual es una categoría real, no hipotética.

"A partir de ahora se leerán ambos archivos". Solo bajo uno de los cuatro valores de Project instructions. El valor predeterminado, claude-md-or-agents-md, lee "Tus archivos CLAUDE.md, o tus archivos AGENTS.md cuando no tienes ningún CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o por encima de este". Leer ambos es claude-md-and-agents-md, que los lee "juntos, primero los archivos CLAUDE.md de cada directorio y luego sus archivos AGENTS.md".

"Mi importación ahora es redundante, así que debería eliminarla". La documentación dice lo contrario sobre una configuración: para "Un CLAUDE.md que contiene @AGENTS.md", dice "puedes dejarlo. Mantener la importación nunca hace que Claude lea AGENTS.md dos veces, independientemente del valor de Project instructions que utilices".

"Nada en mi configuración está duplicado". Uno de ellos lo está. Para "Un gancho SessionStart que imprime AGENTS.md", la guía es "eliminarlo. Una vez que Claude lee AGENTS.md directamente, el gancho agrega una segunda copia al contexto".

"El archivo que escribí es el contexto". Un archivo de instrucciones es un informe permanente, y las preguntas que descarrilan un proyecto largo suelen ser sobre decisiones más que sobre convenciones: cuál de los dos enfoques decidieron adoptar en junio y por qué. Vale la pena separar ese registro del archivo que tus agentes leen al inicio, que es el argumento en por qué el contexto largo no es memoria.

Paso 1: Haz un inventario de los archivos que cuentan, no de los que recuerdas

La comprobación se realiza hacia arriba, no solo en la raíz del proyecto. Recorre tu directorio de trabajo y cada directorio por encima de este y busca exactamente tres nombres: CLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md. Uno solo en cualquier parte de esa ruta es suficiente para que Claude lea únicamente archivos CLAUDE.md.

Dos nombres más merecen una mirada, porque están documentados bajo "No leídos": "AGENTS.local.md, AGENTS.override.md o cualquier cosa bajo un directorio .agents/". Si alguien dividió las anulaciones personales en uno de esos, no han estado llegando a Claude Code y no empezarán a hacerlo ahora.

Tus archivos personales y a nivel de organización están seguros de cualquier manera. "No cuentan y se siguen cargando junto con AGENTS.md", por lo que un ~/.claude/CLAUDE.md lleno de tus propios hábitos no es lo que está cancelando el archivo del repositorio.

Paso 2: Elige un valor de Project instructions a propósito

Escribe /config y establece Project instructions deliberadamente en lugar de heredar el valor predeterminado. Los cuatro valores corresponden a cuatro situaciones reales: claude-md-or-agents-md cuando un archivo es claramente el del proyecto; claude-md-and-agents-md cuando deseas el archivo compartido más las adiciones específicas de Claude, y especialmente cuando mantienes un CLAUDE.local.md; claude-md cuando el proyecto ha divergido y el archivo compartido es solo para otras herramientas; y managed-only, que carga "Solo el CLAUDE.md administrado de tu organización y la memoria automática al inicio".

El valor también puede residir en la configuración en lugar de en el panel, bajo el ID del complemento integrado agents-md en pluginConfigs, en tu archivo de configuración de usuario, en un archivo --settings o en la configuración administrada. Una restricción importante para los equipos: "Claude Code lo ignora en los archivos de configuración locales y del proyecto". No puedes enviar esta opción a tus colegas dentro del repositorio, lo que significa que pertenece a tus notas de incorporación en su lugar. Cualquiera que sea el camino que elijas, "Tu cambio se aplica a partir del próximo mensaje que envíes y en cada nueva sesión".

Paso 3: Confirma la carga y luego elimina solo la solución temporal que duplica

Inicia una sesión y busca la línea. Bajo el valor predeterminado sin ningún archivo de conteo presente, la conversación muestra no CLAUDE.md found; AGENTS.md loaded: seguido de la ruta. Si estás usando claude-md-and-agents-md, o si mantuviste una importación, ejecuta /context y confirma que CLAUDE.md aparece bajo Memory files, que es la comprobación documentada para las rutas de importación y enlace simbólico.

Luego maneja la antigua solución temporal por tipo en lugar de por instinto. Deja una importación @AGENTS.md. Elimina un CLAUDE.md que simplemente le dice a Claude con palabras que lea el otro archivo, porque "Claude ve AGENTS.md solo si decide abrir el archivo". Un enlace simbólico no necesita "nada, o elimina el enlace simbólico. De cualquier manera, Claude lee el contenido una vez". Un gancho SessionStart que imprime el archivo debe eliminarse.

Se aplican dos restricciones si eliges la ruta del enlace simbólico por primera vez. Las herramientas Edit y Write "se niegan a escribir a través de un enlace simbólico", y la negativa "indica a Claude que edite el destino del enlace, AGENTS.md, en su lugar". Y en Windows, "Crear un enlace simbólico allí requiere privilegios de administrador o el modo de desarrollador, y Git descarga un enlace simbólico confirmado como un archivo de texto plano a menos que core.symlinks esté habilitado".

Los archivos de instrucciones responden a "cómo deberías trabajar aquí". No son el lugar adecuado para "qué decidimos y cuándo", y una vez que estás haciendo malabares con dos nombres de archivo y una configuración, la diferencia se vuelve más marcada. Un almacén independiente en el que escribes entradas de MemoryLake a propósito mantiene las decisiones y sus razones en un solo lugar que no depende de qué nombre de archivo ganó esta semana. Tú mismo escribes las entradas, con tus propias palabras. No se lee nada, ni se escribe, ni se elimina de los archivos o configuraciones de Anthropic.

Paso 1: Crea una clave API

Inicia sesión y genera una clave API desde la configuración de tu espacio de trabajo. Esta es la credencial que utilizan tus agentes e integraciones, así que créala antes de comenzar a mover cualquier cosa.

Paso 2: Sube tus primeras memorias

Comienza con las entradas que siempre se tienen que volver a explicar: las decisiones de arquitectura, las convenciones sobre las que discutieron una vez, las razones detrás de las restricciones que parecen arbitrarias en un archivo. Escríbelas como notas cortas e independientes en lugar de como un documento largo, para que cada una pueda recuperarse por separado.

Paso 3: Conecta tu IA y agentes

Conecta los asistentes y agentes de programación que realmente utilizas. Tu almacén permanente viajará contigo a través de las herramientas, independientemente de qué nombre de archivo de instrucciones prefiera cada herramienta este mes.

Cambia la incorporación (onboarding). Antes, "leer el CLAUDE.md" era una instrucción completa. Ahora, un colega puede clonar el mismo repositorio, ejecutar la misma versión y obtener diferentes instrucciones de proyecto porque conservó un CLAUDE.local.md de un trabajo anterior. Nada falla; las respuestas simplemente están menos informadas. Escribe el valor esperado de Project instructions en tus notas de configuración, ya que el repositorio no puede llevarlo.

Cambia lo que significa "un archivo para cada herramienta". La idea del archivo compartido sigue siendo buena, pero las reglas que lo rodean difieren según la herramienta. La documentación de dirección de Kiro, por ejemplo, establece que "los archivos AGENTS.md no admiten modos de inclusión y siempre se incluyen", el mismo nombre de archivo, un contrato de carga diferente. Si mantienes un archivo en varios agentes, el archivo se comparte pero el comportamiento no, que es la misma brecha descrita en por qué los agentes ignoran tus archivos de instrucciones.

Cambia el valor de tus notas de migración. Si ya moviste contenido a AGENTS.md siguiendo la ruta en cómo migrar CLAUDE.md a AGENTS.md, el movimiento en sí sigue siendo válido, pero el final de "mantener ambos archivos" es ahora el caso en el que solo se lee uno de ellos, por lo que ese es el paso que debes revisar primero.

Y cambia cómo interpretas una sesión silenciosa. Una sesión que no se queja no es una sesión que cargó todo, el mismo patrón que en las configuraciones en capas, donde la solución es averiguar qué capa ganó en lugar de reescribir el contenido, como en cómo reconciliar capas de CLAUDE.md en conflicto.

Pon la regla de conteo en el repositorio, no en la cabeza de alguien. Una nota cerca de la parte superior del archivo compartido que nombre los nombres de archivo que lo cancelan le ahorrará a la siguiente persona una tarde confusa.

Separa las convenciones permanentes de las decisiones con fechas. Las convenciones pertenecen al archivo que lee cada herramienta. Las decisiones, las compensaciones (trade-offs) y la razón por la que existe una restricción pertenecen a algún lugar recuperable, que es la distinción trazada en cómo convertir documentos de proyecto en memoria de IA.

Comprueba la carga una vez por entorno, no una vez por proyecto. Los casos no disponibles documentados son ambientales (proveedor, telemetría, política de ganchos, primera sesión después de la actualización), por lo que una comprobación en una máquina nueva o imagen de CI cubre cada repositorio en ella.

Mantente atento a qué más llega al inicio. Las habilidades y complementos de una cuenta de claude.ai en la que se haya iniciado sesión ahora se sincronizan en las sesiones de terminal, una segunda fuente de comportamiento permanente que ningún archivo en tu repositorio controla, adyacente a los límites descritos en cómo compartir contexto entre sesiones de Claude Code.

No asumas que otros agentes también cambiaron. La brecha entre lo que promete un archivo compartido y lo que carga cada herramienta es el mismo fallo documentado en cómo evitar que Codex omita las reglas de AGENTS.md.

Finalmente, trata el archivo como un informe (brief) en lugar de un archivo histórico. Los archivos de instrucciones largos compiten con el resto de la sesión por el espacio, y lo que sobrevive a una compactación es una pregunta aparte, cubierta en qué conservar a través de la compactación automática de Claude Code.

El titular es que Claude Code lee AGENTS.md. La parte que realmente cambiará la tarde de alguien es que lo lee solo cuando tres nombres de archivo específicos están ausentes del directorio de trabajo y de cada directorio por encima de este, que un CLAUDE.local.md personal es uno de ellos, y que la confirmación de qué archivo se cargó reside en una línea de la sesión en lugar de en la lista de /memory.

Dedica diez minutos: enumera los archivos de conteo, establece Project instructions a propósito, inicia una sesión y lee la línea de carga. Luego decide qué archivo es el informe permanente del proyecto, y guarda las decisiones que lo explican en un lugar que no cambie cuando cambie un nombre de archivo.