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. Num repositório usado por mais de um agente de código, o arranjo que não falha é ter uma fonte só: as instruções no AGENTS.md e um CLAUDE.md com uma única importação @AGENTS.md. Isso resolve qual arquivo o agente lê. Não resolve a regra que precisa chegar também a um assistente de chat, a outro agente ou a uma pessoa fora do repositório, nem a regra que muda sem o código mudar — essas precisam morar fora dos dois arquivos, com quem decidiu e quando deixam de valer, e é isso que a Arroway guarda.
Ú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.
Uma fonte para dois arquivos
Mantenha o AGENTS.md como o arquivo compartilhado e deixe no CLAUDE.md uma linha, @AGENTS.md, seguida do que for específico do Claude Code. A importação é expandida na abertura, o Claude Code não lê o arquivo importado duas vezes, e ela 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 serve, 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. Na sessão seguinte, rode /context e confira se o arquivo aparece em Memory files.
Onde um arquivo só para de escalar
A importação resolve qual arquivo é lido. Três coisas ela não toca. 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. O arquivo fica com o que é do repositório: como compilar, testar e organizar o código.
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 trocam o CLAUDE.md por uma única linha @AGENTS.md, e os dois agentes passam a ler o mesmo arquivo. 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 chega 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?
- Não, se o Claude Code é o seu único agente de código: um CLAUDE.md basta. Se outros agentes no mesmo repositório leem o AGENTS.md, mantenha o AGENTS.md como fonte única e um CLAUDE.md que só o importa, mais o que for específico do Claude Code. Dois arquivos independentes é justamente o arranjo em que um deles deixa de ser lido sem ninguém saber.
- 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?
- Não. O arquivo continua sendo o lugar certo para o que é do repositório. A Arroway é para as regras e decisões que precisam chegar a toda ferramenta e a toda pessoa de um projeto, levar quem as decidiu e sair da leitura quando são substituídas. 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