O Claude Code lê agora AGENTS.md: o que mudou na versão 2.1.277

A 18 de setembro de 2026, foi adicionado suporte para AGENTS.md no Claude Code 2.1.277. Se a funcionalidade estiver disponível na sessão e, na cadeia de diretórios acima do diretório de trabalho, não existir nenhum CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md, o Claude Code lê AGENTS.md por predefinição, sem importação manual. Anteriormente, isto era feito através de uma importação @AGENTS.md em CLAUDE.md ou de uma ligação simbólica CLAUDE.md para AGENTS.md—para mais detalhes, consulte o artigo sobre um ficheiro de instruções para vários agentes.

Se utiliza o Claude Code e mais uma ou duas ferramentas no mesmo repositório, o modo Project instructions que escolher determina que ficheiros de instruções o Claude Code lê. Seguem-se as condições de cada um dos quatro modos e os passos para mudar da configuração antiga.

Pode encontrar mais materiais sobre a configuração de ferramentas na documentação da Ailoot.

O que mudou na versão 2.1.277?#

O ficheiro oficial CHANGELOG.md do projeto Claude Code no GitHub descreve a alteração da seguinte forma:

Tradução: foi adicionado suporte para AGENTS.md—num projeto sem CLAUDE.md, o Claude Code lê agora AGENTS.md em alternativa; esta opção pode ser alterada em “Project instructions” em /config (ainda não disponível em Bedrock, Vertex ou Foundry).

Antes desta versão, a ausência de CLAUDE.md, .claude/CLAUDE.md e CLAUDE.local.md no diretório de trabalho e nos diretórios acima não bastava, por si só, para ativar a leitura de AGENTS.md. Era necessária uma importação explícita, uma ligação simbólica ou um hook manual. Agora, quando a funcionalidade está disponível, o agente carrega o ficheiro automaticamente.

Que ficheiros impedem a leitura automática de AGENTS.md#

Se tiver um ~/.claude/CLAUDE.md pessoal com definições de estilo de programação, isso não impedirá o Claude Code de ler o AGENTS.md do projeto. No entanto, qualquer CLAUDE.local.md no diretório de trabalho—mesmo que não esteja adicionado ao Git e seja utilizado para notas pessoais—impede a leitura automática de AGENTS.md no modo predefinido. A importação explícita continua a funcionar; para ler ambos os ficheiros diretamente, tem de mudar de modo.

Se estiver selecionado um modo de leitura direta em Project instructions (consulte “4 modos de Project instructions—qual escolher”, abaixo) e não existir nenhum CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho ou nos diretórios acima, o Claude Code lê todos os ficheiros AGENTS.md e .claude/AGENTS.md nesses diretórios quando a sessão é iniciada. Quando não existem ficheiros que bloqueiem a leitura, a documentação mostra uma linha semelhante a esta numa sessão interativa:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

Um ficheiro AGENTS.md num subdiretório é carregado quando o Claude abre um ficheiro aí com a ferramenta Read. No modo claude-md-or-agents-md, isto só acontece se esse subdiretório não tiver o seu próprio CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md. Para claude-md-and-agents-md, a documentação descreve a regra geral: CLAUDE.md e AGENTS.md são lidos em conjunto, primeiro CLAUDE.md e depois AGENTS.md em cada diretório. AGENTS.local.md, AGENTS.override.md e tudo o que esteja no diretório .agents/ não são lidos automaticamente.

Pode encontrar materiais sobre a configuração do espaço de trabalho de um agente de IA, incluindo ficheiros de instruções com contexto do projeto, na documentação da Ailoot.

4 modos de Project instructions—qual escolher#

O comportamento dos modos na tabela é descrito na documentação da Anthropic. A coluna da direita apresenta recomendações para escolher um modo:

Também pode escolher o modo sem utilizar a interface, através de settings.json:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

O Claude Code ignora este valor nas definições project e local. Segundo a documentação da Anthropic, pode defini-lo em ~/.claude/settings.json, num ficheiro --settings ou nas definições geridas pela organização.

Se já tiver configurado um ficheiro de instruções partilhado para várias ferramentas de IA num repositório, as instruções para versões anteriores à 2.1.277 explicam como funciona a importação @. Este método continua a funcionar.

Porque não aparece Project instructions em /config#

Comece por verificar a versão com o comando claude --version. Se for anterior à 2.1.277, atualize o Claude Code. Se a versão for adequada, mas a secção continuar sem aparecer, verifique os outros motivos indicados acima. Enquanto a funcionalidade não estiver disponível, a importação @AGENTS.md em CLAUDE.md continua a ser uma alternativa funcional.

O que fazer com a antiga importação @AGENTS.md#

Os passos seguintes dependem da configuração antiga. Primeiro, certifique-se de que a funcionalidade está disponível na sua sessão, conforme descrito na secção anterior.

• CLAUDE.md com uma importação @AGENTS.md. Pode deixá-lo como está—o Claude Code não lerá o ficheiro duas vezes com qualquer valor de Project instructions. Eliminar CLAUDE.md é opcional: a importação já dá ao Claude acesso ao conteúdo de AGENTS.md. Continue a verificar o carregamento através da importação com /memory; perguntar diretamente ao Claude sobre o conteúdo das instruções é apenas uma verificação pouco fiável.
• CLAUDE.md que pede por palavras que se leia AGENTS.md. Esse pedido não é uma importação e, por si só, não garante que o ficheiro seja carregado. Se quiser manter CLAUDE.md (por exemplo, para ferramentas que também o leem), substitua a formulação por uma importação @AGENTS.md. Se decidir eliminar completamente CLAUDE.md e tiver selecionado o modo claude-md-or-agents-md, confirme primeiro que CLAUDE.md não contém instruções exclusivas e que não existe outro CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho ou nos diretórios acima; caso contrário, o Claude Code continuará a ler o ficheiro restante em vez de AGENTS.md. Depois de o eliminar, confirme que a transição ocorreu: quando já não existirem ficheiros que bloqueiem a leitura, a linha AGENTS.md loaded aparece numa sessão interativa. Se CLAUDE.md permanecer e ambos os ficheiros forem lidos no modo claude-md-and-agents-md, verifique /memory (na versão 2.1.280+). Uma pergunta direta ao Claude não permite distinguir a leitura direta de uma importação.
• Ligação simbólica CLAUDE.md para AGENTS.md. Pode mantê-la: não haverá leitura duplicada em nenhum dos modos. Antes de eliminar a ligação no modo claude-md-or-agents-md, confirme que as instruções necessárias estão preservadas e que não existe outro CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho ou nos diretórios acima. Verifique o carregamento da mesma forma: pela linha AGENTS.md loaded no início da sessão, quando não existirem ficheiros que bloqueiem a leitura, ou através de /memory (2.1.280+). Se CLAUDE.md permanecer no modo claude-md-and-agents-md, uma pergunta direta ao Claude é apenas uma verificação pouco fiável. A ausência de um erro não é suficiente para confirmar o carregamento.
• Um hook SessionStart que imprimia manualmente o conteúdo de AGENTS.md. Quando o ficheiro é lido diretamente, esse hook acrescenta uma segunda cópia ao contexto. Enquanto o hook estiver ativo, perguntar “o que está nas suas instruções?” não confirma a leitura direta: Claude pode responder com base no texto acrescentado pelo hook. Siga esta ordem para mudar:
  1. Confirme que a funcionalidade está disponível: versão 2.1.277 ou superior, a sessão recebe sinalizadores de funcionalidades, o plug-in está ativado e já decorreu a primeira sessão após a instalação ou atualização. Escolha um modo de leitura direta—nem claude-md nem managed-only. No modo predefinido, confirme também que não existem ficheiros que bloqueiem a leitura.
  2. Remova o hook.
  3. Feche a sessão e abra uma nova. O hook SessionStart acrescenta o texto no arranque, pelo que o respetivo conteúdo permanece no contexto de uma sessão já aberta. A resposta do Claude sobre o conteúdo das instruções nessa sessão não confirma a leitura direta.
  4. Verifique o carregamento na nova sessão. Na versão 2.1.280+, o caminho para AGENTS.md é visível em /memory. Nas versões 2.1.277–2.1.279, se não existirem ficheiros que bloqueiem a leitura, procure a linha AGENTS.md loaded no arranque: a documentação descreve-a especificamente para o caso em que não foi encontrado nenhum CLAUDE.md. Se mantiver CLAUDE.md e utilizar o modo claude-md-and-agents-md, a verificação é limitada: nestas versões, /memory não mostra AGENTS.md, a documentação não descreve uma linha de carregamento para este caso e uma paráfrase das instruções não permite distinguir a leitura direta de uma importação @ dentro de CLAUDE.md. Nesse caso, atualize para a versão 2.1.280+ e verifique /memory.

Como verificar se AGENTS.md foi carregado#

Existem ainda duas diferenças em relação ao CLAUDE.md normal: os hooks InstructionsLoaded não são acionados por este tipo de AGENTS.md (funcionam com AGENTS.md importado através da sintaxe @ a partir de CLAUDE.md ou ligado através de uma ligação simbólica CLAUDE.md); os diretórios adicionados com a opção --add-dir juntamente com a variável CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD carregam apenas o CLAUDE.md desse diretório—o respetivo AGENTS.md não é incluído.

Se precisar de rever o conteúdo de um ficheiro de instruções de projeto extenso, consulte a análise separada sobre como configurar CLAUDE.md sem o tornar demasiado extenso. Aborda a estrutura das instruções, enquanto as condições de carregamento de AGENTS.md são descritas acima. Para notas de trabalho entre sessões, consulte a análise sobre um segundo cérebro no Claude Code—sobre memória pessoal em camadas sobre as instruções do projeto.

O que fazer a seguir#

A funcionalidade foi lançada a 18 de setembro de 2026, na versão 2.1.277. A Anthropic poderá esclarecer detalhes dos modos em futuras versões; por isso, antes de alterar as definições de um projeto importante, compare este artigo com o /config atual e o changelog oficial.