Resposta rápida
O Claude Code 2.1.277 ou mais recente lê AGENTS.md como instruções do projeto quando não encontra CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho nem nos diretórios acima dele. Se qualquer um desses arquivos existir nesse caminho, o padrão é carregar CLAUDE.md e ignorar AGENTS.md.
Para usar os dois, abra /config no terminal e mude Project instructions para claude-md-and-agents-md. Em uma sessão compatível, o início da conversa informa que AGENTS.md foi carregado. Se a opção não aparecer, confira a versão, abra uma nova sessão e verifique as limitações do provedor antes de editar o repositório.
O que mudou no Claude Code 2.1.277
A Anthropic publicou a versão 2.1.277 em 18 de setembro de 2026 com suporte nativo a AGENTS.md. Isso permite que um repositório já preparado para diferentes agentes compartilhe instruções com o Claude Code sem precisar criar um CLAUDE.md apenas para redirecionar a leitura.
O recurso é uma escolha de arquivos de instruções, não uma camada de autorização. A documentação da Anthropic explica que instruções entram no contexto e orientam o comportamento do agente, mas não impõem uma regra técnica. Para bloquear comandos, arquivos ou ações, continue usando permissões, hooks e isolamento apropriados.
Quando AGENTS.md é carregado por padrão
Na configuração padrão, o Claude Code procura AGENTS.md e .claude/AGENTS.md no diretório atual e nos diretórios acima dele. Arquivos equivalentes em subdiretórios entram quando o agente lê um arquivo naquela parte do projeto, desde que o próprio subdiretório não tenha um arquivo CLAUDE.md que altere essa escolha.
Um CLAUDE.md pessoal em ~/.claude e instruções gerenciadas pela organização não impedem o AGENTS.md do projeto. Já CLAUDE.local.md no projeto impede a leitura padrão de AGENTS.md, mesmo quando está fora do controle de versão. AGENTS.local.md, AGENTS.override.md e arquivos dentro de .agents não são lidos por esse mecanismo.
- Atualize o Claude Code para a versão 2.1.277 ou mais recente.
- Coloque AGENTS.md na raiz do repositório ou em .claude/AGENTS.md.
- Procure CLAUDE.md, .claude/CLAUDE.md e CLAUDE.local.md no diretório atual e nos diretórios acima.
- Inicie uma nova sessão na raiz correta do repositório.
- Confirme na conversa a linha que informa que AGENTS.md foi carregado.
Como carregar AGENTS.md e CLAUDE.md juntos
Use os dois arquivos quando AGENTS.md contiver regras compartilhadas com outras ferramentas e CLAUDE.md trouxer detalhes específicos do Claude Code. No terminal, abra /config, encontre Project instructions e selecione claude-md-and-agents-md. Nessa opção, o conteúdo de CLAUDE.md aparece antes do AGENTS.md de cada diretório.
A preferência também pode ser definida no arquivo de configuração do usuário pelo plugin integrado agents-md. A Anthropic informa que essa opção é aceita nas configurações do usuário, em um arquivo passado por --settings ou em políticas gerenciadas. Configurações locais ou do próprio projeto são ignoradas para essa escolha. A alteração vale a partir da mensagem seguinte e para novas sessões.
Por que o Claude Code não está lendo AGENTS.md
O motivo mais comum é a presença de um CLAUDE.md ou CLAUDE.local.md no caminho entre o diretório atual e a raiz do sistema. O segundo é usar uma versão anterior à 2.1.277. Também pode ser apenas a primeira sessão depois da atualização: a documentação diz que o suporte passa a valer na sessão seguinte.
O recurso depende do plugin integrado agents-md e da disponibilidade de feature flags da Anthropic. Sessões em Amazon Bedrock ou outro provedor de terceiros, sessões com telemetria desativada e ambientes que bloqueiam hooks podem não mostrar Project instructions em /config. O release original também registrou indisponibilidade em Bedrock, Vertex e Foundry.
- Confira a versão instalada e atualize se ela for anterior à 2.1.277.
- Feche a primeira sessão após a atualização e inicie outra na raiz do projeto.
- Procure os três arquivos CLAUDE.md que têm prioridade no diretório atual e nos diretórios-pai.
- Abra /plugin e confirme que o plugin integrado agents-md não foi desativado.
- Abra /config e verifique se Project instructions está disponível e com a opção esperada.
- Consulte o Claude Status se o comportamento mudar em vários projetos ao mesmo tempo.
Como manter um único arquivo entre vários agentes
Se o ambiente não consegue ler AGENTS.md diretamente ou o projeto precisa manter CLAUDE.md, crie um CLAUDE.md com a linha @AGENTS.md. Esse import mantém AGENTS.md como fonte compartilhada e permite acrescentar abaixo apenas as instruções exclusivas do Claude Code. A documentação afirma que o arquivo importado não é duplicado quando a configuração também habilita AGENTS.md.
Evite escrever apenas uma frase pedindo que o agente abra AGENTS.md. Nesse caso, a leitura depende de uma decisão do modelo durante a sessão. O import é explícito. Um link simbólico também funciona em alguns ambientes, mas pode virar um arquivo de texto comum no Windows; para equipes multiplataforma, o import costuma ser mais previsível.
Como escrever instruções que realmente ajudam
Inclua comandos verificáveis, convenções, arquitetura e fluxos que o agente não deve precisar redescobrir. Prefira instruções curtas como executar npm test antes de um commit, indicar onde ficam os handlers de API ou definir o formato de uma migração. Remova contradições entre arquivos de diretórios diferentes.
Não coloque tokens, cookies, senhas ou chaves em AGENTS.md. O arquivo normalmente faz parte do repositório e seu conteúdo entra no contexto do agente. Também não trate a frase não acesse .env como um controle de segurança: use regras de permissão para negar a leitura e mantenha segredos fora do código versionado.
Limitações e próxima ação útil
AGENTS.md carregado pelo seletor de Project instructions não aparece na lista Memory files de /context e não dispara hooks InstructionsLoaded. Para confirmar a leitura na configuração padrão, procure a mensagem de carregamento no início da sessão ou pergunte ao Claude quais instruções de projeto recebeu. Diretórios adicionados com --add-dir também não carregam automaticamente o AGENTS.md por essa opção.
Este guia foi verificado em 20 de setembro de 2026. Atualize o CLI, abra uma sessão nova na raiz do repositório e teste uma instrução pequena e observável. Se AGENTS.md continuar ausente, use @AGENTS.md dentro de CLAUDE.md como fallback documentado e registre a escolha no projeto para que toda a equipe tenha o mesmo comportamento.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Claude Code v2.1.277Anthropic no GitHub
- How Claude remembers your projectClaude Code Docs
- Settings files and precedenceClaude Code Docs
- Claude StatusAnthropic