AGENTS.md e CLAUDE.md: Como Escrever um Ficheiro de Configuração que o Agente Realmente Usa

Escrever um bom ficheiro de configuração é a jogada de maior alavancagem e menor esforço em programação agêntica. Define o contexto uma vez e todas as sessões beneficiam: o agente deixa de adivinhar o comando de teste, de reformatar segundo os seus próprios padrões, de editar o único diretório que declaraste estar fora dos limites. Esta página é o ofício concreto por detrás da skill "contexto e configuração" AI-Native — uma das 17 skills AI-native que avaliamos ao longo dos níveis. Manter memória durável do projeto em CLAUDE.md / AGENTS.md é um sinal distintivo de um Developer Agêntico de Nível 3, por isso vale a pena fazer isto bem.

A ideia central é a mesma em todas as ferramentas, mesmo que a mecânica difira: um ficheiro de configuração transporta as coisas que um agente não consegue inferir do código por si só. O modelo já conhece a tua linguagem. Não sabe que os teus testes precisam de uma flag específica, que migraste de uma biblioteca há três meses, ou que infra/ é gerado e nunca deve ser editado à mão. É essa lacuna que o ficheiro preenche.

O panorama: uma filosofia, vários ficheiros

Todos os agentes principais leem um ficheiro de contexto do projeto. Partilham uma filosofia e divergem no nome do ficheiro e na mecânica de carregamento. Aqui está o mapa para 2026:

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 tools	Padrão aberto entre ferramentas
CLAUDE.md	Claude Code	Formato nativo do Claude Code
GEMINI.md	Gemini CLI	Formato nativo do Gemini
.github/copilot-instructions.md	GitHub Copilot	Instruções de repositório do Copilot
.cursor/rules (formerly .cursorrules)	Cursor	Formato de regras do Cursor

A conclusão: AGENTS.md é o emergente ponto único de verdade — uma especificação aberta que ~20 ferramentas já leem. O senão é que o Claude Code não lê AGENTS.md nativamente; só lê CLAUDE.md. Por isso, o padrão canónico de fonte única é manter AGENTS.md como referência e criar uma ponte para o Claude com um CLAUDE.md mínimo que o importa:

@AGENTS.md

<!-- Claude-specific notes can go below -->

Um symlink também funciona (ln -s AGENTS.md CLAUDE.md), mas no Windows prefere o @import — os symlinks lá precisam de direitos de administrador. Assim manténs um único ficheiro e ambos os ecossistemas leem-no.

O que pôr lá dentro

A análise do GitHub sobre mais de 2 500 repositórios ("How to write a great AGENTS.md") concluiu que as configurações que ajudam mensuravelmente os agentes partilham seis secções. Por ordem aproximada de prioridade:

1. Commands — colocados cedo, com comandos executáveis exatos e flags (npm test, npm run build, pytest -v), não apenas nomes de ferramentas. Esta é a secção de maior ROI: os agentes já sabem que o pytest existe; não sabem as flags obrigatórias do teu projeto. Coloca-a perto do topo.
2. Testing practices — como testar, o que executar antes de fazer commit, expetativas de cobertura.
3. Project structure — onde as coisas estão, para o agente parar de andar à procura.
4. Code style — mostra um snippet de código real, não três parágrafos de prosa.
5. Git workflow — nomenclatura de branches, convenções de commits, regras de PR.
6. Boundaries — o que o agente nunca deve tocar (diretórios gerados, segredos, código vendorizado, migrações).

Repara na ordem de alavancagem. "Commands com flags" é primeiro por uma razão: é o único elemento que o modelo mais seguramente não consegue adivinhar e que mais frequentemente erra. Se não escreveres mais nada bem, escreve isso.

Incluir / excluir: o teste linha a linha

A documentação de memória da Anthropic traça uma linha explícita de duas colunas. Usa-a como filtro para cada linha que te apeteça adicionar.

Include	Exclude
Comandos Bash que o agente não consegue adivinhar	Tudo o que seja inferível a partir do código
Regras de estilo que diferem dos padrões	Convenções de linguagem que o modelo já conhece
Instruções de teste / test runner preferido	Documentação detalhada de API (faz antes uma ligação)
Etiqueta do repositório (nomenclatura de branches, convenções de PR)	Informação que muda com frequência
Decisões arquiteturais específicas do projeto	Explicações longas e tutoriais
Particularidades do ambiente de dev (variáveis de ambiente obrigatórias)	Descrições ficheiro a ficheiro da base de código
Armadilhas não óbvias	Práticas evidentes como "escreve código limpo"

Há um teste que colapsa toda a tabela num hábito:

O teste por linha: "Remover esta linha faria o agente cometer erros? Se não, corta-a."

Aplica esse teste a cada linha. "Use TypeScript" — o agente vê os ficheiros .ts; corta. "Executa as migrações de base de dados com npm run db:migrate, nunca edites migrations/ à mão" — não podia ter adivinhado isso, e errar corrompe estado; mantém.

Escreve com a altitude certa

A orientação de context-engineering da Anthropic condensa uma boa autoria em quatro princípios.

1. Especificidade / verificabilidade. Escreve regras concretas o suficiente para verificar contra o output do agente. Orientação vaga não pode ser verificada, por isso não pode ser seguida de forma fiável.

• "Use indentação de 2 espaços" — não "Formata o código corretamente."
• "Executa npm test antes de fazer commit" — não "Testa as tuas alterações."
• "Os handlers de API estão em src/api/handlers/" — não "Mantém os ficheiros organizados."

2. Altitude certa. Aponta entre a lógica rigidamente codificada e a vagueza sem sentido: "específico o suficiente para orientar o comportamento, flexível o suficiente para ser uma heurística sólida." Demasiado rígido e quebra no primeiro caso extremo; demasiado vago e não orienta nada.

3. Mínimo mas suficiente. Mínimo não significa curto. Significa dar contexto suficiente à partida para que o agente não precise de adivinhar ou redescobrir — e nada mais além disso. Corta o relleno, mantém o detalhe que suporta peso.

4. Estrutura. Usa secções etiquetadas — cabeçalhos Markdown ou tags XML. Um ficheiro legível à vista é um ficheiro que o agente (e os teus colegas de equipa) realmente interpreta.

Mantém-no leve

A razão real para manter o ficheiro leve é o orçamento de tokens. O ficheiro de configuração carrega na íntegra em cada sessão. Não é recuperado por demanda; é prefixado ao contexto no arranque. Por isso, o inchaço tem um custo direto e mensurável: um CLAUDE.md inchado reduz mensuravelmente a adesão às instruções. A própria Anthropic é direta — ficheiros CLAUDE.md inchados fazem o Claude ignorar as tuas instruções reais. Cada linha inútil que adicionas enfraquece as tuas linhas boas.

Os objetivos são concretos:

• A Anthropic aponta para menos de ~200 linhas como objetivo indicativo para CLAUDE.md.
• O Codex impõe um limite rígido de 32 KiB em AGENTS.md (project_doc_max_bytes); ficheiros demasiado grandes são truncados, pelo que tudo o que ultrapasse esse limite simplesmente não carrega.

E uma armadilha que vale a pena nomear: os imports não poupam orçamento. Um ficheiro @imported ainda carrega para o contexto no arranque — dividiste o ficheiro, não reduziste a pegada. Para reduzir de facto o que carrega em cada sessão, externaliza conteúdo condicionalmente relevante:

• Path-scoped rules para preocupações transversais que tocam muitos ficheiros — carregam apenas quando o agente trabalha nesse caminho.
• Skills para procedimentos por demanda — carregam apenas quando são invocadas.
• Ligações para material de referência longo ou detalhado — aponta para ele em vez de o incluir inline.

O princípio é o mesmo que o teste por linha impõe, aplicado ao nível da secção: se só é relevante às vezes, não deve estar no ficheiro que carrega sempre.

DESIGN.md: uma convenção de equipa, não um padrão

Um DESIGN.md é a aplicação exemplar de "mantém a configuração leve, liga o detalhe." É um documento separado de design/arquitetura — as decisões chave, o modelo de domínio, os padrões arquiteturais, o porquê de estar construído assim — que o teu AGENTS.md importa com @ ou referencia em vez de incluir inline. Isso mantém a configuração sempre carregada curta, enquanto o contexto profundo fica a um salto de distância.

Sê honesto sobre o seu estatuto, porém: ao contrário de AGENTS.md e CLAUDE.md, não existe nenhuma fonte primária que estabeleça DESIGN.md como um ficheiro de configuração de agente padrão. É uma poderosa convenção de equipa, não um padrão documentado. Usa-o porque funciona para a tua equipa, não porque uma especificação o exige.

Âmbito e hierarquia

Ambos os ecossistemas organizam ficheiros do geral para o específico, mas resolvem a precedência de forma diferente.

O CLAUDE.md tem quatro âmbitos, carregando do geral para o específico:

1. Política gerida — definida pela tua organização / TI, aplica-se a toda a organização.
2. Utilizador — ~/.claude/CLAUDE.md, aplica-se a todos os teus projetos.
3. Projeto — ./CLAUDE.md, incluído no git e partilhado com a equipa.
4. Local — ./CLAUDE.local.md, ignorado pelo git, para os teus overrides pessoais.

Em monorepos, os ficheiros de diretórios pai carregam automaticamente e os ficheiros de subdiretórios carregam por demanda. Os imports usam a sintaxe @path/to/file (relativa ou absoluta), aninham até 4 níveis de profundidade, e o parser ignora blocos de código para que um caminho dentro de um bloco delimitado não seja tratado como um import.

O AGENTS.md resolve com prioridade para o mais próximo. O Codex percorre desde a raiz do Git até ao teu diretório de trabalho atual e concatena os ficheiros que encontra, do mais genérico para o mais específico. Como os ficheiros mais próximos aparecem mais tarde, sobrepõem-se — o ficheiro mais próximo tem prioridade. Num monorepo manténs um AGENTS.md por pacote, e o mais próximo do código que está a ser editado tem precedência. Acima de tudo: uma instrução explícita no chat sobrepõe-se a todos os ficheiros.

E a ponte entre ferramentas mencionada antes une os dois sistemas: mantém AGENTS.md como referência, adiciona um CLAUDE.md que faz @AGENTS.md, e a tua hierarquia é partilhada entre ferramentas sem duplicação.

Orientativo, não impositivo

Aqui está a nuance que te salva de uma falsa sensação de segurança: estes ficheiros são contexto orientativo, não imposição determinística. Orientam o agente; não o vinculam.

Palavras de ênfase como IMPORTANT e YOU MUST melhoram mensuravelmente a adesão — mas não a garantem. Para requisitos que devem acontecer sempre (executar o formatador, bloquear um commit que falha nos testes, nunca escrever em main), o backstop determinístico são os hooks (no Claude Code), não uma formulação mais enfática na configuração.

A regra prática: usa a configuração para orientação e heurísticas; recorre a hooks no momento em que "o agente geralmente faz isto" não é suficiente e precisas de "o agente faz isto sempre."

Mantém-no como código

Um ficheiro de configuração é um artefacto vivo, não uma escrita única. Trata-o da mesma forma que tratas o resto do repositório.

• Arranca com /init. Deixa a ferramenta gerar um primeiro rascunho a partir da tua base de código, depois refina-o à mão — a versão gerada é um ponto de partida, não o ficheiro final.
• Revê quando algo corre mal. Cada vez que o agente faz algo errado, pergunta se uma linha em falta ou enganosa na configuração foi a causa.
• Poda regularmente. Volta a aplicar o teste por linha a todo o ficheiro. Linhas que eram essenciais no trimestre passado podem ser peso morto agora.
• Testa as alterações pelo comportamento. Não confies que uma edição ajudou — observa se o comportamento do agente mudou de facto. Se não consegues ver a diferença, a linha provavelmente não está a fazer trabalho.
• Incluí-lo no git. Uma configuração partilhada e com controlo de versão significa que toda a equipa contribui e beneficia, e as alterações aparecem em revisão.

O hábito mais valioso é o ciclo de auto-melhoria: quando o agente comete um erro, adiciona uma única regra de uma linha para que não se repita. Ao longo de algumas semanas, esse ciclo converge a tua configuração exatamente nos pontos sensíveis que o teu projeto realmente tem — nem mais, nem menos.

Um AGENTS.md de partida

Aqui está um esqueleto real, pronto a copiar, com as seis secções de maior ROI preenchidas com placeholders realistas. Substitui pelos teus dados específicos e elimina tudo o que não passe no teste por linha.

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Para uma fonte única de verdade entre ferramentas, coloca um `CLAUDE.md` de uma linha ao lado contendo `@AGENTS.md`, e liga as tuas notas de arquitetura mais profundas (um `DESIGN.md`, os teus ADRs) em vez de as colar inline.

## Para onde ir a seguir

Um ficheiro de configuração leve e específico é um dos comportamentos concretos que separa os developers assistidos por IA dos genuinamente AI-native. [Descobre o teu nível AI-native](/quiz) em três minutos — avalia exatamente este tipo de ofício — e quando estiveres pronto para ligar a tua cadeia de ferramentas, começa pelo [stack recomendado pela ProCoders](/stack).