CLAUDE.md vs AGENTS.md:que agente lê que ficheiro.

O que é cada ficheiro

Ambos são Markdown simples que um agente carrega para o seu contexto no início de uma sessão. Escreve-se lá comandos de compilação e de teste, estilo de código, estrutura do projeto e regras como "nunca editar ficheiros gerados". São instruções, e não definições impostas: o agente trata-as como orientações.

• O CLAUDE.md é específico do Claude Code. Pode estar na raiz do projeto (./CLAUDE.md ou ./.claude/CLAUDE.md), em ~/.claude/CLAUDE.md para todos os seus projetos e em subpastas. Um CLAUDE.local.md guarda notas privadas de um projeto.
• O AGENTS.md é um formato aberto descrito em agents.md, um README para agentes. O Codex, o Cursor, o agente de programação do GitHub Copilot, o Gemini CLI, o Zed e muitos outros leem-no. Num monorepo, um AGENTS.md numa subpasta aplica-se a essa parte, e prevalece o ficheiro mais próximo.

O conteúdo é do mesmo género. O que difere é a ferramenta que apanha o ficheiro.

O que o Claude Code faz com o AGENTS.md

A documentação do Claude Code descreve três casos, para a versão 2.1.277 ou posterior:

• Só um AGENTS.md no projeto, sem CLAUDE.md: o Claude Code lê o AGENTS.md.
• Os dois ficheiros no projeto: o Claude Code lê apenas os ficheiros CLAUDE.md.
• Um CLAUDE.md que importa o AGENTS.md com @AGENTS.md: o Claude lê o CLAUDE.md com o AGENTS.md incluído.

O segundo caso é o que apanha as pessoas de surpresa. Se juntar um CLAUDE.md, mesmo pequeno, a um repositório que tem um AGENTS.md, o Claude deixa de ler o AGENTS.md a menos que o CLAUDE.md o importe. O mesmo vale para um CLAUDE.local.md. As versões mais antigas do Claude Code liam apenas o CLAUDE.md, e é por isso que a importação continua a ser a escolha segura. A documentação descreve também uma definição Project instructions em /config para o Claude ler os dois ficheiros em conjunto.

Manter um só conjunto de instruções

Escolha um ficheiro como fonte de verdade. Há duas formas documentadas:

1. Importar o AGENTS.md a partir do CLAUDE.md

   Crie um CLAUDE.md junto do AGENTS.md cuja primeira linha seja @AGENTS.md e depois junte por baixo as instruções só para o Claude. As importações usam a sintaxe @caminho, os caminhos relativos resolvem-se a partir do ficheiro que os contém e os ficheiros importados podem importar outros até quatro níveis de profundidade.

2. Ligação simbólica de CLAUDE.md para AGENTS.md

   Execute ln -s AGENTS.md CLAUDE.md se não tiver nada específico do Claude a acrescentar. A documentação avisa que as ferramentas de edição do Claude não escrevem através de uma ligação simbólica, e que no Windows uma ligação simbólica no commit pode ser extraída como um ficheiro de texto de uma linha, pelo que a importação é a escolha mais segura para um repositório partilhado.

Evite uma terceira abordagem: um CLAUDE.md que diz "lê o AGENTS.md" por palavras. O Claude só vê o ficheiro se decidir abri-lo, ao passo que uma importação carrega-o sempre.

Um AGENTS.md partilhado

Ponha no AGENTS.md o que qualquer agente precisa:

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Mantenha-o curto e específico. A documentação do Claude Code sugere ficar abaixo de cerca de 200 linhas por CLAUDE.md, porque os ficheiros mais longos custam contexto e são seguidos com menos fiabilidade.

Erros comuns

• Dois ficheiros que se afastam. Uma cópia é atualizada, a outra não. Use a importação.
• Juntar um CLAUDE.md e perder o AGENTS.md. Veja acima: importe-o.
• Pôr segredos num dos ficheiros. Vão para o commit e são carregados em todas as sessões.
• Regras vagas. "Escreve código limpo" não serve de nada. "Executa npm test antes de dizeres que acabaste" serve.
• Regras contraditórias entre o ficheiro de uma pasta-mãe e o de uma subpasta.

Ler e rever estes ficheiros

Ambos são Markdown comum, por isso o DotMD abre o CLAUDE.md e o AGENTS.md como qualquer ficheiro .md, com um índice e o histórico de cada alteração, e mostra o que um agente neles alterou. A leitura é gratuita. Veja também o Claude Code e o Codex com o DotMD.

Perguntas sobre CLAUDE.md e AGENTS.md

Mais perguntas