Claude Code y AGENTS.md: por qué el tuyo no se está leyendo

Desde el 18 de septiembre medio internet repite lo mismo: Claude Code ya lee AGENTS.md. Es verdad a medias, y la mitad que falta es justo la que te afecta si ya usabas Claude Code antes de esa fecha. La versión 2.1.277 de Claude Code añadió soporte para AGENTS.md, el archivo de instrucciones que usan otros agentes de programación. Pero lo añadió como plan B, no como regla general. Si en tu proyecto ya tienes un CLAUDE.md, tu AGENTS.md sigue sin leerse. Y nadie te avisa.

Qué dice de verdad el changelog

La línea del changelog de la versión 2.1.277 lo dice entero, y casi nadie la copió completa: «in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead». En un proyecto sin CLAUDE.md. En lugar de. La documentación de memoria de Claude Code lo repite sin rodeos: por defecto, Claude lee AGENTS.md solo cuando no tienes un CLAUDE.md en tu carpeta de trabajo ni en ninguna carpeta por encima. Es un respaldo para quien llega de otra herramienta sin CLAUDE.md, no una suma. Ahora piensa en quién tiene un AGENTS.md hoy. Normalmente, equipos que trabajan con varios agentes a la vez. Y quién tiene además un CLAUDE.md: casi cualquiera que lleve unos meses con Claude Code. Para ese perfil, que es justo el que celebró la noticia, la novedad no cambia nada.

La trampa que sí me preocupa: CLAUDE.local.md

Lo que más me llamó la atención no está en el changelog, está en una nota de la documentación. Para decidir si lee o no tu AGENTS.md, Claude Code cuenta tres archivos: CLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md, en tu carpeta o en cualquiera por encima. CLAUDE.local.md es el archivo personal que muchos usamos para notas que no se suben al repositorio. La documentación lo dice literal: añadir uno en un proyecto que depende de AGENTS.md hace que Claude deje de leer AGENTS.md para ti. Traducido a un equipo real: todo funciona, alguien agrega sus notas personales en un CLAUDE.local.md y, desde ese momento, Claude deja de ver las reglas del equipo en la máquina de esa persona. No hay error ni aviso. Solo un Claude que de repente ignora las reglas del equipo. Lo que no cuenta para esa decisión, y sigue cargando junto a AGENTS.md: tu CLAUDE.md de usuario en la carpeta de inicio, el CLAUDE.md gestionado por tu organización y los archivos de .claude/rules.

Cómo saber si te está pasando

Hay una señal fácil de ver. Cuando Claude Code sí lee tu AGENTS.md en una sesión interactiva, lo dice al arrancar con una línea del tipo «no CLAUDE.md found; AGENTS.md loaded». Si tu proyecto tiene AGENTS.md y esa línea no aparece, Claude está leyendo tus CLAUDE.md y nada más. Hay tres casos más en los que tampoco se lee, según la documentación: si usas una versión anterior a la 2.1.277, si desactivaste el plugin integrado agents-md, y a veces en la primera sesión después de actualizar. En ese último caso lo lee desde la sesión siguiente.

Lo que yo haría hoy

No borraría nada todavía. Haría dos comprobaciones de un minuto:

• Mira si tienes CLAUDE.md o CLAUDE.local.md en la carpeta del proyecto o por encima. Si tienes cualquiera de los dos, tu AGENTS.md no entra por defecto.
• Decide si quieres los dos archivos a la vez. Si la respuesta es sí, hay un ajuste para eso en la configuración de Claude Code, se llama Project instructions, y uno de sus valores carga CLAUDE.md y AGENTS.md juntos.

La otra salida, que ya funcionaba antes de esta versión, es importar AGENTS.md desde tu CLAUDE.md con una línea @AGENTS.md. Según la documentación, esa importación nunca hace que se lea dos veces, uses el valor que uses. La lección que me llevo no es sobre AGENTS.md. Es sobre cómo leemos los changelogs: la noticia fue «ya lo lee», y la frase entera era «lo lee cuando no hay otra cosa». Esas dos versiones se parecen, pero no dicen lo mismo.