# O Claude Code lê agora AGENTS.md: o que mudou na versão 2.1.277
> A 18 de setembro de 2026, o Claude Code 2.1.277 passou a suportar diretamente AGENTS.md: quando o ficheiro é carregado, como escolher um de 4 modos e o que fazer com as importações.
Source: https://ailoot.ai/blog/pt-pt/claude-code-agents-md-support/
Canonical: https://ailoot.ai/blog/pt-pt/claude-code-agents-md-support/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-041
Revision: sha256-95bba56b4dc4cd76d6a4726f39fe74b256900144e041a98d3a3aa702bb13277e
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](https://ailoot.ai/blog/pt-pt/agents-md-claude-md-one-instruction-file/).
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](https://ailoot.ai/docs/).
[Guias Ailoot](https://ailoot.ai/docs/)
## O que mudou na versão 2.1.277?
Conclusão principal
A partir de 18 de setembro de 2026, o Claude Code lê `AGENTS.md` por predefinição se não existir nenhum `CLAUDE.md`, `.claude/CLAUDE.md` ou `CLAUDE.local.md` na cadeia de diretórios desde o diretório de trabalho até aos diretórios acima. Se existir um desses ficheiros, a leitura automática de `AGENTS.md` através de Project instructions não fica ativada. A importação explícita `@AGENTS.md` a partir de `CLAUDE.md` continua a funcionar. O ficheiro pessoal `~/.claude/CLAUDE.md`, os ficheiros `CLAUDE.md` geridos pela organização e os ficheiros `.claude/rules/` são carregados independentemente da escolha entre ficheiros do projeto. O modo é alterado através de `/config`. A funcionalidade ainda não está disponível em Bedrock, Vertex ou Foundry.
O ficheiro oficial CHANGELOG.md do projeto Claude Code no GitHub descreve a alteração da seguinte forma:
Adicionado suporte para AGENTS.md: num projeto sem CLAUDE.md, o Claude Code lê AGENTS.md em alternativa; altere esta opção em "Project instructions" em /config (ainda não disponível em Bedrock, Vertex ou Foundry)
— Anthropic, commit ca02e7d do CHANGELOG.md de claude-code, https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3
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
Conclusão principal
No modo predefinido, são verificados `CLAUDE.md`, `.claude/CLAUDE.md` e `CLAUDE.local.md` no diretório de trabalho e nos diretórios acima. O ficheiro pessoal `~/.claude/CLAUDE.md`, os ficheiros `CLAUDE.md` geridos pela organização e os ficheiros `.claude/rules/` não impedem a leitura de `AGENTS.md` e são carregados juntamente com ele.
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](https://ailoot.ai/docs/).
[Guias Ailoot](https://ailoot.ai/docs/)
## 4 modos de Project instructions—qual escolher
Conclusão principal
Na secção Project instructions do comando `/config`, existem quatro valores: `claude-md-or-agents-md` (predefinição—um dos dois ficheiros), `claude-md-and-agents-md` (ambos em conjunto), `claude-md` (só `CLAUDE.md` é lido automaticamente, mesmo que o projeto tenha apenas `AGENTS.md`) e `managed-only` (no arranque—apenas o `CLAUDE.md` gerido pela organização e a memória automática, sem ficheiros do projeto ou pessoais). A alteração produz efeito a partir da mensagem seguinte e em todas as novas sessões.
O comportamento dos modos na tabela é descrito na documentação da Anthropic. A coluna da direita apresenta recomendações para escolher um modo:
| Valor | O que o Claude Code lê | Quando utilizar |
|----|----|----|
| `claude-md-or-agents-md` | `CLAUDE.md` ou `AGENTS.md` se não existir nenhum `CLAUDE.md`, `.claude/CLAUDE.md` ou `CLAUDE.local.md` no diretório de trabalho ou nos diretórios acima | Predefinição, se o repositório utilizar apenas um dos dois ficheiros e não existirem ficheiros que bloqueiem a leitura nos diretórios acima |
| `claude-md-and-agents-md` | Ambos os ficheiros em conjunto: em cada diretório, primeiro `CLAUDE.md` e depois `AGENTS.md` | Precisa de um `AGENTS.md` partilhado por todas as ferramentas e de um `CLAUDE.md` curto apenas para o Claude; ou precisa de ler `AGENTS.md` quando existe `CLAUDE.local.md` |
| `claude-md` | Apenas `CLAUDE.md`; a leitura automática de `AGENTS.md` através de Project instructions está desativada, mesmo que `AGENTS.md` seja o único ficheiro (uma importação explícita `@AGENTS.md` a partir de `CLAUDE.md` continua a funcionar) | `AGENTS.md` foi escrito para outra ferramenta e pode confundir o Claude |
| `managed-only` | No início da sessão—apenas o `CLAUDE.md` gerido pela organização e a memória automática; os ficheiros `CLAUDE.md` do projeto, locais e do utilizador, `.claude/rules/` e todos os ficheiros `AGENTS.md` são excluídos do conjunto inicial. No entanto, os ficheiros `CLAUDE.md` e `.claude/rules/` em subdiretórios continuam a ser carregados mais tarde, quando o Claude abre aí um ficheiro. O modo limita o conjunto inicial, mas não proporciona isolamento total dos ficheiros do projeto | Para organizações que se preocupam com o conjunto de instruções com que o Claude Code inicia uma sessão, independentemente de o projeto conter `CLAUDE.md` ou `AGENTS.md` |
Também pode escolher o modo sem utilizar a interface, através de `settings.json`:
```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](https://ailoot.ai/blog/pt-pt/agents-md-claude-md-one-instruction-file/) explicam como funciona a importação `@`. Este método continua a funcionar.
## Porque não aparece Project instructions em /config
Conclusão principal
Segundo a documentação da Anthropic, a secção Project instructions pode não aparecer pelas seguintes razões:
- A versão do Claude Code é anterior à 2.1.277.
- A sessão não recebe sinalizadores de funcionalidades da Anthropic—por exemplo, ao utilizar Bedrock, outro fornecedor terceiro ou quando a telemetria está desativada.
- Esta é a primeira sessão imediatamente após a instalação ou atualização de uma versão anterior. Se for esse o único motivo, a funcionalidade aparecerá na sessão seguinte. O próprio `AGENTS.md` só será carregado se forem cumpridas as condições do modo selecionado.
- O plug-in integrado `agents-md` está desativado em `/plugin`.
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
Conclusão principal
Pode manter a importação `@AGENTS.md` em `CLAUDE.md` e a ligação simbólica: o ficheiro não será lido duas vezes em nenhum dos modos. Se mantiver `CLAUDE.md`, substitua um pedido textual para “ler AGENTS.md” por uma importação. Antes de eliminar um ficheiro, guarde todas as instruções necessárias e verifique as condições do modo selecionado. Se mudar para a leitura direta, remova qualquer hook `SessionStart` que imprimisse manualmente o conteúdo de `AGENTS.md`; caso contrário, será adicionada ao contexto uma segunda cópia do ficheiro. Depois, verifique o carregamento numa nova sessão; a forma de o fazer depende da versão e da existência de ficheiros que bloqueiem a leitura.
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
Conclusão principal
A partir da versão 2.1.280, `AGENTS.md` carregado através de Project instructions aparece em `/memory` e na lista Memory files do comando `/context`. Nas versões 2.1.277–2.1.279, não aparece nesses locais, apesar de os próprios comandos funcionarem e mostrarem `CLAUDE.md` e outros ficheiros de memória carregados. Nestas versões, se não existirem ficheiros que bloqueiem a leitura, procure a linha `AGENTS.md loaded` no arranque da sessão. Perguntar ao Claude sobre o conteúdo das instruções é apenas uma verificação pouco fiável: a resposta não permite distinguir a leitura direta de uma importação `@` e pode basear-se no texto acrescentado por um hook `SessionStart`. Por isso, só faz sentido perguntar numa nova sessão, depois de remover esse hook.
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](https://ailoot.ai/blog/pt-pt/claude-md-template/). 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](https://ailoot.ai/blog/pt-pt/claude-code-second-brain/)—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.
### Fontes
- [Claude Code, commit do CHANGELOG.md com a entrada da versão 2.1.277 no GitHub (18 de setembro de 2026)](https://github.com/anthropics/claude-code/commit/ca02e7deeb0707f558b0afd7e9e5d67a382e12b3)
- [Documentação do Claude Code: Como o Claude se lembra do seu projeto - secção AGENTS.md](https://code.claude.com/docs/en/memory)
[Guias Ailoot](https://ailoot.ai/docs/)
[Ir para Ailoot](https://ailoot.ai/)
## Perguntas frequentes
### Porque não é carregado o AGENTS.md, apesar de o ficheiro existir?
No modo predefinido, um CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md na pasta de trabalho ou num antepassado bloqueia a seleção automática de AGENTS.md. Verifique também a versão, a disponibilidade da funcionalidade e o modo Project instructions em /config.
### Como verifico o carregamento direto depois de remover um hook manual?
Abra uma sessão nova para excluir a saída antiga de SessionStart. Na versão 2.1.280 ou posterior, consulte /memory ou a lista Memory files em /context; nas versões 2.1.277-2.1.279, aplica-se a linha de carregamento no arranque quando não há CLAUDE.md bloqueadores. Uma paráfrase do Claude é evidência fraca.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.