Pular para o conteúdo principal

AGENTS.md & Interoperabilidade Entre Ferramentas

Intermediário

Você já conhece o CLAUDE.md — o briefing de projeto do Claude Code. Mas seu repositório provavelmente é tocado por mais de um agente: um colega usa o Codex, a CI usa um bot de código, alguém abre o repositório no Cursor. O AGENTS.md é o padrão aberto que essas ferramentas concordam em ler, então você escreve as instruções do seu projeto uma única vez em vez de manter um arquivo diferente por ferramenta.

What you'll learn
  • O que é o AGENTS.md e quem o administra
  • Por que o Claude Code lê o CLAUDE.md e não o AGENTS.md
  • Três formas confiáveis de manter uma única fonte de verdade entre ferramentas
  • Como arquivos AGENTS.md aninhados e globais se combinam
  • O que pertence ao arquivo — e o que deixar de fora

O que é o AGENTS.md​

O AGENTS.md é um arquivo Markdown simples na raiz do seu repositório — pense nele como um README escrito para agentes em vez de humanos. Ele diz a um agente de código como compilar, testar e contribuir com o projeto. O formato não tem campos obrigatórios: os agentes simplesmente leem a prosa.

É um padrão aberto administrado pela Agentic AI Foundation (AAIF) sob a Linux Foundation e, em meados de 2026, é usado por mais de 60 mil projetos open-source e lido por mais de 30 ferramentas — incluindo OpenAI Codex, Jules e Gemini CLI do Google, Cursor, Windsurf, Devin, Zed, Warp, Aider, goose, Amp e o agente de código do GitHub Copilot.

What you'll learn
  • O AGENTS.md é uma convenção, não um runtime: cada ferramenta decide como descobre, combina e injeta o arquivo.
  • Nenhum schema é imposto — prosa clara vence estrutura rígida.
  • Ele complementa seu README; não o substitui.

O detalhe do Claude Code​

Aqui está a parte em que as pessoas tropeçam: o Claude Code lê o CLAUDE.md, não o AGENTS.md. Se seu repositório tiver apenas um AGENTS.md, o Claude Code o ignora por padrão. Isso não é um bug — é anterior ao padrão —, mas significa que um repositório multiferramenta precisa de uma estratégia de sincronização deliberada, ou suas instruções vão silenciosamente divergir.

Watch out
  • Não presuma que o Claude Code recorre ao AGENTS.md — ele não o lê automaticamente.
  • Dois arquivos mantidos à mão (CLAUDE.md e AGENTS.md) vão divergir. Escolha uma única fonte de verdade.
  • Verifique o comportamento atual na documentação oficial de memória antes de confiar em qualquer alegação de fallback.

Mantenha uma única fonte de verdade​

Três padrões mantêm o CLAUDE.md e o AGENTS.md sincronizados sem duplicar conteúdo. Escolha conforme a plataforma da sua equipe.

Guided walkthrough1 of 3
  1. Faça do CLAUDE.md um symlink para o AGENTS.md. O Claude Code segue symlinks e lê o destino byte por byte — um único arquivo real, zero lógica de combinação. Ressalva: no Windows, criar um symlink exige o Modo Desenvolvedor ou direitos de administrador, então equipes multiplataforma podem preferir o método de importação.

Faça um symlink do CLAUDE.md para o padrão compartilhado (macOS / Linux)

ln -s AGENTS.md CLAUDE.md

Ou mantenha um CLAUDE.md de uma linha que o importa

@AGENTS.md
Pro tip
  • Use symlink quando toda a equipe estiver no macOS/Linux — é o que menos exige manutenção.
  • Use @import quando houver colaboradores no Windows.
  • Faça o commit do que escolher para que toda a equipe tenha o mesmo comportamento.

Como arquivos aninhados e globais se combinam​

Os agentes mais robustos tratam o AGENTS.md de forma hierárquica — o mesmo modelo mental da hierarquia de memória do CLAUDE.md. O Codex, por exemplo, percorre desde um arquivo global no seu diretório pessoal, passando pela raiz do Git, até a pasta atual, concatenando à medida que avança:

Arquivos mais próximos do trabalho prevalecem, porque são concatenados por último e sobrescrevem as orientações anteriores. Assim, um services/payments/AGENTS.md herda as instruções da raiz do repositório e adiciona regras que se aplicam apenas dentro daquele serviço — coloque orientações especializadas o mais perto possível do código especializado.

Interoperabilidade num relance
Pressione Enter ou Espaço para virar o cartão. Use as setas esquerda e direita para navegar entre os cartões.Termo exibido.
1 / 5

O que colocar nele​

A mesma disciplina de um bom CLAUDE.md — o padrão apenas sugere algumas seções comuns:

  • Visão geral do projeto — o que é isto, em duas frases.
  • Comandos de build e teste — como executar, testar e fazer lint.
  • Estilo de código — convenções que um agente não consegue inferir.
  • Instruções de teste — o que "concluído" significa.
  • Considerações de segurança — o que nunca tocar ou commitar.
  • Diretrizes de commit / PR — formato de mensagem, regras de branch.
Watch out
  • Os agentes seguem o arquivo ao pé da letra — instruções desatualizadas ou idealizadas atrapalham ativamente, exatamente como no CLAUDE.md.
  • Mantenha-o curto e verdadeiro; descreva como o projeto funciona hoje.
  • Nunca faça commit de segredos; referencie documentos extensos em vez de colá-los.

Teste-se​

Teste-se

0/3
  1. O Claude Code lê o AGENTS.md automaticamente?
  2. Sua equipe está totalmente no macOS e Linux. Qual é a forma de menor manutenção para compartilhar um único arquivo de instruções entre o Claude Code e o Codex?
  3. Quando os agentes combinam um AGENTS.md global, um da raiz do repositório e um de subdiretório, qual prevalece nos conflitos?
Key takeaways
  • O AGENTS.md é o padrão aberto, administrado pela Linux Foundation, que mais de 30 agentes de código leem — um README para agentes.
  • O Claude Code lê o CLAUDE.md, não o AGENTS.md, então repositórios multiferramenta precisam mantê-los sincronizados.
  • Faça um symlink do CLAUDE.md → AGENTS.md no Mac/Linux, ou use uma importação @AGENTS.md de uma linha para equipes multiplataforma.
  • Arquivos aninhados se combinam global → raiz → subdiretório, com o arquivo mais próximo prevalecendo.
  • Preencha-o como um ótimo CLAUDE.md: visão geral, comandos de build/teste, convenções, segurança e proteções — curto e verdadeiro.

A seguir​

Fontes e leitura adicional​