O que deve ir no AGENTS.md e no CLAUDE.md?
Saiba o que pôr no AGENTS.md e no CLAUDE.md com base em benchmarks de agentes: comandos úteis, restrições operacionais, armadilhas dispendiosas e o que omitir.
Um ficheiro de instruções de um repositório pode facilmente transformar-se num README comprimido, num ensaio sobre arquitetura e numa lista de princípios de engenharia admiráveis. O agente recebe depois todo esse material em cada tarefa – mesmo quando a maior parte é irrelevante.
Resultados recentes de benchmarks sugerem um papel mais restrito para estes
ficheiros. Use o AGENTS.md e o CLAUDE.md como manuais de operação curtos:
comandos exatos, operações dispendiosas, passos de verificação, limites e
factos difíceis de inferir a partir do código. Não espere que uma descrição mais
longa do projeto forneça um discernimento de engenharia que o modelo ainda não
tem.
Resposta rápida
Ponha um facto no ficheiro de instruções da raiz quando se verificarem as três condições:
- Aplica-se à maior parte do trabalho nesse âmbito.
- O agente não o consegue descobrir de forma rápida e fiável a partir do repositório.
- Segui-lo muda uma ação ou uma verificação observável.
Bons exemplos:
pnpm test --filter apié o comando de testes rápido para alterações na API.- A suite de integração completa demora 25 minutos e deve correr uma única vez, depois de os testes direcionados passarem.
- Os ficheiros em
generated/têm de ser alterados através depnpm generate. - Adicionar uma dependência de produção ou alterar uma migração da base de dados exige confirmação.
- Uma alteração só está concluída quando a verificação de tipos e o teste focado relevante passam.
Deixe de fora afirmações genéricas como «escreve código limpo», listas de pacotes copiadas e descrições que o agente consegue obter ao ler o manifesto e a árvore do código-fonte. Use o prompt da tarefa para requisitos pontuais, uma skill para um procedimento a pedido e testes, hooks ou CI para regras que têm de ser aplicadas mecanicamente.
AGENTS.md e CLAUDE.md são parecidos, mas não idênticos
Ambos os ficheiros fornecem instruções persistentes para o repositório, mas as regras de descoberta e de âmbito dependem do agente que os lê.
AGENTS.md do Codex |
CLAUDE.md do Claude Code |
|
|---|---|---|
| Ficheiro de projeto na raiz | AGENTS.md |
CLAUDE.md ou .claude/CLAUDE.md |
| Predefinições pessoais | ~/.codex/AGENTS.md |
~/.claude/CLAUDE.md |
| Orientações mais específicas | AGENTS.md aninhado ou AGENTS.override.md |
CLAUDE.md aninhado ou .claude/rules/ com âmbito por caminho |
| Como os ficheiros se combinam | Cadeia da raiz até ao diretório de trabalho; os ficheiros mais próximos aplicam-se depois | Os ficheiros dos diretórios superiores são carregados no arranque; os aninhados, quando o Claude trabalha nessa subárvore |
| Orientação atual sobre o tamanho | Limite de descoberta combinado de 32 KiB por omissão | A Anthropic recomenda menos de 200 linhas por ficheiro |
O Codex constrói a cadeia de instruções uma vez por execução ou por sessão TUI iniciada. Verifica as orientações globais e depois percorre os diretórios desde a raiz do projeto até ao diretório de trabalho atual. Um ficheiro mais próximo aparece mais tarde no prompt combinado e, por isso, sobrepõe-se às orientações mais gerais. A ordem exata de descoberta e o comportamento de substituição estão descritos na documentação do AGENTS.md do Codex.
O Claude Code trata o CLAUDE.md como contexto e não como configuração imposta.
A documentação recomenda instruções específicas e concisas e explica que
ficheiros grandes ou contraditórios reduzem o grau de cumprimento. Consulte
How Claude remembers your project.
Se uma equipa usa os dois agentes, mantenha as instruções partilhadas no
AGENTS.md e importe-as a partir de um pequeno CLAUDE.md:
@AGENTS.md
## Claude Code only
- Use the path-scoped rule in `.claude/rules/frontend.md` for UI changes.
A Anthropic documenta este padrão de importação de forma explícita. Uma ligação simbólica também pode funcionar, mas a importação deixa espaço para algumas orientações específicas do Claude e é mais portátil no Windows.
O que testou o estudo mais recente com dois agentes
O preprint de julho de 2026 Do Context Files Help Coding Agents? transformou pull requests já integrados de três repositórios Python – PDM, firebase-admin-python e opshin – em 17 tarefas de programação. A descrição do PR serviu de prompt, enquanto os testes introduzidos pelo PR real ficaram ocultos e serviram para avaliar a implementação do agente.
O Claude Code e o Codex trabalharam, cada um, em três condições:
- sem contexto: nenhum ficheiro de contexto do repositório;
- sempre ativo: o
AGENTS.mdcompleto era inserido em cada turno; - seletivo: o agente recebia uma indicação e podia ler ficheiros de uma wiki organizada por temas quando precisasse.
Após três repetições, 288 execuções tinham resultados de correção válidos:
| Estratégia | Claude Code | Codex |
|---|---|---|
| Sem contexto | 53,3% | 58,8% |
| Sempre ativo | 55,6% | 56,9% |
| Seletivo | 55,6% | 52,9% |
As diferenças não foram estatisticamente significativas. Na revisão manual dos
autores, as tentativas que ficaram perto de passar falharam por causa do
desenho da funcionalidade, da escolha de padrões ou de ligações mal feitas entre
componentes – e não por faltar um facto do repositório que o AGENTS.md real
contivesse. Acrescentar ou reorganizar esse contexto não transformou essas
falhas em sucessos.
Esse resultado não prova que os ficheiros de instruções nunca melhoram a correção. A amostra contém apenas três repositórios Python e 15–17 tarefas por agente. A análise de potência estatística do artigo estima que detetar um efeito de 10 pontos percentuais exigiria cerca de 120–200 tarefas. O estudo também testou uma injeção mais forte e artificial, em vez de simplesmente deixar um ficheiro no seu local natural no espaço de trabalho: o Claude recebeu o texto acrescentado ao prompt de sistema, enquanto o Codex o recebeu colocado antes do prompt do utilizador.
A condição seletiva tem outra limitação. A sua wiki só correspondia ao
AGENTS.md original no caso do opshin; os outros dois repositórios receberam
wikis geradas mais abrangentes, cerca de 10 e 18 vezes mais longas. A
recuperação seletiva não é, portanto, uma comparação limpa do mesmo conteúdo
entregue de outra forma.
O resultado útil foi operacional
O AGENTS.md do opshin diz que a suite de testes completa demora mais de 20
minutos. Sem esse aviso, o Claude correu a suite inteira, em média, 3,67 vezes
por célula. Com o contexto sempre ativo, correu-a 2,44 vezes; com o contexto
seletivo, 1,67. O tempo médio de execução desceu de 2689 segundos para 2066 e
2032 segundos – uma redução de cerca de 24% – sem nenhuma melhoria
correspondente na correção.
São bons indícios a favor de um tipo concreto de instrução: dizer ao agente quanto custa uma ação e dar-lhe um caminho correto mais barato. Não são uma prova geral de execução mais rápida. A análise foi exploratória, abrangeu o Claude num único repositório e, com cinco tarefas, tinha pouca potência estatística. A duração do Codex manteve-se estável, e outro repositório variou ligeiramente no sentido oposto.
A conclusão prudente é:
Um ficheiro de instruções do repositório pode melhorar a forma como um agente trabalha, mesmo quando não melhora aquilo que o agente consegue resolver.
No panorama mais amplo, os dados são díspares
Dois estudos anteriores, também de 2026, chegaram a resultados diferentes quanto à eficiência:
- On the Impact of AGENTS.md Files
estudou 10 repositórios e 124 pull requests. A presença do
AGENTS.mdesteve associada a um tempo de execução mediano 28,64% inferior e a 16,58% menos tokens de saída, com um comportamento comparável na conclusão das tarefas. - Evaluating AGENTS.md testou ficheiros gerados e escritos por programadores com vários agentes e modelos. Não encontrou nenhuma melhoria geral no sucesso das tarefas e registou, em média, um custo de inferência mais de 20% superior, embora os agentes tenham seguido instruções fora do comum.
O novo artigo com dois agentes sugere que a contradição pode explicar-se pelas diferenças na mecânica de injeção e pela dificuldade das tarefas, que varia de agente para agente. É uma hipótese, não uma conciliação definitiva. Tendo em conta os três artigos, a prática mais defensável é avaliar um ficheiro pelo comportamento que muda, em vez de partir do princípio de que mais contexto é melhor.
O que deve constar de um ficheiro de contexto útil
Comandos exatos e o caminho rápido
Indique comandos prontos a executar, incluindo o diretório de trabalho correto e as flags úteis. Distinga a verificação direcionada da suite final, mais dispendiosa:
## Verification
- API change: run `pnpm test --filter api` first.
- Type check: run `pnpm typecheck` after changing TypeScript.
- Full suite: `pnpm test`; takes about 18 minutes, so run it once after focused tests pass.
«Executa os testes» acrescenta pouco. Indicar o comando certo, o custo e a ordem acaba com as suposições.
Limites com uma razão ou uma alternativa segura
Registe as áreas não óbvias que o agente não deve modificar diretamente:
## Boundaries
- Do not edit `src/generated/`; change the schema and run `pnpm generate`.
- Ask before adding a production dependency.
- Do not rewrite an existing migration; add a new migration instead.
Um caminho seguro é mais útil do que uma simples proibição.
Invariantes específicos do repositório
Inclua convenções que sejam importantes, surpreendentes e não impostas mecanicamente. Por exemplo, uma regra invulgar de mapeamento de erros, um requisito de compatibilidade que os testes não cobrem ou o único serviço que tem de usar um comando diferente.
Ponha os factos específicos de um serviço num ficheiro de instruções aninhado ou numa regra com âmbito por caminho. Carregar detalhes do frontend em todas as tarefas de backend gasta contexto e aumenta a probabilidade de conflitos.
Erros recorrentes, não hipotéticos
Acrescente uma regra quando um agente repete o mesmo erro dispendioso ou quando uma revisão deteta um facto que o agente não podia razoavelmente inferir. Remova a regra quando o repositório ou as ferramentas a tornarem obsoleta. Assim, o ficheiro mantém-se assente em falhas observadas, em vez de acumular conselhos especulativos.
O que deixar de fora
- Personas genéricas: «És um engenheiro sénior» não foi avaliado diretamente por estes estudos, mas não fornece nenhuma ação verificável nem nenhum facto do repositório.
- Ideais vagos: «Segue os princípios SOLID» ou «escreve código limpo» deixam o agente a inferir a mesma decisão de design que já ia tomar.
- Um segundo README: descreva apenas a estrutura que é surpreendente ou que determina onde deve ser feita uma alteração.
- Inventários completos de dependências: o manifesto está mais atualizado e é mais fácil de inspecionar pelo agente.
- Requisitos pontuais de uma tarefa: mantenha-os no prompt da tarefa, para que não influenciem sessões não relacionadas.
- Regras que as ferramentas conseguem impor: formatadores, verificações de tipos, testes, hooks e CI são mais robustos do que instruções escritas para requisitos determinísticos.
- Segredos ou credenciais pessoais: um ficheiro de instruções é contexto normal do projeto, não um cofre de segredos.
Um modelo inicial compacto
# Repository instructions
## Fast path
- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm test --filter <changed-package>`
- Full suite: `pnpm test` (about 20 minutes; run after focused tests pass)
## Verification
- Run `pnpm typecheck` after TypeScript changes.
- Add or update a focused test when behavior changes.
## Boundaries
- Do not edit `generated/`; run `pnpm generate` from the schema.
- Ask before adding production dependencies or changing migrations.
## Known traps
- Tests under `integration/` require the local database started with `pnpm db:up`.
- Package-specific instructions live in that package's nested `AGENTS.md`.
Substitua cada exemplo por um facto do repositório real. Um ficheiro de dez linhas, mas exato, é melhor do que um modelo exaustivo cheio de predefinições genéricas.
Escolha o mecanismo duradouro mais pequeno
| Informação | Melhor sítio |
|---|---|
| Aplica-se à maior parte das tarefas do repositório | AGENTS.md ou CLAUDE.md na raiz |
| Aplica-se apenas a uma subárvore | Ficheiro de instruções aninhado ou regra com âmbito por caminho |
| Preferência pessoal em todos os repositórios | Ficheiro de instruções ao nível do utilizador |
| Procedimento de vários passos necessário para certas tarefas | Uma skill a pedido |
| Requisito apenas desta tarefa | O prompt da tarefa |
| Regra que tem sempre de ser executada | Teste, formatador, hook, política ou CI |
Para instalar e manter procedimentos a pedido em vários agentes, consulte o guia prático do skills.sh. Um ficheiro de instruções não deve tornar-se um substituto de todos os outros mecanismos de controlo.
Avalie o ficheiro no seu próprio repositório
As médias da investigação não lhe podem dizer se uma instrução ajuda a sua base de código. Escolha uma tarefa repetível em que a instrução deva mudar o comportamento e faça várias tentativas com e sem ela, com o mesmo agente e a mesma versão do modelo. Registe:
- os resultados de testes ocultos ou escritos de forma independente;
- as execuções direcionadas e da suite completa;
- o tempo decorrido e o consumo de tokens;
- as alterações de ficheiros e os pedidos de permissão desnecessários;
- se o agente seguiu a regra específica.
Mantenha uma instrução quando esta melhora um resultado ou evita um desperdício mensurável. Reescreva-a ou remova-a quando for ignorada, estiver duplicada ou desatualizada, ou apenas tornar o prompt mais longo. O objetivo não é o ficheiro de contexto perfeito; é um pequeno conjunto de factos do repositório que mude o trabalho para melhor de forma fiável.
Perguntas frequentes
O AGENTS.md e o CLAUDE.md tornam os agentes de programação mais precisos?
Não de forma fiável, segundo a investigação atual. Estudos recentes encontram efeitos díspares na eficiência e pouca ou nenhuma melhoria geral na correção das tarefas. Ainda assim, instruções operacionais concretas podem reduzir o desperdício de comandos, tempo e tokens.
O Claude Code pode usar um ficheiro AGENTS.md que já exista?
Que tamanho deve ter um ficheiro AGENTS.md ou CLAUDE.md?
Mantenha o ficheiro da raiz tão curto quanto o repositório permitir. A Anthropic recomenda atualmente menos de 200 linhas por CLAUDE.md. O Codex tem, por omissão, um limite de 32 KiB para toda a cadeia de instruções combinada, mas isso é um teto e não um objetivo de escrita.