Claude Code agora lê AGENTS.md: como usar e quando seu CLAUDE.md o bloqueia

Devy · Setembro 19, 2026, 3:01pm

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.md e .claude/AGENTS.md do seu diretório de trabalho e dos diretórios superiores. Em uma sessão interativa você verá uma linha como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
Enquanto trabalha em subdiretórios, carrega o AGENTS.md daquele subdiretório quando abre um arquivo lá com a ferramenta Read, desde que o subdiretório não tenha seu próprio CLAUDE.md.
Dentro de cada AGENTS.md, os imports @path se expandem e os padrões de claudeMdExcludes se aplicam, igual que com CLAUDE.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.md ou CLAUDE.local.md no seu diretório de trabalho ou em qualquer diretório superior.
Não contam (se carregam junto com AGENTS.md): seu ~/.claude/CLAUDE.md pessoal, o CLAUDE.md gerenciado 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:

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.
Execute claude --version e confirme que você tem a versão 2.1.277 ou posterior.
Verifique se sua sessão é uma das que não suportam o recurso (próxima seção).
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:

@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.

Por que Anthropic demorou tanto para suportar AGENTS.md?

A issue do GitHub #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.

Tópico	Respostas	Visualizações
Claude-howto: El Camino de Aprendizaje que Llena el Hueco Entre los Docs de Claude Code y los Workflows Reales Claude Code mcp , claude-code , sub-agents , hooks , slash-commands , templates	51	31 de Março de 2026
Claude Code en 2026: Lo que cambió y por qué importa Claude Code	56	17 de Fevereiro de 2026
Un archivo CLAUDE.md se convirtió en ecosistema AI Dev Tools — General claude-code , agent-skills , github-trending , karpathy , llm-wiki	85	26 de Abril de 2026
Qué tiene el CLAUDE.md de Andrej Karpathy y cómo usarlo en tu proyecto AI Dev Tools — General cursor , vs-code , claude-code , plugins , ai-coding	541	12 de Abril de 2026
Claude Code Spends ~16% of Your Tokens on a Status Line: How to Measure agent_summary and Turn It Off ✅ yoDEV Tested Claude Code bun , claude-code , tokens , agentes-de-ia , yodev-tested , opentelemetry	24	29 de Outubro de 2026