Respostas
O Claude Code lê o AGENTS.md?
Sim, desde a versão 2.1.277 (18 de setembro de 2026) — mas, por padrão, só quando o projeto não tem CLAUDE.md. Se houver um CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho ou em qualquer diretório acima dele, o Claude Code lê esses e deixa o AGENTS.md de fora, sem erro nenhum. O padrão muda em "Project instructions" no /config, por exemplo para ler os dois arquivos, e uma versão de 24 de setembro estendeu o suporte a Amazon Bedrock, Google Vertex AI, Microsoft Foundry, gateways de LLM e sessões com telemetria desligada. Qual arquivo é carregado decide quais instruções valem, e nada avisa o time. A recomendação da Arroway é deixar os dois arquivos vazios: o que está neles governa toda sessão sem ninguém ver nem aprovar, e nunca chega a um assistente de chat, a outro agente ou a uma pessoa fora do repositório. O que vale vai para a Arroway, com quem decidiu e quando deixa de valer, e toda ferramenta conectada lê isso antes de agir, seja qual for o arquivo que ela carrega.
Última atualização 29 de setembro de 2026
Qual arquivo ganha, e por que a falha é silenciosa
A conferência é simples. O Claude Code procura CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no diretório de trabalho e em todos os diretórios acima. Achou um, essas são as instruções do projeto e o AGENTS.md não carrega. Não achou nenhum, ele carrega todo AGENTS.md desse caminho, e a sessão interativa mostra uma linha avisando. O caso silencioso é o CLAUDE.local.md: uma pessoa do time cria um arquivo pessoal, fora do controle de versão, e dali em diante o Claude Code para de ler o AGENTS.md do time só para ela. Ninguém mais vê a diferença, e nada acusa. A configuração que muda isso é lida das configurações de usuário de cada pessoa, não do repositório — a documentação diz que os arquivos de configuração de projeto e locais a ignoram —, então o time não tem como commitar o conserto.
O que a documentação descreve para dois arquivos
A documentação do Claude Code descreve dois jeitos de os dois arquivos serem lidos como um. Um CLAUDE.md que importa o AGENTS.md com uma linha @AGENTS.md é expandido na abertura, o arquivo importado não é lido duas vezes, e a importação funciona também nas sessões em que o suporte direto ao AGENTS.md não está disponível. Um link simbólico do CLAUDE.md para o AGENTS.md também funciona, com duas pegadinhas que a documentação lista: as ferramentas de edição se recusam a escrever através do link, e no Windows um link commitado pode chegar ao clone como um arquivo de texto de uma linha. Nos dois casos, o /context mostra em Memory files qual arquivo a sessão carregou. Os dois resolvem qual arquivo é lido; nenhum diz quem pôs cada linha ali nem se alguém aprovou.
Onde um arquivo só para de escalar
A importação ou o link resolvem qual arquivo é lido. Três coisas eles não tocam. O arquivo só chega aos agentes de código que trabalham naquele repositório: quem define preço numa janela de chat, ou um agente em outro repositório, nunca o carrega. Uma linha dele não tem como dizer que foi superada, então a regra do mês passado se lê igualzinho à de hoje. E nada nele separa a regra que uma pessoa aprovou da que um assistente anotou. A Arroway guarda essa parte: regras e decisões por projeto, cada uma com quem aprovou e a condição que a encerra, lidas antes de agir por toda ferramenta conectada — Claude, ChatGPT, Codex, Cursor ou qualquer uma via MCP. Por isso a recomendação da Arroway é deixar o arquivo vazio.
Como isso aparece na prática
Um time de três pessoas divide um repositório em que trabalha com o Claude Code e com outro agente de código. Em agosto, mudaram as instruções para o AGENTS.md e mantiveram um CLAUDE.md antigo com os comandos de build. Em setembro, acrescentam uma regra ao AGENTS.md: migração nunca roda a partir de branch de feature. O outro agente segue. O Claude Code acha o CLAUDE.md antigo primeiro e nunca vê a regra. Eles levam a regra para a Arroway, escrita uma vez com o nome de quem decidiu, e os dois agentes a leem no começo de cada sessão, seja qual for o arquivo de instrução que carregam. Uma semana depois, a líder de produto decide numa conversa de chat que o plano gratuito cai de cinco projetos para três. Essa decisão não é sobre o código e nunca teria chegado ao AGENTS.md. Na Arroway ela é escrita uma vez, com o nome dela, como substituta da regra dos cinco projetos — e todo assistente que o time usa, dentro ou fora do repositório, abre a próxima sessão com ela.
Perguntas que as pessoas fazem sobre isso
- Preciso manter CLAUDE.md e AGENTS.md?
- Para regra, nenhum dos dois. Com dois arquivos independentes, um deles deixa de ser lido sem ninguém saber: o Claude Code só lê o AGENTS.md quando não há CLAUDE.md no caminho, a menos que o ajuste Project instructions diga outra coisa. A recomendação da Arroway é deixar os dois vazios e pôr o que vale na Arroway, que todo agente conectado lê no começo do trabalho, seja qual for o arquivo que carrega.
- Como confiro qual arquivo o Claude Code carregou de fato?
- Rode /context ou /memory numa sessão e procure o caminho do arquivo. Quando o Claude Code lê o AGENTS.md porque não há CLAUDE.md, a sessão interativa também mostra uma linha dizendo que nenhum CLAUDE.md foi encontrado e que o AGENTS.md foi carregado. A documentação avisa que antes da v2.1.280 essas listas não mostravam um AGENTS.md lido diretamente; em versão mais antiga, pergunte ao assistente o que dizem as instruções de projeto dele.
- A Arroway substitui o AGENTS.md?
- Para tudo o que precisa valer, sim: a recomendação da Arroway é que nada fique no arquivo. O que está no AGENTS.md governa toda sessão sem ninguém ver nem aprovar. Na Arroway cada regra e cada decisão leva quem a decidiu, chega a toda ferramenta e a toda pessoa do projeto e sai da leitura quando é substituída. Instale na ferramenta que você já usa — a página de instalação tem a rota de cada uma — e a próxima sessão abre lendo o projeto.
Onde isto se confere
Changelog do Claude Code (code.claude.com/docs/en/changelog), entradas 2.1.277 de 18 de setembro de 2026 e 2.1.282 de 24 de setembro de 2026; a documentação de memória do Claude Code (code.claude.com/docs/en/memory), nas seções sobre AGENTS.md, a configuração Project instructions, importações e solução de problemas, lida em 29 de setembro de 2026; a documentação do produto neste site (Como funciona, Instalar); e as regras de sanção, substituição e condição de fim da especificação sancionada do produto. O Claude Code é descrito como a própria documentação dele o descreve nessa data, e o comportamento pode mudar em qualquer versão. Tudo o que está descrito aqui sobre a Arroway é comportamento que as ferramentas aplicam hoje, não roadmap.
https://www.arroway.app/pt-BR/answers/does-claude-code-read-agents-md