Cómo estructurar archivos AGENTS.md anidados en monorepos
Evita que el contexto de tu agente se sature con un único archivo AGENTS.md. Aprende a distribuir reglas por directorios para optimizar el rendimiento en monorepos.
Qué significa AGENTS.md anidado en un monorepo
Un archivo AGENTS.md anidado en un monorepo consiste en un archivo pequeño en la raíz del repositorio y otro archivo adicional dentro de cada directorio de servicio. El archivo raíz contiene las pocas reglas que se aplican en todas partes, además de un mapa de la ubicación de los otros archivos. Cada archivo de servicio contiene los comandos y las convenciones exclusivas para ese directorio. Un agente que edita services/worker/queue.py lee entonces el archivo raíz y el archivo del trabajador, sin gastar contexto alguno en el frontend que nunca tocará.
No hay nada que instalar. AGENTS.md es una convención, y el proyecto original lo indica claramente:
AGENTS.md es simplemente Markdown estándar. Utilice los encabezados que desee; el agente simplemente analiza el texto que usted proporciona.
Por eso vale la pena aprender esta técnica correctamente. El formato no cambiará bajo su responsabilidad. Lo que puede fallar es la ubicación y el mantenimiento, y ambos son su tarea.
¿Por qué deja de funcionar un único AGENTS.md grande en la raíz?
Un único AGENTS.md de 600 líneas en la raíz de un repositorio que contiene una aplicación web, un worker en segundo plano y un directorio de Terraform falla de cuatro formas distintas.
Queda obsoleto porque nadie es responsable de mantenerlo. El ingeniero que cambia el nombre de un script de pruebas en apps/web está editando archivos bajo apps/web. El AGENTS.md de la raíz no forma parte de ese diff, por lo que ningún revisor ve la discrepancia. Seis semanas después, el archivo describe un paso de compilación que ya no existe y la persona que introdujo el problema ha olvidado el cambio.
Consume contexto en todas las tareas. Estos archivos se cargan al inicio de la sesión, antes de que el agente sepa qué se le va a pedir. La documentación de Claude Code da una cifra concreta: "mantenga menos de 200 líneas por archivo CLAUDE.md. Los archivos más largos consumen más contexto y reducen el cumplimiento". Codex deja de combinar archivos de instrucciones cuando su tamaño total alcanza 32 KiB, el valor predeterminado de project_doc_max_bytes. Un archivo raíz que documenta cuatro servicios consume ese presupuesto con tres de ellos en cada tarea.
Las instrucciones empiezan a contradecirse. El directorio web requiere pnpm test. El worker requiere pytest -q. Al escribirlas en un solo archivo, cada regla sólo es correcta en algunos casos, así que el agente tiene que adivinar cuál se aplica. La documentación de Claude Code describe el resultado: "si dos instrucciones se contradicen, Claude puede elegir una de forma arbitraria". Dividir el archivo no mantiene la otra regla fuera del contexto. Claude Code concatena todos los archivos de instrucciones que ha cargado en lugar de permitir que uno sustituya a otro. Por eso, el archivo raíz siempre está presente y, cuando el agente ha abierto archivos en apps/web y services/worker, los dos archivos de directorio permanecen juntos en el contexto. Lo que hace un archivo por directorio es vincular cada regla al directorio que gobierna. Indique el directorio en la parte superior del archivo, como hacen los ejemplos siguientes con # apps/web, para que cada comando siga indicando dónde se aplica cuando se cargan varios archivos a la vez. Cuando una regla que está seguro de haber escrito con claridad se omite de todos modos, revisar los motivos por los que una instrucción nunca se aplica resulta más útil que reescribirla por cuarta vez.
Se llena de datos que el agente podría leer del código. Un árbol de directorios, una lista de dependencias y un resumen de la función de cada paquete. La comprobación /doctor de Claude Code existe para eliminar exactamente este contenido. "Elimina el contenido que Claude puede deducir del código base, como diseños de directorios, listas de dependencias y descripciones generales de la arquitectura" y conserva "los problemas conocidos, la justificación y las convenciones que difieren de los valores predeterminados de las herramientas". Esa frase es la mejor prueba que conozco para decidir si una línea debe formar parte del archivo.
¿El agente lee el archivo raíz o sólo el más cercano?
Aquí es donde la mayoría interpreta mal el comportamiento del modelo, por lo que conviene citar la convención original en lugar de parafrasearla:
Coloque otro AGENTS.md dentro de cada paquete. Los agentes leen automáticamente el archivo más cercano en el árbol de directorios, por lo que el más próximo tiene prioridad y cada subproyecto puede incluir instrucciones adaptadas.
Y sobre los conflictos:
El AGENTS.md más cercano al archivo editado tiene prioridad; las instrucciones explícitas del usuario en el chat prevalecen sobre todo lo demás.
Para muchas personas, «tiene prioridad» significa que «el archivo raíz se ignora». No es así. En las herramientas que implementan esta convención, se lee cada archivo del recorrido desde la raíz del repositorio hasta el directorio de trabajo, y luego se combinan. El archivo más cercano sólo tiene prioridad cuando dos archivos indican cosas diferentes sobre el mismo tema.
Codex explica el mecanismo de forma explícita: «Codex concatena los archivos desde la raíz hacia abajo y los separa con líneas en blanco. Los archivos más cercanos al directorio actual sustituyen las instrucciones anteriores». Claude Code recorre el mismo camino. Al iniciar la sesión, lee «cada AGENTS.md y .claude/AGENTS.md del directorio de trabajo y de los directorios superiores», y su documentación describe claramente el modelo de carga: «Todos los archivos descubiertos se concatenan en el contexto, en lugar de sustituirse entre sí». Los directorios por debajo del directorio de trabajo funcionan de otra forma: Claude Code carga el AGENTS.md de un subdirectorio bajo demanda, «cuando Claude abre allí un archivo con la herramienta Read».
De aquí se derivan dos consecuencias prácticas. El archivo raíz es un prefijo de todas las sesiones del repositorio, por lo que cada línea que contiene se procesa muchas veces a la semana. Un archivo específico de un directorio no consume recursos hasta que el agente abre un archivo de ese directorio. Por eso, el detalle es barato allí y debe colocarse allí.
Este comportamiento se comprobó con la documentación de Codex y Claude Code el 27 de octubre de 2026. Las herramientas implementan la convención de forma ligeramente diferente y pueden cambiarla, así que confirme las reglas de carga de cualquier agente que utilice su equipo.
Un diseño funcional para un repositorio con tres servicios
repo/
AGENTS.md rules true everywhere, plus the map
apps/web/AGENTS.md TypeScript client, Vite, Vitest
services/worker/AGENTS.md Python queue consumer, pytest
infra/AGENTS.md Terraform and the deploy scriptsEl archivo raíz es breve a propósito. Indica dónde buscar y contiene únicamente las reglas que se aplican en todos los directorios.
# AGENTS.md
This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.
- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts
## Rules for the whole repository
- The package manager is `pnpm`. `npm install` writes a second lockfile
that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
`schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
in the same commit.El archivo por directorio es donde se detallan los pormenores, y puede ser tan extenso como el directorio lo requiera.
# apps/web
Browser client. Vite and React, TypeScript with `strict` on.
## Commands
- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.
## Conventions
- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
because the client attaches the auth header and retries on 429.
## Traps
- `pnpm build` does not type check. Vite strips the types instead of
checking them, so a broken type still produces a green build.
Run `pnpm typecheck` as a separate step.El archivo de trabajo tiene la misma estructura pero con contenido distinto: el comando de instalación, pytest -q, la razón por la que el consumidor debe ser idempotente y la migración que debe ejecutarse antes de que las pruebas sean exitosas. El archivo de infraestructura es donde se escriben las reglas que impiden que un agente cause daños. Nunca ejecute terraform apply. Ejecute terraform plan y deténgase ahí, especificando el backend de estado que ya está configurado para que el agente no intente inicializar uno nuevo.
Observe lo que no figura en ninguno de estos archivos: una descripción de la finalidad de cada servicio. Eso corresponde a los humanos. Upstream establece el mismo límite al afirmar que "los archivos README.md son para humanos: inicios rápidos, descripciones de proyectos y directrices de contribución", mientras que AGENTS.md contiene "el contexto adicional, a veces detallado, que necesitan los agentes de programación: pasos de compilación, pruebas y convenciones". La división entre AGENTS.md y un README orientado a humanos recorre frase por frase ese límite, y un archivo DESIGN.md que registra por qué el código tiene la forma que tiene cubre el tercer archivo, aquel que explica las decisiones en lugar de los comandos.
¿Quién actualiza el archivo cuando cambia el código?
Existe una regla, y debe incluirse en el archivo raíz: quien modifique código en un directorio debe actualizar el archivo AGENTS.md de dicho directorio en el mismo commit.
Esto funciona por una razón mecánica, no cultural. El archivo por directorio aparece en el mismo diff que el código, por lo que el revisor de la pull request ve ambos al mismo tiempo. Un archivo raíz pertenece a todos, lo que significa que no pertenece a nadie, y nunca aparece en el diff que alguien esté leyendo.
Refuerce esta regla con una comprobación en la pull request. Esta busca el archivo AGENTS.md más cercano por encima de cada archivo modificado y notifica si dicho archivo no fue alterado.
#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)
nearest_doc() {
d=$(dirname "$1")
while [ "$d" != "." ]; do
if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
d=$(dirname "$d")
done
echo "AGENTS.md"
}
printf '%s\n' "$changed" | while read -r f; do
[ -n "$f" ] || continue
case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
doc=$(nearest_doc "$f")
printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
echo "note: $f changed but $doc was not updated"
doneEn una rama que modificó el cliente de la API sin tocar la documentación, el resultado se muestra así:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedManténgalo como una advertencia en lugar de un error bloqueante. Un bloqueo estricto enseña a los usuarios a añadir una línea en blanco al archivo solo para que el CI pase, y un archivo editado para satisfacer a un robot vale menos que no tener archivo alguno. La advertencia le da al revisor una pregunta que plantear, que es la parte que realmente funciona.
¿Cómo detectar que un archivo AGENTS.md ha quedado obsoleto?
Puede ejecutar dos comprobaciones hoy mismo y observar un síntoma dentro de una sesión.
Compare la antigüedad de cada archivo con la antigüedad del código que describe. %cs muestra la fecha del commit como YYYY-MM-DD.
for f in $(git ls-files '*AGENTS.md'); do
d=$(dirname "$f")
printf '%s doc:%s code:%s\n' "$f" \
"$(git log -1 --format=%cs -- "$f")" \
"$(git log -1 --format=%cs -- "$d")"
doneapps/web/AGENTS.md doc:2026-02-11 code:2026-08-07
services/worker/AGENTS.md doc:2026-07-29 code:2026-08-09
infra/AGENTS.md doc:2026-08-01 code:2026-08-01Que la fecha de la documentación sea seis meses anterior a la del código no demuestra que el archivo sea incorrecto. Indica qué archivo debe leer primero. Eso es todo lo que necesita de una comprobación que tarda un segundo.
Busque rutas que ya no existan. La documentación se degrada de una forma muy concreta: sigue describiendo código que se eliminó. Todas las rutas de estos archivos están escritas entre comillas invertidas, por lo que es fácil extraerlas y comprobarlas.
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneLea el resultado en lugar de integrar esta comprobación en CI. También marca patrones glob como src/**/*.ts y cualquier URL que haya citado, porque ambos contienen una barra y ninguno corresponde a un archivo del disco. En Claude Code v2.1.283 o posterior, /doctor prompt-audit realiza una comprobación similar: busca "referencias a archivos o comandos que no existen" y archivos que se contradicen entre sí, incluye AGENTS.md de forma predeterminada y no cambia nada hasta que le pida aplicar las ediciones que propone.
El síntoma dentro de una sesión. El agente lee el archivo, intenta abrir src/api/client.ts porque el archivo se lo indica y la herramienta devuelve:
No such file or directoryPor eso hace lo razonable y escribe su propio contenedor fetch. Ese es el coste real de un archivo obsoleto. El agente no ignora la documentación. Sigue la documentación, llega a una ruta que se eliminó hace tres meses y vuelve a crear código que usted ya tiene. Una skill como Ponytail, que obliga al agente a aplicar el cambio mínimo que funciona, hace menos frecuente ese impulso de reconstruir, pero no puede encontrar un helper al que el archivo apuntaba en el lugar equivocado.
¿Claude Code lee archivos AGENTS.md?
Sí, desde Claude Code v2.1.277, y la regla exacta importa porque de ella depende la estructura anidada. Comprobado con la documentación el 27 de octubre de 2026: «Claude Code puede leer AGENTS.md como instrucciones del proyecto, por lo que un repositorio ya configurado para otros agentes de programación funciona sin añadir un CLAUDE.md, una importación ni un ajuste». El valor predeterminado de Project instructions, claude-md-or-agents-md, lee «tus archivos AGENTS.md cuando no tienes ningún CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo o por encima de él». También se incluyen los archivos anidados: Claude lee el AGENTS.md de un subdirectorio «cuando Claude abre allí un archivo con la herramienta Read», siempre que «ese subdirectorio no tenga ninguno de los tres archivos CLAUDE.md propios». Esos tres son CLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md, así que un CLAUDE.local.md personal en apps/web basta para impedir que apps/web/AGENTS.md se cargue.
Esto convierte en una trampa el antiguo consejo de poner un CLAUDE.md junto a cada AGENTS.md. Con un AGENTS.md y un CLAUDE.md o CLAUDE.local.md en tu directorio de trabajo o por encima de él, la documentación indica que Claude lee «sólo tus archivos CLAUDE.md». Un .claude/CLAUDE.md funciona de la misma manera. Un único archivo complementario en la raíz que contenga una sola línea específica para Claude oculta todos los AGENTS.md de la ruta, y un CLAUDE.local.md personal produce el mismo efecto. Si quieres conservar uno, escribe /config y establece Project instructions en claude-md-and-agents-md, que lee ambos: primero el CLAUDE.md de cada directorio y después su AGENTS.md.
Un número de versión por sí solo no confirma que haya funcionado. Necesitas v2.1.277 o posterior, pero antes de v2.1.281 algunas sesiones, como las de Amazon Bedrock o las que tienen la telemetría desactivada, sólo leían archivos CLAUDE.md, y en algunos casos la primera sesión después de actualizar desde v2.1.276 o anterior también omite AGENTS.md: la documentación indica que «Claude lee AGENTS.md a partir de tu siguiente sesión». Por eso debes comprobar la propia sesión. En una sesión interactiva, Claude Code muestra una línea como no CLAUDE.md found; AGENTS.md loaded: seguida de la ruta, y en las versiones actuales /memory muestra el archivo. Antes de v2.1.280, /memory y /context no mostraban un AGENTS.md que Claude hubiera leído directamente, así que en esas versiones pregunta a Claude cuáles son sus instrucciones del proyecto.
La forma de importación sigue siendo adecuada cuando Claude no puede leer AGENTS.md directamente: una versión antigua, una sesión anterior a v2.1.281 en Amazon Bedrock o con la telemetría desactivada, una sesión en la que el plugin integrado que lo lee está desactivado o un proyecto que conserva un CLAUDE.md con Project instructions establecido en claude-md. Pon esto en services/worker/CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.La forma con enlace simbólico es adecuada cuando no hay nada específico de una herramienta que añadir.
git ls-files '*AGENTS.md' | while read -r f; do
ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.mdln no muestra nada cuando termina correctamente, así que comprueba el listado: apps/web/CLAUDE.md -> AGENTS.md. Después inicia una sesión y ejecuta /context; los archivos cargados aparecen bajo Memory files. En Windows, un enlace simbólico necesita permisos de Administrador o Developer Mode, y Git comprueba un enlace simbólico confirmado en el repositorio sacándolo en el disco como un archivo de texto normal a menos que core.symlinks esté habilitado, lo que deja en ese clon un CLAUDE.md de una sola línea en lugar de tus instrucciones. Si alguna persona que clone el repositorio trabaja en Windows, usa la importación @AGENTS.md. Si configuraste cualquiera de estas soluciones antes de que Claude Code leyera AGENTS.md por sí solo, puedes dejarla: la documentación indica que conservar la importación «nunca hace que Claude lea AGENTS.md dos veces», y un CLAUDE.md enlazado se lee una vez.
Hay otra trampa relacionada con esto. Después de /compact, el CLAUDE.md de la raíz del proyecto se vuelve a leer del disco, pero los archivos anidados de los subdirectorios no se vuelven a inyectar. Claude Code los recarga bajo demanda, la próxima vez que el agente trabaje con un archivo de ese directorio. La documentación lo especifica para los archivos CLAUDE.md y no describe la compactación por separado para un AGENTS.md leído directamente, así que debes esperar este comportamiento con los archivos anidados de cualquiera de los dos nombres. Si una regla por directorio parece dejar de aplicarse a mitad de una sesión larga, normalmente esa es la causa; leer cualquier archivo del directorio la vuelve a cargar.
Ajustes que indican a otros agentes que usen AGENTS.md
Codex lee AGENTS.md de forma nativa. En cada nivel comprueba primero AGENTS.override.md, lo que permite aplicar una sobrescritura local a un directorio sin editar el archivo compartido. Deja de combinar archivos cuando el tamaño combinado alcanza 32 KiB, el valor predeterminado de project_doc_max_bytes, lo que constituye otra razón para mantener pequeño el archivo raíz.
Aider lo usa mediante .aider.conf.yml con la línea read: AGENTS.md.
Gemini CLI lo usa mediante .gemini/settings.json con { "context": { "fileName": "AGENTS.md" } }.
La documentación de Upstream incluye un cambio de nombre compatible con versiones anteriores para los repositorios que todavía usan el nombre singular anterior: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
En un monorepo muy grande, el ajuste claudeMdExcludes de Claude Code omite los archivos de los directorios superiores por ruta o patrón glob, lo que resulta útil cuando el directorio de otro equipo se encuentra por encima del tuyo. Sus patrones también se aplican a los archivos AGENTS.md que lee Claude Code.
¿En qué se diferencia esto de la memoria del agente o de una habilidad?
Estos mecanismos parecen similares pero fallan de formas completamente distintas, por lo que es importante ser preciso sobre cuál de ellos está utilizando.
AGENTS.md es escrito por usted, enviado a git, revisado en un pull request e idéntico para cualquiera que clone el repositorio. La memoria del agente es escrita por el agente, almacenada fuera del repositorio y local a una sola máquina. La documentación de Claude Code traza la misma línea: CLAUDE.md contiene "Instrucciones y reglas" que usted escribe, la memoria automática contiene "Aprendizajes y patrones" que Claude escribe, y el directorio de memoria no se comparte entre máquinas. La prueba es sencilla. Si un hecho debe ser cierto para un colega en un clon nuevo, no puede residir en la memoria. Cómo persiste la memoria del agente entre sesiones cubre esa parte del panorama.
Una habilidad es el tercer elemento. AGENTS.md es contexto que se carga en cada sesión; una habilidad es un procedimiento que se carga cuando es necesario. La documentación de Claude Code ofrece una regla útil: "Si una entrada es un procedimiento de varios pasos o solo importa para una parte del código, muévala a una habilidad o a una regla con alcance de ruta". La segunda mitad de esa frase es precisamente lo que resuelve un AGENTS.md anidado. La primera mitad es para lo que sirven las habilidades del agente, y cuando el mismo procedimiento es necesario en más de un repositorio, comparta la habilidad entre repositorios en lugar de pegar los mismos párrafos en diez archivos AGENTS.md diferentes.
Upstream señala que "en el momento de escribir este artículo, el repositorio principal de OpenAI tiene 88 archivos AGENTS.md". Esa cifra es todo el argumento. Un repositorio grande no necesita un archivo más grande. Necesita más archivos pequeños, cada uno ubicado junto al código que describe, y cada uno bajo la responsabilidad de quien haya modificado ese código por última vez.
FAQ
¿Un archivo AGENTS.md anidado sustituye al archivo raíz o se suma a él?
Se suma a él. Upstream indica que «el más cercano tiene prioridad», lo que describe lo que ocurre cuando hay un conflicto, no qué archivos se cargan. Codex «concatena los archivos desde la raíz hacia abajo, uniéndolos con líneas en blanco», y Claude Code concatena todos los archivos que encuentra al subir desde el directorio de trabajo, en lugar de sustituirlos. El archivo más cercano sólo tiene prioridad cuando dos archivos dan instrucciones diferentes sobre el mismo asunto. Escriba las reglas compartidas una sola vez en la raíz y no las repita en cada directorio.
¿Qué tamaño debería tener el AGENTS.md raíz?
Debe ser lo bastante pequeño como para que no le importe pegarlo al principio de cada solicitud que haga en ese repositorio, porque eso es lo que ocurre. La documentación de Claude Code recomienda mantener cada archivo por debajo de 200 líneas y advierte que los archivos más largos «reducen el cumplimiento». Codex deja de combinar archivos de instrucciones al alcanzar 32 KiB en conjunto de forma predeterminada. Si el archivo raíz documenta cuatro servicios, la mayor parte será innecesaria para cualquier tarea concreta. Traslade los detalles a archivos por directorio y deje un mapa.
¿Cómo evito que estos archivos queden obsoletos?
Añada una regla en el archivo raíz: quien cambie código en un directorio actualiza el AGENTS.md de ese directorio en el mismo commit. Colocar el archivo junto al código hace que la regla se cumpla, porque el cambio queda incluido en el diff de la misma pull request que ya está revisando una persona. Añada una advertencia de CI que asocie cada ruta modificada con el AGENTS.md más cercano situado por encima, y compare periódicamente git log -1 --format=%cs en cada archivo con el mismo comando ejecutado en el directorio que documenta.
¿Claude Code lee los archivos AGENTS.md?
Sí, desde v2.1.277. Según la documentación comprobada el 27 de octubre de 2026, Claude Code lee AGENTS.md de forma predeterminada cuando no hay ningún CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo o por encima de él, y lee el AGENTS.md de un subdirectorio cuando abre un archivo situado allí con la herramienta Read y ese subdirectorio no tiene ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md propio. No añada un CLAUDE.md junto a cada AGENTS.md: cuando hay uno en el directorio de trabajo o por encima de él, Claude lee «sólo sus archivos CLAUDE.md». Si también necesita un CLAUDE.md, establezca Project instructions en claude-md-and-agents-md en /config, o coloque @AGENTS.md en su primera línea. Ejecute /memory en una sesión y confirme que la ruta AGENTS.md aparece en la lista.
¿Dónde coloco una regla que sólo importa a veces?
No en AGENTS.md. Ese archivo se carga en todas las sesiones, por lo que cada línea compite por la atención con la solicitud que acaba de escribir. Un procedimiento de varios pasos que se necesita ocasionalmente debe estar en una skill, que se carga bajo demanda. Una regla que se aplica a un solo directorio debe estar en el AGENTS.md de ese directorio. Un dato que el agente puede leer directamente del código, como el árbol de directorios o la lista de dependencias, no debe estar en ninguno de los dos.