AGENTS.md vs CLAUDE.md Explicados

Problema: Você abre um repositório que tem um AGENTS.md e um CLAUDE.md. Eles parecem semelhantes. Dizem coisas semelhantes. Você não tem certeza qual o Claude Code lê, qual as outras ferramentas leem, ou por que dois arquivos existem.

Resposta rápida: Claude Code lê CLAUDE.md. Todas as outras ferramentas principais de IA leem AGENTS.md. Se você usa apenas o Claude Code, precisa apenas do CLAUDE.md. Se sua equipe usa múltiplas ferramentas, um symlink faz as duas ferramentas lerem o mesmo arquivo:

ln -s CLAUDE.md AGENTS.md

Uma fonte de verdade. Sem duplicação.

O que AGENTS.md realmente é

AGENTS.md é um padrão cross-tool publicado pela Linux Foundation e pela Agent Interoperability Initiative Foundation (AAIF). O objetivo é um único arquivo de contexto que qualquer ferramenta de código por IA possa ler quando abre seu repositório.

Até abril de 2026, 18+ ferramentas o suportam. OpenAI Codex, Gemini CLI, Devin, Cursor, Windsurf, Continue, Amp, Warp e Goose todos leem AGENTS.md. Está ativo em mais de 60.000 projetos no GitHub.

A spec da AAIF define um schema para o arquivo: campos como allowed_tools, disallowed_tools, agent_instructions, output_format e environment. Cada ferramenta lê os campos que entende e ignora os que não reconhece.

O Claude Code ignora esses campos de schema completamente. Ele tem seu próprio sistema de permissões dentro do settings.json. Quando pega conteúdo do AGENTS.md (via import), lê as instruções em prosa e descarta os campos estruturados.

O que CLAUDE.md realmente é

CLAUDE.md é o arquivo de contexto nativo do Claude Code. Toda sessão começa carregando-o antes do primeiro token de conversa.

O arquivo não é documentação para o Claude ler. São os parâmetros de operação de como o Claude roda. Coloque seus fluxos de trabalho, lógica de roteamento, regras de qualidade e padrões de delegação aqui. Docs do projeto, notas de stack e especificidades de tecnologia pertencem a skills que carregam sob demanda.

Tamanho alvo: 200-500 linhas para um setup solo. 50-100 linhas para um arquivo de equipe compartilhado onde cada contribuidor precisa entender o que está lá.

A Hierarquia de 6 Níveis de Prioridade

O Claude Code não carrega apenas um arquivo. Ele carrega uma pilha de arquivos e os resolve em ordem. O mais interno vence sobre o mais externo:

O nível 1 define padrões globais. O nível 2 define regras do repositório. O nível 3 guarda coisas específicas da máquina que nunca deveriam sair do seu laptop.

O problema do CLAUDE.local.md: O Claude Code não adiciona esse arquivo ao .gitignore por você. Você precisa fazer isso você mesmo. Se esquecer, o git o rastreia e ele sobe no próximo commit. Bons candidatos para o arquivo: endpoints de API locais, preferências pessoais de debug, URLs de sandbox. Nenhum desses pertence à árvore compartilhada.

@imports e a ponte para AGENTS.md

Dentro de qualquer arquivo CLAUDE.md, você pode puxar outro arquivo com @path/to/file.md. O conteúdo importado é injetado onde a linha @ está.

É assim que o Claude Code 2.1.59+ permite criar uma ponte para o AGENTS.md:

# CLAUDE.md
@AGENTS.md
<!-- Claude reads AGENTS.md content here, but CLAUDE.md rules below take priority -->

## Claude-specific rules
- Use TodoWrite to track multi-step tasks
- Never use --dangerously-skip-permissions outside containers

O conteúdo importado do AGENTS.md carrega. Mas o nível 6 (imports) é a camada mais fraca na hierarquia. Se uma regra no AGENTS.md conflita com uma regra escrita diretamente no CLAUDE.md, a regra direta vence. Sempre.

Isso significa que o conteúdo do AGENTS.md é sempre consultivo quando trazido via import. Informa o comportamento do Claude. Não sobrescreve o que você escreveu no arquivo raiz.

O truque do symlink

O setup multi-ferramenta mais limpo evita completamente a complexidade do import. Rode isso uma vez na raiz do repositório:

ln -s CLAUDE.md AGENTS.md

Agora o AGENTS.md é um symlink apontando para CLAUDE.md. O Claude Code lê CLAUDE.md. Cursor, Windsurf, Gemini CLI e qualquer outra ferramenta com suporte a AGENTS.md leem AGENTS.md. Todos leem os mesmos bytes.

Sem duplicação. Sem problema de sincronização. Um arquivo para manter.

O único trade-off: o Claude Code ignora campos de schema do AGENTS.md, e ferramentas com suporte a AGENTS.md ignoram instruções específicas do Claude Code (como TodoWrite ou flags --dangerously-skip-permissions). Na prática, isso não é problema. Instruções em prosa funcionam para os dois lados. Campos de schema são simplesmente pulados.

Memória automática e MEMORY.md

O Claude Code 2.1.59+ pode escrever em um arquivo MEMORY.md na raiz do seu projeto por conta própria. Esse arquivo fica no nível 5, a mesma prioridade do CLAUDE.md no nível do repositório.

O arquivo tem limites rígidos: 200 linhas e 25KB. Para arquivos de tópico sob demanda (como memory/auth.md ou memory/payments.md), o limite é 120 linhas cada. O próprio MEMORY.md funciona como um índice apontando para esses arquivos de tópico.

O que ficar de olho: entradas de memória que se contradizem causam ambiguidade silenciosa. O Claude não lança um erro. Ele apenas tem duas instruções conflitantes e as resolve silenciosamente, o que pode não ir do jeito que você espera. Audite o MEMORY.md periodicamente. Remova entradas com mais de 30 dias que não tenham recorrido.

Os 7 jeitos que o CLAUDE.md dá errado

A maioria das equipes escreve um CLAUDE.md uma vez e nunca o revisa. Esses são os modos de falha que se acumulam com o tempo:

Saturação de prioridade: SEMPRE e NUNCA e CRÍTICO em excesso. Quando cada regra grita, nenhuma delas aterra. O Claude trata arquivos sobrecarregados espalhando a atenção igualmente por todas as regras. Mantenha restrições rígidas em 5-7 no máximo.

O wrapper "pode ou não ser relevante": quando o Claude Code injeta contexto de sessão, às vezes o envolve nessa observação. Esse wrapper sinaliza que o conteúdo foi carregado mas está sendo tratado como plano de fundo, não como instruções. Arquivos com esse wrapper não estão sendo seguidos de perto.

Diluição por profundidade de import: instruções em um arquivo importado são mais fracas que instruções escritas diretamente. Uma cadeia como CLAUDE.md → @a.md → @b.md está muito diluída quando chega em b.md. Mantenha regras importantes no arquivo raiz.

Replay de trauma: o MEMORY.md acumula cada correção que você já fez. Após 50 sessões, o Claude está tentando evitar 50 erros passados de uma vez. O desempenho degrada. Auditorias periódicas corrigem isso.

Acúmulo de viés: confirmações positivas escritas na memória ("usuário prefere X") podem se solidificar em regras que não correspondem mais às suas preferências atuais. O que você preferia seis meses atrás pode não ser o que você prefere hoje.

Seguimento de instruções vs. aplicação: o CLAUDE.md é carregado como contexto, não aplicado como um linter. Uma regra que diz "nunca use travessões" ainda pode ser violada. Se uma regra importa, combine-a com ferramentas reais (uma regra de lint, um hook, um formatter) em vez de depender apenas do contexto.

Perda pós-/compact: rodar /compact resume a conversa. Instruções que estavam no chat mas não no CLAUDE.md não sobrevivem à compactação. Escreva regras duráveis no arquivo. Não as mantenha apenas na sessão.

O que vai em cada arquivo

Boris Cherny da Anthropic define o alvo diretamente: o CLAUDE.md deve guardar comportamentos que precisam persistir em todas as sessões.

Coloque no CLAUDE.md: fluxos de trabalho operacionais, lógica de roteamento, padrões de qualidade, protocolos de coordenação, restrições rígidas (5-7 no máximo), padrões de delegação.

Coloque em skills (carregadas sob demanda): padrões de tecnologia, convenções de framework, contexto específico do projeto, docs de arquitetura, convenções da equipe.

Não coloque no CLAUDE.md: documentação de arquitetura (leia do código), histórico git recente (use git log), status atual de PR, instruções padrão que qualquer modelo já segue por padrão.

O conselho sobre contagem de linhas que você encontra por aí diz ficar abaixo de 60 linhas. Isso está errado. Sessenta linhas de trivialidades de projeto que você só precisa metade das vezes desperdiçam mais contexto efetivo do que 300 linhas de regras operacionais universais que se aplicam a cada requisição. Relevância é a métrica, não o tamanho.

Escolhendo seu setup

Três padrões cobrem a maioria dos casos de uso:

Se você usa apenas Claude Code, escreva um único CLAUDE.md e ignore AGENTS.md completamente. Ele não existe para você.

Se sua equipe usa múltiplas ferramentas mas o Claude Code é a principal, use o symlink. Um arquivo, ambos os nomes, sem overhead de manutenção. Escreva no estilo que funciona para o Claude Code; as outras ferramentas pegam o que conseguem da prosa.

Se você precisa que o Claude Code fique sincronizado com um AGENTS.md de todo o repositório que outras ferramentas mantêm, use a ponte @AGENTS.md de import dentro do seu CLAUDE.md. Lembre que o conteúdo importado é consultivo. Coloque suas substituições específicas para Claude abaixo da linha de import.

Dois arquivos, uma regra clara: Claude lê CLAUDE.md, todos os outros leem AGENTS.md, e um symlink é a forma mais rápida de fazê-los ser o mesmo.

Perguntas frequentes

O que é AGENTS.md?

AGENTS.md é um padrão aberto publicado pela Linux Foundation e pela Agent Interoperability Initiative Foundation. Ele define um único arquivo de contexto que qualquer ferramenta de código por IA pode ler quando abre seu repositório. Mais de 18 ferramentas o suportam, incluindo Cursor, Windsurf, Gemini CLI, Devin e OpenAI Codex. É usado em mais de 60.000 projetos open-source.

O Claude Code lê AGENTS.md?

O Claude Code não lê AGENTS.md nativamente. Ele lê CLAUDE.md. Você pode trazer conteúdo do AGENTS.md para o Claude Code usando uma linha de import @AGENTS.md dentro do seu arquivo CLAUDE.md, ou apontar ambos os nomes de arquivo para o mesmo arquivo usando um symlink. Nenhuma abordagem muda qual arquivo o Claude Code trata como autoritativo.

Qual é a diferença entre AGENTS.md e CLAUDE.md?

AGENTS.md é um padrão cross-tool que qualquer assistente de código por IA pode ler. CLAUDE.md é o arquivo nativo do Claude Code, carregado automaticamente no início de cada sessão. AGENTS.md usa um schema estruturado com campos como allowed_tools e output_format. CLAUDE.md usa instruções em prosa simples e suporta funcionalidades específicas do Claude Code como @imports, CLAUDE.local.md e memória automática.

O que devo colocar no CLAUDE.md?

Coloque regras operacionais que se aplicam a cada sessão: fluxos de trabalho, lógica de roteamento, padrões de qualidade, restrições rígidas e padrões de delegação. Mantenha as restrições rígidas em 5-7 no máximo. Não coloque documentação de arquitetura, histórico git recente ou instruções padrão que qualquer modelo já segue por padrão. Especificidades de tecnologia e contexto do projeto pertencem a skills que carregam sob demanda, não no arquivo raiz.

Para que serve o CLAUDE.local.md?

CLAUDE.local.md guarda configurações específicas da máquina que não devem ser commitadas no controle de versão. Bons candidatos incluem endpoints de API locais, preferências pessoais de debug e URLs de sandbox. O Claude Code não o adiciona ao .gitignore automaticamente, então você precisa fazer isso você mesmo. Se esquecer, o arquivo sobe no próximo commit e expõe configuração local para cada contribuidor.

Como uso CLAUDE.md e AGENTS.md juntos?

A abordagem mais limpa é um symlink na raiz do repositório: ln -s CLAUDE.md AGENTS.md. O Claude Code lê CLAUDE.md, e todas as outras ferramentas leem AGENTS.md. Ambos leem os mesmos bytes sem duplicação. Se você precisa que o Claude Code fique downstream de um AGENTS.md compartilhado mantido pela equipe, use o import @AGENTS.md dentro do seu CLAUDE.md e escreva qualquer substituição específica para Claude abaixo da linha de import.