Claude Code agora lê AGENTS.md nativamente: a partir da versão 2.1.277, se seu projeto não tiver CLAUDE.md, carrega AGENTS.md como instruções do projeto, sem imports nem symlinks. O detalhe está nesse “não tiver”: um CLAUDE.md —ou até um CLAUDE.local.md privado— no seu diretório de trabalho ou em qualquer um superior é suficiente para que Claude ignore AGENTS.md por padrão.
Se seu repositório já alimenta Codex, Cursor ou Amp com um AGENTS.md compartilhado, essa é a mudança que permite deletar aquele CLAUDE.md de uma única linha que você mantinha só para Claude. Aqui está como funciona exatamente, como mudar o comportamento padrão e quais workarounds antigos você pode eliminar.
O que é AGENTS.md?
AGENTS.md é um arquivo Markdown na raiz do repositório com as instruções que um agente de código precisa para trabalhar nesse projeto: comandos de build e test, convenções, estrutura. Diferente de CLAUDE.md, não pertence a nenhuma ferramenta: Codex, Amp e Cursor já o leem, e é por isso que se tornou o formato compartilhado para equipes que usam vários agentes ao mesmo tempo.
Claude Code, o agente de terminal da Anthropic, tinha seu próprio arquivo de instruções —CLAUDE.md— e até agora ignorava AGENTS.md a menos que você o importasse manualmente. Se ainda não o usa, comece por nosso guia Claude Code: o que é, por que importa e como começar.
Como usar AGENTS.md no Claude Code?
Você não precisa fazer nada: atualize para a versão 2.1.277 ou posterior e, se seu projeto não tiver CLAUDE.md, Claude Code lê seu AGENTS.md automaticamente. A entrada do changelog de 18 de setembro de 2026 resume em uma linha: “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under ‘Project instructions’ in /config (not yet on Bedrock, Vertex or Foundry).”
Por dentro, é um plugin integrado chamado agents-md, e Anthropic publicou seu código no repositório de Claude Code, em mods/agents-md. Um AGENTS.md carregado assim é tratado como um arquivo de instruções do projeto: mesmo lugar no contexto e mesmo tratamento que um CLAUDE.md.
Na prática, Claude o lê nestes momentos:
- Ao iniciar a sessão, carrega cada
AGENTS.mde.claude/AGENTS.mddo seu diretório de trabalho e dos diretórios superiores. Em uma sessão interativa você verá uma linha comono CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. - Enquanto trabalha em subdiretórios, carrega o
AGENTS.mddaquele subdiretório quando abre um arquivo lá com a ferramenta Read, desde que o subdiretório não tenha seu próprioCLAUDE.md. - Dentro de cada
AGENTS.md, os imports@pathse expandem e os padrões declaudeMdExcludesse aplicam, igual que comCLAUDE.md.
O que não lê: AGENTS.local.md, AGENTS.override.md nem nada dentro de um diretório .agents/. Então se você esperava que Claude também usasse .agents/skills, não fará; foi uma das primeiras reclamações na thread do Hacker News.
AGENTS.md ou CLAUDE.md: qual Claude Code lê?
Por padrão vence CLAUDE.md e AGENTS.md é completamente ignorado. A documentação oficial resume assim:
| Seu repositório tem | Claude lê |
|---|---|
Um AGENTS.md, e nenhum CLAUDE.md nem CLAUDE.local.md no seu diretório de trabalho ou superiores |
Seu AGENTS.md |
Um AGENTS.md e um CLAUDE.md ou CLAUDE.local.md no seu diretório de trabalho ou superiores |
Apenas seus arquivos CLAUDE.md |
Um CLAUDE.md que já importa AGENTS.md |
Seu CLAUDE.md, com AGENTS.md incluído através do import |
O importante é quais arquivos contam para essa verificação:
- Contam (bloqueiam
AGENTS.md):CLAUDE.md,.claude/CLAUDE.mdouCLAUDE.local.mdno seu diretório de trabalho ou em qualquer diretório superior. - Não contam (se carregam junto com
AGENTS.md): seu~/.claude/CLAUDE.mdpessoal, oCLAUDE.mdgerenciado pela sua organização e os arquivos de.claude/rules/.
Essa segunda lista é uma boa notícia: suas instruções globais pessoais continuam funcionando em um repositório que só tem AGENTS.md.
A pegadinha é CLAUDE.local.md. É o arquivo que você cria para notas pessoais que não são enviadas ao repositório e, como conta, adicionar um a um projeto que depende de AGENTS.md faz com que Claude deixe de ler AGENTS.md para você, sem aviso, enquanto seus colegas continuam recebendo. Se quer os dois, mude a configuração da próxima seção.
Como fazer Claude Code ler CLAUDE.md e AGENTS.md ao mesmo tempo?
Abra /config em uma sessão de Claude Code e mude Project instructions para claude-md-and-agents-md. Há quatro valores possíveis:
| Valor | O que Claude lê |
|---|---|
claude-md-or-agents-md |
Seus arquivos CLAUDE.md, ou seus AGENTS.md quando não há CLAUDE.md nem CLAUDE.local.md no seu diretório de trabalho ou superiores. Valor padrão. |
claude-md-and-agents-md |
Ambos. Em cada diretório, primeiro CLAUDE.md e depois AGENTS.md. Um AGENTS.md que seu CLAUDE.md já importa ou vincula com symlink não é carregado duas vezes. |
claude-md |
Apenas CLAUDE.md: o comportamento anterior. |
managed-only |
Apenas o CLAUDE.md gerenciado pela sua organização e a memória automática ao iniciar. |
Você também pode configurar em um arquivo de settings, sob o ID do plugin integrado em pluginConfigs:
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
```Funciona em `~/.claude/settings.json`, em um arquivo passado com `--settings` ou nas configurações gerenciadas da sua organização. É **ignorado** no `.claude/settings.json` do projeto e nas configurações locais, então você não pode enviá-lo para o repositório para todo o time. A alteração é aplicada a partir da sua próxima mensagem e em cada nova sessão.
Para a maioria dos times que usam ferramentas variadas, `claude-md-and-agents-md` é a configuração que você realmente quer: regras compartilhadas em `AGENTS.md`, extras específicos do Claude em `CLAUDE.md` e nada duplicado.
## Por que o Claude Code não lê meu AGENTS.md?
Quase sempre é porque há um `CLAUDE.md` em algum ponto do caminho. A lista de verificação da documentação, em ordem:
1. Procure por um `CLAUDE.md`, `.claude/CLAUDE.md` ou `CLAUDE.local.md` no seu diretório de trabalho ou em qualquer diretório acima (sem contar `~/.claude/CLAUDE.md`). Se existir, Claude o lê em vez de `AGENTS.md`, a menos que você mude para `claude-md-and-agents-md`.
2. Execute `claude --version` e confirme que você tem a versão 2.1.277 ou posterior.
3. Verifique se sua sessão é uma das que não suportam o recurso (próxima seção).
4. Abra `/config` e verifique que **Project instructions** não está em `claude-md` nem em `managed-only`. Se a configuração não aparecer, sua sessão não a suporta.
Outro detalhe que vai confundir você: quando Claude lê `AGENTS.md` diretamente, **não aparece** em `/context` nem em `/memory`. Procure pela linha `AGENTS.md loaded` no início da sessão, ou simplesmente pergunte ao Claude o que dizem suas instruções do projeto.
## O AGENTS.md funciona em Bedrock, Vertex ou sem telemetria?
Ainda não. De acordo com a documentação de 19 de setembro de 2026, Claude Code só lê `CLAUDE.md` nestes casos:
- Você usa uma versão anterior à 2.1.277.
- Sua sessão não baixa feature flags do Anthropic: por exemplo no Amazon Bedrock ou outro provedor externo, ou com a telemetria desativada. (O changelog menciona Bedrock, Vertex e Foundry.)
- É sua **primeira sessão** após instalar ou atualizar. Claude lê `AGENTS.md` a partir da próxima.
- Você desativou o plugin integrado `agents-md` em `/plugin`.
Em qualquer um desses casos, mantenha um `CLAUDE.md` junto ao seu `AGENTS.md` com o import:
```markdown
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
```Claude lê primeiro o arquivo importado e depois tudo que você adicionar abaixo.
## Posso deletar o symlink ou o @AGENTS.md do meu CLAUDE.md?
Na maioria dos casos, sim. A documentação cobre cada configuração habitual:
- **Um `CLAUDE.md` que só contém `@AGENTS.md`**: você pode deixar; Claude nunca lê `AGENTS.md` duas vezes, seja qual for o ajuste. Delete se não tiver mais nada, *exceto* se parte das suas sessões rodar em Bedrock, Vertex ou sem telemetria.
- **Um `CLAUDE.md` que pede a Claude com palavras que leia `AGENTS.md`**: delete, ou substitua a frase por um import `@AGENTS.md` real. Uma frase só funciona se Claude decidir abrir o arquivo.
- **Um `CLAUDE.md` que é symlink de `AGENTS.md`**: nada se quebra; delete se quiser. Se alguém do time usa Windows, delete: Git faz checkout de um symlink versionado como um arquivo de texto simples, a menos que `core.symlinks` esteja ativado.
- **Um hook `SessionStart` que imprime `AGENTS.md`**: remova. Agora que Claude lê o arquivo diretamente, o hook adiciona uma segunda cópia ao seu contexto.
Se você vem de Cursor, cobrimos a migração completa em [Como mudar de Cursor para Claude Code sem perder o contexto do projeto](https://www.yodev.dev/t/como-cambiar-de-cursor-a-claude-code-sin-perder-el-contexto-del-proyecto/5191).
## Por que Anthropic demorou tanto para suportar AGENTS.md?
A issue do GitHub [#6235](https://github.com/anthropics/claude-code/issues/6235), "Feature Request: Support AGENTS.md", pedia exatamente isso e apontava que Codex, Amp, Cursor e outros estavam se padronizando nesse arquivo. [VERIFICAR: data de abertura / número de reações] Os próprios comentaristas o descrevem como a issue mais votada do repositório.
Terminou fechada, mas não com uma solução, e sim com uma resposta de Boris Cherny que remetia aos dois workarounds: um `CLAUDE.md` com `@AGENTS.md` ou um symlink. A thread não reagiu bem. A objeção mais repetida: o import é trivial para um único arquivo na raiz, mas um monorepo com dezenas de `AGENTS.md` aninhados precisaria de um `CLAUDE.md` de preenchimento junto a cada um.
A versão 2.1.277 é a solução real que esse fechamento não entregou. A reação no Hacker News foi principalmente alívio com um toque de repreensão: "Time to delete the symlinks" junto a "it's the absolute bare minimum".
> ### A leitura de Grego: isso nunca foi sobre um nome de arquivo
>
> Duas linhas de lógica de fallback demoraram mais de um ano, e ninguém naquela thread do GitHub acreditava que fosse um problema de engenharia. Um `CLAUDE.md` em um repositório público é uma pequena placa de publicidade: cada desenvolvedor que o clona vê qual ferramenta o time usa. `AGENTS.md` é terreno neutro: Codex, Cursor e Amp já o leem.
>
> Dar suporte nativo é Anthropic reconhecer que esse terreno neutro é onde a configuração dos times vai viver. Mas veja a forma da concessão: `CLAUDE.md` ainda ganha por padrão, o ajuste não pode ser versionado no nível do projeto e `.agents/` ainda é ignorado. É interoperabilidade nos termos de Claude.
>
> Para um CTO, a conclusão prática é mais simples que a política: se seus times combinam agentes de código, adote `AGENTS.md` como fonte da verdade agora e trate o arquivo próprio de cada ferramenta como uma camada opcional em cima. Todas as ferramentas principais já o leem. O arquivo do qual seu repositório depende não deveria levar o nome de um fornecedor.
Para outro ângulo da mesma briga por configuração entre ferramentas, veja como Codex foi na direção contrária e começou a importar a configuração de Claude Code: [Um Comando e Codex Traz Toda sua Config de Cursor e Claude Code, assim funciona import](https://www.yodev.dev/t/un-comando-y-codex-se-trae-toda-tu-config-de-cursor-y-claude-code-asi-funciona-import/4085).
https://code.claude.com/docs/en/memory