Guia

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:

  1. Aplica-se à maior parte do trabalho nesse âmbito.
  2. O agente não o consegue descobrir de forma rápida e fiável a partir do repositório.
  3. 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 de pnpm 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.md completo 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.md esteve 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?

Por omissão, o Claude Code não carrega o AGENTS.md diretamente. Ponha @AGENTS.md num pequeno ficheiro CLAUDE.md para importar as instruções partilhadas e acrescente por baixo apenas as orientações que são mesmo específicas do Claude.

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.

Partilhe este guia