AGENTS.md aninhado para monorepo: estrutura ideal
Veja como dividir o AGENTS.md por serviço, evitar regras obsoletas e reduzir o contexto lido pelo agente sem instalar nada no monorepo.
O que significa um AGENTS.md aninhado num monorepo
Um AGENTS.md aninhado num monorepo significa ter um ficheiro pequeno na raiz do repositório e outro ficheiro dentro de cada diretório de serviço. O ficheiro da raiz contém as poucas regras que são válidas em todo o repositório, além de um mapa que indica onde estão os outros ficheiros. Cada ficheiro de serviço contém os comandos e as convenções aplicáveis apenas a esse diretório. Um agente que edite services/worker/queue.py lê primeiro o ficheiro da raiz e o ficheiro do worker, sem gastar contexto algum com o front end que nunca irá alterar.
Não há nada para instalar. AGENTS.md é uma convenção, e o projeto upstream afirma isso claramente:
AGENTS.md é apenas Markdown padrão. Use os títulos que quiser; o agente simplesmente analisa o texto fornecido.
É por isso que vale a pena aprender esta técnica corretamente. O formato não vai mudar sem aviso. O que causa problemas é a localização e a manutenção dos ficheiros, e ambas são da sua responsabilidade.
Por que um único AGENTS.md grande na raiz deixa de funcionar?
Um único AGENTS.md com 600 linhas na raiz de um repositório que contém uma aplicação web, um worker em segundo plano e um diretório Terraform falha de quatro formas diferentes.
Fica desatualizado, porque ninguém é responsável por ele. O engenheiro que renomeia um script de testes em apps/web está a editar ficheiros em apps/web. O AGENTS.md da raiz não faz parte desse diff, por isso nenhum revisor vê a inconsistência. Seis semanas depois, o ficheiro descreve uma etapa de build que já não existe, e a pessoa que causou o problema já se esqueceu da alteração.
Consome contexto em todas as tarefas. Estes ficheiros são carregados no início da sessão, antes de o agente saber o que lhe vai ser pedido. A documentação do Claude Code apresenta um valor concreto: "mantenha cada ficheiro CLAUDE.md abaixo de 200 linhas. Ficheiros mais longos consomem mais contexto e reduzem a adesão." O Codex deixa de combinar ficheiros de instruções quando o tamanho total atinge 32 KiB, o valor predefinido de project_doc_max_bytes. Um ficheiro da raiz que documenta quatro serviços gasta esse orçamento com três deles em todas as tarefas.
As instruções começam a contradizer-se. O diretório web exige pnpm test. O worker exige pytest -q. Quando são escritas num único ficheiro, cada regra só está correta em algumas situações, por isso o agente tem de adivinhar qual se aplica. A documentação do Claude Code descreve o resultado: "se duas instruções se contradisserem, o Claude pode escolher uma arbitrariamente." Dividir o ficheiro não impede que a outra regra entre no contexto. O Claude Code concatena todos os ficheiros de instruções que carregou, em vez de deixar que um substitua outro. Por isso, o ficheiro da raiz está sempre presente e, quando o agente abre ficheiros em apps/web e services/worker, os dois ficheiros dos diretórios ficam juntos no contexto. O que um ficheiro por diretório faz é associar cada regra ao diretório que governa. Indique o diretório no início do ficheiro, como os exemplos abaixo fazem com # apps/web, e cada comando continua a indicar onde se aplica quando vários ficheiros são carregados ao mesmo tempo. Quando uma regra que tem a certeza de ter escrito claramente continua a ser ignorada, analisar as razões pelas quais uma instrução nunca é aplicada é melhor do que reescrever o texto uma quarta vez.
Fica cheio de factos que o agente poderia ler no código. Uma árvore de diretórios, uma lista de dependências, um resumo do que cada pacote faz. A verificação /doctor do Claude Code existe para remover exatamente este conteúdo. Ela "remove conteúdo que o Claude consegue obter da base de código, como estruturas de diretórios, listas de dependências e visões gerais da arquitetura" e mantém "armadilhas, justificações e convenções que diferem das predefinições das ferramentas." Esta frase é o melhor teste que conheço para determinar se uma linha pertence realmente ao ficheiro.
O agente lê o ficheiro raiz ou apenas o mais próximo?
É aqui que muitas pessoas interpretam mal o comportamento do modelo, por isso vale a pena citar a convenção upstream em vez de a parafrasear:
Coloque outro AGENTS.md dentro de cada pacote. Os agentes leem automaticamente o ficheiro mais próximo na árvore de diretórios, por isso o ficheiro mais próximo tem precedência e cada subprojeto pode incluir instruções específicas.
E, sobre conflitos:
O AGENTS.md mais próximo do ficheiro editado prevalece; as instruções explícitas do utilizador na conversa têm precedência sobre tudo o resto.
Para muitas pessoas, "tem precedência" significa que "o ficheiro raiz é ignorado". Não é. Nas ferramentas que implementam esta convenção, todos os ficheiros no caminho desde a raiz do repositório até ao diretório de trabalho são lidos e combinados. O ficheiro mais próximo só prevalece quando dois ficheiros definem instruções diferentes sobre o mesmo assunto.
O Codex é explícito sobre o mecanismo: "O Codex concatena os ficheiros desde a raiz, separando-os com linhas em branco. Os ficheiros mais próximos do diretório atual substituem as instruções anteriores." O Claude Code percorre o mesmo caminho. No início da sessão, lê "todos os AGENTS.md e .claude/AGENTS.md no diretório de trabalho e nos diretórios acima dele", e a documentação descreve claramente o modelo de carregamento: "Todos os ficheiros descobertos são concatenados no contexto, em vez de se substituírem." Os diretórios abaixo do diretório de trabalho comportam-se de forma diferente: o Claude Code carrega o AGENTS.md de um subdiretório a pedido, "quando o Claude abre um ficheiro nesse diretório com a ferramenta Read."
Daqui resultam duas consequências práticas. O ficheiro raiz é um prefixo em todas as sessões no repositório, por isso trate cada linha como uma linha cujo custo é pago uma centena de vezes por semana. Um ficheiro por diretório não tem custo até o agente abrir um ficheiro nesse diretório, o que significa que os detalhes são baratos nesse local e devem ficar aí.
Este comportamento foi verificado com base na documentação do Codex e do Claude Code em 27 October 2026. As ferramentas implementam a convenção de formas ligeiramente diferentes e essas implementações também mudam, por isso confirme as regras de carregamento do agente utilizado pela sua equipa.
Um layout funcional para um repositório com três serviços
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 scriptsO ficheiro raiz é curto de propósito. Indica onde procurar e contém apenas as regras que se aplicam a todos os diretórios.
# 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.O ficheiro específico do diretório é onde ficam os detalhes e pode ter o tamanho que o diretório exigir.
# 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.O ficheiro do worker tem a mesma estrutura, mas conteúdo diferente: o comando de instalação, pytest -q, o motivo pelo qual o consumer tem de permanecer idempotente e a migração que tem de ser executada antes de os testes passarem. O ficheiro de infra é onde define as regras que impedem um agent de causar danos. Nunca execute terraform apply. Execute terraform plan e pare aí. Indique também o state backend que já está configurado, para que o agent não tente inicializar outro.
Repare no que não aparece em nenhum destes ficheiros: uma descrição da finalidade de cada serviço. Isso é responsabilidade das pessoas. O projeto upstream estabelece a mesma separação ao afirmar que "os ficheiros README.md são para pessoas: inícios rápidos, descrições de projetos e orientações para contribuir", enquanto o AGENTS.md contém "o contexto adicional, por vezes detalhado, de que os coding agents precisam: passos de build, testes e convenções." A separação entre AGENTS.md e um README destinado às pessoas explica essa fronteira frase a frase. Já um DESIGN.md que regista o motivo pelo qual o código tem esta estrutura aborda o terceiro ficheiro, que explica decisões em vez de comandos.
Quem atualiza o ficheiro quando o código muda?
Existe uma regra, definida no ficheiro raiz: quem altera código num diretório atualiza o AGENTS.md desse diretório no mesmo commit.
Isto funciona por uma razão mecânica, não cultural. O ficheiro específico do diretório fica no mesmo diff que o código, por isso o revisor do pull request vê ambos ao mesmo tempo. Um ficheiro raiz pertence a todos, o que significa que não pertence a ninguém, e nunca aparece no diff que alguém já está a rever.
Associe a regra a uma verificação no pull request. Ela encontra o AGENTS.md mais próximo acima de cada ficheiro alterado e indica quando esse ficheiro não foi 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"
doneNuma branch que reestruturou o cliente da API sem alterar a documentação, a saída é semelhante a esta:
note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updatedMantenha isto como um aviso, não como uma falha. Uma regra obrigatória leva as pessoas a adicionar uma linha em branco ao ficheiro para que o CI fique verde, e um ficheiro editado apenas para satisfazer um robô vale menos do que nenhum ficheiro. O aviso dá ao revisor uma pergunta para fazer. É essa parte que funciona.
Como identificar um AGENTS.md desatualizado?
Há duas verificações que pode executar hoje e um sintoma que verá durante uma sessão.
Compare a data de cada ficheiro com a data do código que ele descreve. %cs mostra a data do 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-01Uma data da documentação seis meses anterior à data do código não prova que o ficheiro esteja errado. Indica qual ficheiro deve ler primeiro. Isso é tudo o que precisa de uma verificação que demora um segundo.
Procure caminhos que já não existem. A documentação fica desatualizada de uma forma muito específica: continua a descrever código que foi eliminado. Todos os caminhos nestes ficheiros estão escritos entre crases, por isso é fácil extraí-los e testá-los.
grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
[ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
doneLeia o resultado em vez de integrar esta verificação no CI. Ela também sinaliza padrões glob como src/**/*.ts e qualquer URL que tenha colocado entre aspas, porque ambos contêm uma barra e nenhum corresponde a um ficheiro no disco. No Claude Code v2.1.283 ou posterior, /doctor prompt-audit executa uma verificação semelhante por si: procura "referências a ficheiros ou comandos que não existem" e ficheiros que se contradizem, inclui os seus ficheiros AGENTS.md por predefinição e não altera nada até lhe pedir para aplicar as edições propostas.
O sintoma durante uma sessão. O agente lê o ficheiro, tenta abrir src/api/client.ts porque o ficheiro lhe indicou esse caminho e a ferramenta devolve:
No such file or directoryEntão faz o que parece razoável e escreve o seu próprio wrapper fetch. Esse é o custo real de um ficheiro desatualizado. O agente não ignora a sua documentação. Segue a documentação, chega a um caminho que foi eliminado há três meses e recria código que já existe. Uma skill como Ponytail, que obriga o agente a fazer a menor alteração que funciona, torna menos frequente essa tendência para recriar código, mas não consegue encontrar um helper para o qual o ficheiro apontou o caminho errado.
O Claude Code lê ficheiros AGENTS.md?
Sim, desde o Claude Code v2.1.277. A regra exata é importante porque dela depende a estrutura aninhada. Confirmado na documentação em 27 October 2026: "O Claude Code pode ler AGENTS.md como instruções do projeto, por isso um repositório já configurado para outros agentes de programação funciona sem adicionar um CLAUDE.md, uma importação ou uma definição." O valor predefinido de Project instructions, claude-md-or-agents-md, lê "os seus ficheiros AGENTS.md quando não existe nenhum CLAUDE.md ou CLAUDE.local.md no seu diretório de trabalho ou acima dele." Os ficheiros aninhados também são abrangidos: o Claude lê o AGENTS.md de um subdiretório "quando o Claude abre um ficheiro nesse local com a ferramenta Read", desde que "esse subdiretório não tenha nenhum dos três ficheiros CLAUDE.md próprios". Esses três ficheiros são CLAUDE.md, .claude/CLAUDE.md e CLAUDE.local.md. Portanto, um CLAUDE.local.md pessoal em apps/web basta para impedir o carregamento de apps/web/AGENTS.md.
Isto transforma em armadilha o conselho antigo de colocar um CLAUDE.md junto de cada AGENTS.md. Com um AGENTS.md e um CLAUDE.md ou CLAUDE.local.md no seu diretório de trabalho ou acima dele, a documentação diz que o Claude lê "apenas os seus ficheiros CLAUDE.md". Um .claude/CLAUDE.md tem o mesmo efeito. Um único ficheiro auxiliar na raiz, com uma linha específica do Claude, oculta todos os AGENTS.md no caminho, e um CLAUDE.local.md pessoal faz o mesmo. Se quiser manter um deles, escreva /config e defina Project instructions como claude-md-and-agents-md. Isto lê ambos, primeiro o CLAUDE.md de cada diretório e depois o seu AGENTS.md.
Um número de versão, por si só, não confirma que funcionou. Precisa de v2.1.277 ou posterior, mas antes da v2.1.281 algumas sessões, como as executadas no Amazon Bedrock ou com a telemetria desativada, liam apenas ficheiros CLAUDE.md. Em alguns casos, a primeira sessão depois de atualizar a partir da v2.1.276 ou anterior também ignora AGENTS.md: a documentação diz que "o Claude lê AGENTS.md a partir da sessão seguinte". Por isso, verifique a própria sessão. Numa sessão interativa, o Claude Code imprime uma linha como no CLAUDE.md found; AGENTS.md loaded:, seguida do caminho. Nas versões atuais, /memory apresenta o ficheiro. Antes da v2.1.280, /memory e /context não apresentavam um AGENTS.md que o Claude tivesse lido diretamente. Nessas versões, pergunte ao Claude quais são as instruções do projeto.
A forma de importação continua correta quando o Claude não consegue ler AGENTS.md diretamente: numa versão mais antiga, numa sessão anterior à v2.1.281 no Amazon Bedrock ou com a telemetria desativada, numa sessão em que o plugin integrado que o lê está desativado ou num projeto que mantém um CLAUDE.md com Project instructions definido como claude-md. Coloque isto em services/worker/CLAUDE.md:
@AGENTS.md
## Claude Code
Use plan mode for changes under `services/worker/migrations/`.A forma com symlink é adequada quando não é necessário adicionar nada específico de uma ferramenta.
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 não apresenta nada quando é executado com sucesso, por isso verifique a listagem: apps/web/CLAUDE.md -> AGENTS.md. Em seguida, inicie uma sessão e execute /context. Os ficheiros carregados aparecem em Memory files. No Windows, um symlink requer direitos de Administrator ou Developer Mode. Além disso, o Git obtém um symlink submetido ao repositório como um ficheiro de texto simples, a menos que core.symlinks esteja ativado. Nesse caso, o clone fica com um CLAUDE.md de uma linha no lugar das instruções. Se alguém que clona o repositório trabalhar no Windows, use a importação @AGENTS.md. Se configurar qualquer uma destas soluções antes de o Claude Code ler AGENTS.md por si próprio, pode mantê-la: a documentação diz que manter a importação "nunca faz o Claude ler AGENTS.md duas vezes", e um CLAUDE.md com symlink é lido uma vez.
Há uma armadilha relacionada com isto. Depois de /compact, o CLAUDE.md da raiz do projeto é relido do disco, mas os ficheiros aninhados nos subdiretórios não são reinjetados. O Claude Code volta a carregá-los quando necessário, na próxima vez que o agente trabalhar com um ficheiro nesse diretório. A documentação explica este comportamento para ficheiros CLAUDE.md, mas não descreve separadamente a compactação para um AGENTS.md lido diretamente. Por isso, espere o mesmo comportamento para ficheiros aninhados com qualquer um dos dois nomes. Se uma regra por diretório parecer deixar de ser aplicada a meio de uma sessão longa, normalmente essa é a causa. Ler qualquer ficheiro nesse diretório volta a carregá-la.
Definições que apontam outros agentes para AGENTS.md
O Codex lê AGENTS.md nativamente. Em cada nível, verifica primeiro AGENTS.override.md, o que permite uma substituição local para um diretório sem editar o ficheiro partilhado. Para de combinar ficheiros quando o tamanho total atinge 32 KiB, o valor predefinido de project_doc_max_bytes. Esta é mais uma razão para manter o ficheiro da raiz pequeno.
O Aider usa-o através de .aider.conf.yml com a linha read: AGENTS.md.
O Gemini CLI usa-o através de .gemini/settings.json com { "context": { "fileName": "AGENTS.md" } }.
A documentação upstream regista uma renomeação compatível com versões anteriores para repositórios que ainda usam o nome singular antigo: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.
Num monorepo muito grande, a definição claudeMdExcludes do Claude Code ignora ficheiros ancestrais por caminho ou glob. Isto é útil quando o diretório de outra equipa fica acima do seu. Os padrões também se aplicam aos ficheiros AGENTS.md que o Claude Code lê.
Como isto é diferente da memória do agente ou de uma skill?
Estes mecanismos parecem semelhantes, mas falham de formas completamente diferentes. Por isso, é importante identificar com precisão qual deles pretende usar.
AGENTS.md é escrito por si, enviado para o git, revisto num pull request e igual para todas as pessoas que clonarem o repositório. A memória do agente é escrita pelo agente, armazenada fora do repositório e local a uma máquina. A documentação do Claude Code estabelece a mesma distinção: CLAUDE.md contém "Instruções e regras" que escreve, a memória automática contém "Aprendizagens e padrões" que o Claude escreve, e o diretório de memória não é partilhado entre máquinas. O teste é simples. Se um facto tiver de ser válido para um colega que faça um clone novo, não pode ficar na memória. Como a memória do agente persiste entre sessões aborda essa parte.
Uma skill é a terceira opção. AGENTS.md é contexto carregado em todas as sessões; uma skill é um procedimento carregado quando é necessário. A documentação do Claude Code apresenta uma regra útil: "Se uma entrada for um procedimento com várias etapas ou só for relevante para uma parte da base de código, mova-a para uma skill ou para uma regra limitada a um caminho." A segunda parte dessa frase corresponde exatamente ao que um AGENTS.md aninhado resolve. A primeira parte corresponde ao objetivo de skills de agente e, quando o mesmo procedimento for necessário em mais do que um repositório, deve partilhar a skill entre repositórios em vez de colar os mesmos parágrafos em dez ficheiros AGENTS.md diferentes.
O projeto upstream indica que "no momento da redação, o repositório principal da OpenAI tem 88 ficheiros AGENTS.md". Esse número resume todo o argumento. Um repositório grande não precisa de um ficheiro maior. Precisa de mais ficheiros pequenos, cada um junto do código que descreve e sob responsabilidade de quem alterou esse código pela última vez.
FAQ
Um AGENTS.md aninhado substitui o arquivo raiz ou é adicionado a ele?
Ele é adicionado. O upstream diz que "o mais próximo tem precedência", o que descreve o que acontece em caso de conflito, não o que é carregado. O Codex "concatena os arquivos da raiz para baixo, unindo-os com linhas em branco", e o Claude Code concatena todos os arquivos encontrados ao subir a partir do diretório de trabalho, em vez de substituí-los. O arquivo mais próximo vence apenas quando dois arquivos fornecem instruções diferentes sobre o mesmo assunto. Escreva as regras compartilhadas uma vez na raiz e não as repita em todos os diretórios.
Qual deve ser o tamanho do AGENTS.md raiz?
Pequeno o suficiente para você não se importar que ele seja colado no início de toda solicitação feita nesse repositório, porque é isso que acontece. A documentação do Claude Code sugere manter cada arquivo abaixo de 200 linhas e alerta que arquivos mais longos "reduzem a aderência". O Codex para de mesclar arquivos de instruções em 32 KiB combinados, por padrão. Se o arquivo raiz documenta quatro serviços, a maior parte dele é conteúdo desnecessário para qualquer tarefa individual. Mova os detalhes para arquivos específicos por diretório e deixe um mapa.
Como faço para evitar que esses arquivos fiquem desatualizados?
Coloque uma regra no arquivo raiz: quem alterar o código de um diretório atualiza o AGENTS.md desse diretório no mesmo commit. Colocar o arquivo junto ao código é o que faz a regra ser cumprida, porque a alteração então aparece no mesmo diff do pull request que uma pessoa já está analisando. Adicione um aviso no CI que associe cada caminho alterado ao AGENTS.md mais próximo acima dele e, de tempos em tempos, compare git log -1 --format=%cs em cada arquivo com o mesmo comando executado no diretório que ele documenta.
O Claude Code lê arquivos AGENTS.md?
Sim, a partir da v2.1.277. Verificado na documentação em 27 de outubro de 2026, o Claude Code lê AGENTS.md por padrão quando não há CLAUDE.md ou CLAUDE.local.md no seu diretório de trabalho ou acima dele, e lê o AGENTS.md de um subdiretório quando abre um arquivo nesse local com a ferramenta Read e esse subdiretório não tem CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md próprios. Não adicione um CLAUDE.md ao lado de cada AGENTS.md: com um deles no diretório de trabalho ou acima dele, o Claude lê "somente os arquivos CLAUDE.md". Se você também precisar de um CLAUDE.md, defina Project instructions como claude-md-and-agents-md em /config ou coloque @AGENTS.md na primeira linha. Execute /memory em uma sessão e confirme que o caminho AGENTS.md aparece na lista.
Onde coloco uma regra que só se aplica às vezes?
Não no AGENTS.md. Esse arquivo é carregado em todas as sessões, portanto cada linha dele compete pela atenção com a solicitação que você realmente digitou. Um procedimento com várias etapas, necessário apenas ocasionalmente, pertence a uma skill, que é carregada sob demanda. Uma regra que se aplica a um diretório pertence ao AGENTS.md desse diretório. Um fato que o agente pode ler diretamente no código, como a árvore de diretórios ou a lista de dependências, não pertence a nenhum dos dois.