Tu AGENTS.md puede no existir para Claude Code

¡Hola DevExpert!

La semana pasada conté en X cómo carga Claude Code los ficheros AGENTS.md… y me equivoqué. Mario Sanoguera me avisó de que lo de las subcarpetas no era así, así que repetí la prueba con calma. Ayer lo dejé publicado en el blog con todo el detalle, y aquí te cuento lo principal.

Cómo lo medí

Puse una palabra clave distinta en cada fichero (KW_A_SUB_AGENTS, por ejemplo), monté varios proyectos de prueba combinando AGENTS.md y CLAUDE.md en la raíz y en subcarpetas, y le pedí a Claude Code en modo no interactivo que listara las palabras KW_ que tenía en el contexto. Como el modelo también se inventa cosas, lo comprobé además en el log de --debug-file y en el historial de la sesión.

Mi error de la primera vez: comprobé las subcarpetas con un cat. Y un cat no activa la carga de AGENTS.md.

Lo que sale (Claude Code 2.1.300)

AGENTS.md es un plan B. Si hay un CLAUDE.md en la carpeta donde abres la sesión o en alguna superior, se ignoran todos los AGENTS.md del proyecto. Basta un CLAUDE.md viejo de tres líneas para que tu AGENTS.md bien trabajado no exista.
Las subcarpetas se cargan más tarde, cuando Claude lee un fichero de ahí con su herramienta de lectura. Con un cat desde la terminal, no. Curiosamente, el CLAUDE.md de una subcarpeta sí se cargó tras un cat; el AGENTS.md, ni una vez.
~/.claude/AGENTS.md no se lee nunca. El único fichero global es ~/.claude/CLAUDE.md.

Todo esto lo gestiona un plugin que viene con Claude Code, cc-plugin-agents-md, con una opción de cuatro modos. Si quieres que cargue los dos ficheros a la vez, esto va en tu ~/.claude/settings.json:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

Ojo, que en los ajustes del proyecto no hace nada.

Cómo lo tengo yo

Uso Codex y Claude Code todos los días, y no quiero dos ficheros de reglas que acaben diciendo cosas distintas. Así que AGENTS.md es la fuente y CLAUDE.md, un enlace simbólico:

# En cada proyecto
ln -s AGENTS.md CLAUDE.md

# El global
ln -s ~/.codex/AGENTS.md ~/.claude/CLAUDE.md

El segundo es el que más importa: sin él, tus reglas globales de Codex no le llegan a Claude Code. Y con el enlace te da igual el modo del plugin o que alguien añada un CLAUDE.md en la raíz.

Si los enlaces simbólicos te dan guerra (en Windows, por ejemplo), un CLAUDE.md con una sola línea, @AGENTS.md, se comportó igual en todo lo que medí.

En el artículo tienes las tablas completas, los cuatro modos y los pasos para repetir la prueba con tu versión. Esto cambia rápido, así que si te sale algo distinto, respóndeme a este email.

Esta semana también:

Puse un modelo de decisión a vigilar a mi agente: el vídeo de modelos de decisión que te adelanté. Los medí con 300 frases en español: Perplexity acertó el 87% y Jev el 82%, son unas 6 veces más rápidos que un LLM, pero en coste no siempre ganan. El repo con los cuatro ejemplos está aquí.
Los proyectos finales de AI Expert: ya hay 33 publicados, con capturas, clips y repos. Desde una app para gestionar un refugio de perros hasta una skill que revisa las dependencias de un proyecto Android como lo haría un senior.

AI Expert · sexta edición, desde el 3 de noviembre. Seis semanas en directo para montar tu propio sistema de trabajo con agentes sobre tu proyecto. Hoy es el último día para entrar también en la sesión previa en grupo del 27 de octubre. Y si la paga tu empresa, se puede bonificar con FUNDAE. Toda la información aquí

Un abrazo,

Antonio