Claude Code + AGENTS.md: como ativar a leitura nativa

Como configurar Claude Code e AGENTS.md: resposta curta

Siga esta sequência:

1. Execute claude --version. É preciso usar a v2.1.277 ou posterior.
2. Atualize se necessário. Na instalação nativa, use claude update; Homebrew e WinGet exigem os comandos de atualização dos próprios gerenciadores de pacotes.
3. Confirme que a sessão consegue buscar as feature flags da Anthropic. O carregamento nativo de AGENTS.md não está disponível em sessões de provedores externos, como Amazon Bedrock, Agent Platform do Google Cloud e Microsoft Foundry, nem quando configurações de telemetria ou de tráfego não essencial impedem essa consulta.
4. Coloque AGENTS.md ou .claude/AGENTS.md no caminho do projeto. No modo padrão, verifique se não existe um CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md do projeto no diretório de trabalho ou acima dele.
5. Se você precisa das duas famílias de arquivos, abra /config e defina Project instructions como claude-md-and-agents-md.
6. Faça o teste em uma sessão nova. A primeira sessão após a instalação ou atualização é uma exceção, então abra a próxima antes de avaliar o comportamento.

Esse é o caminho nativo. Se Project instructions não aparecer em /config, mantenha em CLAUDE.md a importação documentada @AGENTS.md.

Como o Claude Code escolhe o arquivo

O novo comportamento funciona como um seletor, não como uma varredura irrestrita de todos os arquivos de instruções. No modo padrão claude-md-or-agents-md, o Claude Code procura primeiro as instruções Claude no nível do projeto. O AGENTS.md só entra como fallback quando nenhum dos arquivos Claude válidos existe no diretório de trabalho ou acima dele.

O detalhe menos óbvio está no escopo. Um CLAUDE.local.md em um diretório pai desativa o fallback. Já um ~/.claude/CLAUDE.md pessoal, um CLAUDE.md gerenciado pela organização e .claude/rules/ não fazem isso. Essa diferença explica muitos casos em que duas pessoas abrem o mesmo repositório e observam comportamentos distintos.

Quando o fallback se aplica, o Claude Code lê AGENTS.md e .claude/AGENTS.md no diretório de trabalho e nos diretórios acima dele durante o início da sessão. O AGENTS.md de um subdiretório pode ser carregado depois, quando o Claude lê um arquivo naquele local, desde que o subdiretório não tenha seu próprio arquivo Claude válido. O Claude Code não lê diretamente AGENTS.local.md, AGENTS.override.md nem arquivos dentro de .agents/.

O mecanismo se parece mais com o seletor elétrico de um prédio do que com uma busca em pastas. Primeiro, o seletor escolhe qual circuito de instruções fica ativo. Os arquivos no outro circuito podem estar perfeitamente válidos e, ainda assim, continuar desconectados.

Escolha de propósito o modo Project instructions

Abra /config, localize Project instructions e selecione a opção de acordo com a fonte de verdade que o repositório deve usar:

• Fallback, claude-md-or-agents-md: ideal para um repositório que já usa AGENTS.md e não possui um arquivo Claude no projeto. É o padrão.
• Ambos, claude-md-and-agents-md: ideal quando o AGENTS.md reúne regras compartilhadas e o CLAUDE.md acrescenta orientações específicas para Claude.
• Somente Claude, claude-md: ideal quando a equipe ainda não quer disponibilizar instruções compartilhadas de agentes ao Claude Code.
• Somente gerenciado, managed-only: ideal para um ambiente de inicialização controlado, no qual a política da organização e a memória automática devem ser carregadas, mas as instruções do repositório não devem entrar na inicialização.

No modo que carrega ambos, o Claude Code lê o conteúdo Claude de cada diretório antes do conteúdo AGENTS. Ele também evita carregar o mesmo AGENTS.md duas vezes quando o CLAUDE.md já o importa ou aponta para ele por meio de um link simbólico.

A escolha passa a valer a partir da mensagem seguinte e continua ativa em novas sessões. Ela também pode ficar no plugin integrado agents-md@builtin nas configurações do usuário, em um arquivo --settings ou nas configurações gerenciadas. O Claude Code ignora essa opção nos arquivos de configuração locais e do projeto, portanto o repositório não consegue impor silenciosamente a mesma seleção a todas as pessoas. Um administrador pode centralizar a escolha por meio das configurações gerenciadas.

Confirme qual arquivo uma sessão nova carregou

Use uma informação inofensiva, nunca uma instrução destrutiva. Adicione esta linha ao arquivo que você quer testar:

Project probe: BASALT-HERON.

Depois, encerre a sessão, inicie uma nova no repositório e pergunte: What is the project probe? Se a resposta for BASALT-HERON, o conteúdo chegou ao contexto da sessão. Remova a linha ao terminar o teste.

Não use /context como único veredito. Um AGENTS.md carregado diretamente não aparece na lista Memory files. No fallback padrão, uma sessão interativa pode exibir a linha AGENTS.md loaded durante a inicialização. Perguntar pela informação inofensiva também funciona nos outros modos de seleção.

Se a verificação falhar, confira estes itens na ordem:

1. Versão: v2.1.277 ou posterior.
2. Número da sessão: não pode ser a primeira sessão depois da instalação ou atualização.
3. Provedor: não pode ser uma sessão cujo provedor impeça a consulta às feature flags da Anthropic.
4. Ambiente: nenhuma variável de telemetria ou de tráfego não essencial pode ter desativado essa consulta.
5. Plugin e política: o plugin integrado agents-md precisa estar habilitado, e nem disableAllHooks nem allowManagedHooksOnly podem bloqueá-lo.
6. Hierarquia de arquivos: no modo padrão, não pode existir um CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md válido no nível atual ou acima dele.
7. Modo: /config precisa apontar para o comportamento desejado.

Se Project instructions não estiver disponível em /config, isso já serve como pista de diagnóstico. A sessão usa uma versão incompatível ou não consegue acessar o recurso.

Mantenha a importação quando o suporte nativo não funcionar

A importação existente continua sendo a camada de compatibilidade mais segura para Bedrock, Vertex, Foundry, outros provedores externos, ambientes com restrições de telemetria e equipes que misturam versões. Coloque o trecho abaixo em um CLAUDE.md ao lado do AGENTS.md:

@AGENTS.md

As instruções específicas para Claude podem vir abaixo. O Claude lê primeiro o arquivo compartilhado importado e, depois, os complementos específicos. Manter essa ponte não causa carregamento duplicado quando uma pessoa com suporte seleciona o modo que usa os dois arquivos.

Um link simbólico de CLAUDE.md para AGENTS.md também funciona, mas a importação é a alternativa mais segura entre plataformas. No Windows, criar links simbólicos pode exigir privilégios elevados ou o Modo de Desenvolvedor, e o Git precisa da configuração correta para links simbólicos. Um hook SessionStart que imprime o conteúdo de AGENTS.md deve ser removido assim que o carregamento direto funcionar, pois ele pode injetar uma cópia duplicada.

A mudança altera o custo de manutenção. Antes, uma equipe com uma política comum a vários agentes geralmente mantinha dois arquivos, um pequeno importador ou um hook. Nas sessões compatíveis, o caminho padrão agora pode se resumir a um único arquivo de instruções versionado. O preço da licença Claude não diminui: a Anthropic inclui o Claude Code no plano Pro mensal de $20. A economia vem da redução dos pontos de sincronização e das sessões que operam com regras desatualizadas.

Para concluir a configuração, o guia mais amplo do Claude Code explica instalação, contexto de projeto e o fluxo diário de comandos. Se o repositório também define agentes especialistas, o guia de subagentes detalha o contexto de inicialização separado de cada um.

Sete situações em que esse recurso vale a pena

Os casos abaixo estão ordenados pelo tamanho do problema de coordenação que o novo seletor elimina.

Os três primeiros casos oferecem o maior retorno porque a falha se multiplica entre pessoas e repositórios. Em um repositório individual com apenas um agente, a conveniência existe, mas é pequena.

O que você pode construir a partir disso

1. Um verificador de instruções para vários agentes

Crie uma CLI local e uma checagem de CI que expliquem exatamente quais arquivos de instruções cada agente de código vai carregar. Equipes de plataforma e consultorias pagariam por uma resposta confiável antes de aplicar a configuração em vários repositórios.

A demanda já é visível: claude code setup recebe cerca de 1,900 buscas mensais nos EUA, enquanto claude md vs agents md chega a 480 e cresceu 1,500% em relação ao ano anterior. A menor versão vendável varre a árvore de arquivos, lê a versão do Claude Code e a configuração do provedor, sinaliza arquivos que ocultam outros e mostra um plano da ordem de carregamento. Uma camada paga para equipes poderia impor a mesma política em vários repositórios.

Essa é a oportunidade mais forte porque resolve um problema de diagnóstico, não de template. O risco é depender demais da plataforma. A Anthropic pode incorporar essas verificações ao claude doctor; por isso, um produto durável precisa abranger vários agentes de código e manter um histórico das mudanças de política, em vez de se limitar a um comando do Claude.

2. Um modelo inicial de AGENTS.md com linter

Crie um editor guiado que transforme comandos de build, regras de teste, limites entre diretórios e requisitos de revisão em um AGENTS.md conciso, seguido de verificações de conflitos e linguagem vaga. Pequenas equipes de engenharia que estão adotando vários agentes são o público comprador.

agents md recebe cerca de 2,900 buscas mensais nos EUA. A consulta mais específica agents md best practices chega a 210 e cresceu 750% em relação ao ano anterior. Um MVP precisa de um scanner de repositório, uma entrevista curta, um rascunho gerado e regras de lint para instruções duplicadas ou contraditórias. O resultado deve respeitar a recomendação do provedor por arquivos de projeto concisos, em vez de produzir um manual de políticas gigantesco.

O ponto fraco é a baixa diferenciação. Qualquer agente de código consegue redigir Markdown. O produto só se justifica se a validação refletir a ordem real de carregamento e comprovar que cada ferramenta de código compatível consumiu o resultado.

3. Uma auditoria de migração para ambientes mistos

Ofereça um relatório que mapeie CLAUDE.md, AGENTS.md, importações, links simbólicos, hooks, regras aninhadas e exceções de provedores, e então gere um plano seguro de migração para uma única fonte. Agências e equipes maiores com diversas ferramentas de agentes são os compradores mais prováveis.

As 480 buscas mensais por claude md vs agents md, com alta de 1,500% em relação ao ano anterior, são um sinal especialmente direto dessa confusão. O MVP pode ser um analisador de repositório somente leitura acompanhado de um plano de pull request. Ele nunca deve excluir uma ponte automaticamente, pois sessões incompatíveis ainda podem precisar dela.

O risco é uma janela curta de relevância. À medida que as equipes convergirem para uma convenção estável de arquivo compartilhado, as migrações pontuais vão diminuir. Auditorias recorrentes de políticas e verificações de compatibilidade entre provedores precisam se tornar o serviço principal.

Limites e uma avaliação honesta

O fallback nativo elimina uma ponte. Ele não transforma instruções de projeto em mecanismos de controle, não torna todos os provedores compatíveis nem resolve regras conflitantes. A Anthropic descreve os arquivos de instruções como contexto. Se um comando sempre precisar ser bloqueado, use uma regra de permissão ou um hook PreToolUse.

O recurso também não faz o AGENTS.md aparecer nos mesmos diagnósticos que o CLAUDE.md. Um carregamento direto não é exibido em /memory nem na lista Memory files de /context. Essa inconsistência é um bom motivo para manter a informação inofensiva de verificação no checklist de migração.

Não remova uma importação funcional de um ambiente com vários provedores só porque o teste nativo passou em um notebook. Não selecione o modo que carrega ambos sem antes revisar contradições. O conteúdo Claude é lido antes do conteúdo AGENTS dentro de um diretório, mas a ordem no contexto não estabelece uma precedência rígida de políticas.

Ainda assim, a versão representa uma melhoria operacional importante. Um repositório que já trata AGENTS.md como fonte compartilhada agora pode trabalhar com Claude Code sem fingir que o segundo nome de arquivo é a fonte real. É um recurso pequeno com grande efeito sobre a coordenação.

Se você quer um sistema confiável de instruções para vários agentes nos seus repositórios, posso ajudar com a arquitetura e a implantação dos agentes.