A ferramenta de programação Claude Code, da Anthropic, passou a suportar o AGENTS.md a partir da versão 2.1.277. A regra é simples: quando uma pasta não tem CLAUDE.md, o Claude Code procura um arquivo AGENTS.md na mesma pasta e o carrega no contexto como instrução do projeto; onde já existe um CLAUDE.md, a ferramenta continua lendo só esse arquivo, como antes.
A versão foi lançada no GitHub em 18 de setembro. Thariq, integrante da equipe do Claude Code, anunciou a mudança em uma rede social:
"Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md."
(A partir de hoje, na versão 2.1.277, se uma pasta não tiver CLAUDE.md, o Claude vai buscar e usar o AGENTS.md.)
Quatro níveis de configuração
O suporte ao AGENTS.md foi implementado como um plugin nativo, com código aberto no repositório do Claude Code no GitHub. O usuário alterna o modo em "Project instructions", dentro de /config, com quatro níveis no total:
| Modo | Comportamento |
|---|---|
| claude-md | Lê apenas o CLAUDE.md, equivale a desativar o recurso |
| claude-md-or-agents-md (padrão) | Se a pasta tem CLAUDE.md, ignora o AGENTS.md ali; senão, lê o AGENTS.md |
| claude-md-and-agents-md | Lê os dois tipos de arquivo em toda a árvore de pastas |
| managed-only | Descarta arquivos de instrução commitados no repositório e os pessoais, mantendo só os distribuídos centralmente pela organização, além da memória |
O modo padrão é um fallback, não uma fusão de conteúdo. Repositórios que já têm um CLAUDE.md configurado para o Claude Code não mudam de comportamento após a atualização; só repositórios que nunca tiveram CLAUDE.md, e que antes preparavam um AGENTS.md apenas para outras ferramentas, passam a carregar esse arquivo pela primeira vez. Se o mesmo arquivo for identificado como duplicado pelo caminho ou pelo conteúdo, ele não é carregado duas vezes.
Ainda faltam alguns pontos para igualar o CLAUDE.md
A documentação do plugin lista algumas diferenças em relação ao CLAUDE.md. Um AGENTS.md em uma subpasta só é anexado quando o agente usa o Read para ler um arquivo de texto naquela pasta; seleção de texto no IDE, notebooks, imagens e PDFs não disparam esse comportamento. Arquivos anexados dessa forma não ficam registrados como lidos e não voltam automaticamente depois que o contexto é compactado. O comando /memory e o atalho de memória rápida com # também não alcançam o AGENTS.md, pastas adicionadas com --add-dir não contribuem com AGENTS.md, e caminhos de links simbólicos são comparados literalmente, sem resolução.
Quanto aos canais, AWS Bedrock, Google Vertex e Microsoft Foundry ainda não são suportados. A mesma versão traz outra mudança ligada a arquivos de instrução: ao iniciar em modo SDK ou headless, a primeira rodada de conversa não espera mais a busca pelo CLAUDE.md terminar.
Um repositório, vários agentes
O AGENTS.md equivale a um README escrito para agentes de programação: como compilar, como rodar os testes, quais convenções de estilo de código seguir, quais pastas evitar. O formato foi inicialmente impulsionado em conjunto pelo OpenAI Codex e outras ferramentas em 2025, depois passou a ser mantido pela Agentic AI Foundation, sob a Linux Foundation; Cursor, GitHub Copilot e outras ferramentas o reconhecem. Até agora, o Claude Code só lia o seu próprio CLAUDE.md, obrigando equipes que usam várias ferramentas a manter dois arquivos com conteúdo quase idêntico; uma solução comum na comunidade era usar um link simbólico para que os dois apontassem para o mesmo arquivo.
Equipes na China costumam combinar um conjunto de ferramentas ainda mais variado: além do Claude Code, é comum encontrar Kimi Code, Qwen Code, Cursor e Codex, muitos dos quais leem o AGENTS.md por padrão ou permitem renomear o arquivo de instrução. No modo padrão, repositórios antigos não precisam de nenhuma alteração; equipes que querem manter apenas um AGENTS.md podem apagar o CLAUDE.md e concentrar as instruções ali, mas devem revisar antes as limitações citadas acima, especialmente o fato de as instruções de subpastas não voltarem sozinhas depois que o contexto é compactado em sessões longas.
O nível managed-only é voltado a administradores corporativos. Arquivos de instrução commitados no repositório são executados pelo agente como instruções, o que por si só é uma porta de entrada que pode ser envenenada; com esse nível, administradores podem liberar apenas as regras distribuídas centralmente pela organização. Ainda não há dados públicos sobre como esse nível se comporta em equipes grandes.
Fontes: notas de versão do Claude Code no GitHub, CocoLoop, publicação pública do engenheiro da Anthropic Thariq; os quatro modos, a ordem de carregamento e as restrições foram conferidos na documentação do plugin agents-md.