---
title: "O que deve ir no AGENTS.md e no CLAUDE.md?"
seoTitle: "AGENTS.md e CLAUDE.md: o que ajuda mesmo os agentes"
navTitle: "AGENTS.md e CLAUDE.md"
description: "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."
slug: agents-md-claude-md-best-practices
lang: pt-PT
date: 2026-08-06
updated: 2026-08-06
author: "Chatcode"
category: guide
faq:
  - q: "O AGENTS.md e o CLAUDE.md tornam os agentes de programação mais precisos?"
    a: "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."
  - q: "O Claude Code pode usar um ficheiro AGENTS.md que já exista?"
    a: "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."
  - q: "Que tamanho deve ter um ficheiro AGENTS.md ou CLAUDE.md?"
    a: "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."
---

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](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

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](https://code.claude.com/docs/en/memory).

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`:

```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?](https://arxiv.org/abs/2607.27250)
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](https://arxiv.org/abs/2601.20404)
  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](https://arxiv.org/abs/2602.11988) 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:

```md
## 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:

```md
## 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

```md
# 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](/articles/skills-sh-install-skills-ai-coding-agents).
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.
