Claude Code e AGENTS.md: como funcionam os arquivos de instruções para agentes de IA em 2026

O que é o AGENTS.md e por que ele existe

Por um tempo, cada ferramenta de programação inventou o seu próprio arquivo de instruções. O Cursor tinha .cursorrules, o Claude Code tinha CLAUDE.md, o Aider tinha .aider.conf.yml, o Gemini tinha GEMINI.md, e assim por diante. Se você anotasse o repositório para um agente, teria de fazer tudo de novo para o próximo.

O AGENTS.md é a solução: um formato aberto para orientar agentes de programação, um único arquivo em Markdown simples na raiz do repositório que muitos agentes leem. O projeto o chama de "README for agents", a descrição em uma frase mais clara que já vi. O seu README.md é para humanos (início rápido, guia de contribuição); o AGENTS.md guarda o contexto extra de que um agente precisa (passos de build, testes, convenções) e que poluiria um README.

Não há campos obrigatórios. É só Markdown: use os títulos que quiser e o agente interpreta o texto. Ele surgiu de uma colaboração em todo o ecossistema, incluindo OpenAI Codex, Amp, o Jules do Google, Cursor e Factory, com o primeiro commit em 19 de agosto de 2025. Desde então, mudou-se para um lar neutro e hoje é mantido pela Agentic AI Foundation, sob a Linux Foundation, com o repositório em agentsmd/agents.md sob licença MIT.

Isso não é um experimento de nicho. O repositório tem 24,5k estrelas, uma busca de código no GitHub retorna mais de 60k arquivos de exemplo, e até o repositório da própria OpenAI tem 88 deles. Se você vinha ignorando isso como modinha, este é o ponto em que eu pararia.

Quais agentes realmente o leem

A página inicial lista 24 ferramentas compatíveis, e a lista cobre boa parte da categoria: Zed, OpenAI Codex, Gemini CLI, Cursor, Jules, Devin, Warp, Windsurf, VS Code, o agente de programação do GitHub Copilot, Aider, goose, Amp e outros. E, a partir deste mês, o Claude Code também. Quando tantos fornecedores concorrentes convergem discretamente para o mesmo arquivo simples, o formato basicamente venceu.

O Claude Code lê o AGENTS.md? Sim, agora nativamente

Esta é a pergunta com que a maioria chega, então vai a resposta direta: o Claude Code lê o AGENTS.md nativamente, exigindo a v2.1.277 ou posterior (lançada em 18 de setembro de 2026, quando a Anthropic adotou a especificação multiferramenta). Um repositório que outros agentes já entendem funciona com o Claude Code sem que você adicione um CLAUDE.md, uma linha de importação ou uma configuração.

O problema é o que acontece quando os dois arquivos existem. O comportamento padrão:

Então a armadilha é um CLAUDE.md desatualizado vencendo em silêncio um AGENTS.md bem mantido. Se você quiser os dois, a configuração Project instructions (/config) tem os valores claude-md-or-agents-md (o padrão), claude-md-and-agents-md (ambos, CLAUDE primeiro), claude-md (somente CLAUDE) e managed-only. Vale saber: um CLAUDE.local.md também conta como arquivo da família CLAUDE, então colocar um faz o Claude parar de ler o AGENTS.md até você mudar essa configuração. O seu ~/.claude/CLAUDE.md, os arquivos de política gerenciada e o .claude/rules/ não contam para a verificação "tem um CLAUDE.md", então continuam sendo carregados junto com o AGENTS.md.

Mais uma peculiaridade para guardar: um AGENTS.md lido diretamente não aparece em /memory nem em /context, e os hooks InstructionsLoaded não são disparados para ele. Você confirma que foi carregado pela linha AGENTS.md loaded no início da sessão. Se você é novo na ferramenta, nosso guia de primeiros passos e a referência da CLI cobrem o básico.

CLAUDE.md vs AGENTS.md: a diferença honesta

As pessoas encaram isso como uma rivalidade. Na verdade, não é. O AGENTS.md é o padrão multiferramenta; o CLAUDE.md é o sistema de instruções mais rico do próprio Claude Code. Ambos são Markdown simples, e o Claude agora lê qualquer um.

A leitura prática: se a sua equipe usa uma mistura de agentes de programação, mantenha a fonte da verdade no AGENTS.md. Se você usa só o Claude Code e quer importações ou regras por caminho, o CLAUDE.md oferece mais recursos. E você pode ter os dois, se os ligar de propósito e não por acidente.

Vale dizer com clareza: o CLAUDE.md não vai a lugar nenhum e não é "pior". Ele tem recursos que o AGENTS.md deixa de fora deliberadamente (a especificação é mínima de propósito). Escolher um ou outro depende de quantas ferramentas você usa, não de qual é mais bem construído.

Como o Claude Code carrega os arquivos de instruções

Os arquivos CLAUDE.md são carregados do escopo mais amplo ao mais específico, e tudo o que é encontrado é concatenado em vez de sobrescrito, então as instruções mais próximas de onde você iniciou são lidas por último. Existem quatro escopos:

1. Política gerenciada (em toda a organização, carregada primeiro, não pode ser excluída). Fica em caminhos específicos do sistema operacional, como /Library/Application Support/ClaudeCode/CLAUDE.md no macOS.
2. Usuário (~/.claude/CLAUDE.md), suas preferências pessoais em todos os projetos.
3. Projeto (./CLAUDE.md ou ./.claude/CLAUDE.md), compartilhado com a equipe pelo controle de versão.
4. Local (./CLAUDE.local.md), suas anotações privadas por projeto, que você adiciona ao .gitignore.

A descoberta é recursiva: o Claude carrega arquivos CLAUDE.md do seu diretório de trabalho e de todos os diretórios acima dele. Arquivos em subdiretórios abaixo de você não são carregados na inicialização; eles são trazidos sob demanda quando o Claude lê arquivos nessas pastas. Esse comportamento por subárvore é justamente o que mantém os monorrepositórios sob controle, e espelha o funcionamento do AGENTS.md: vence o arquivo mais próximo, e uma instrução explícita no chat se sobrepõe a tudo. Para dar uma noção de escala, o repositório principal da OpenAI traz 88 arquivos AGENTS.md separados, um por pacote.

Essa divisão por pacote importa mais do que parece, porque um único arquivo na raiz esbarra em um teto em uma base de código grande. É a reclamação mais comum que vejo de quem usa essas ferramentas em escala:

"AGENTS dot md files don't scale beyond modest codebases. Lots of discussions on this lately. If you're building serious software with Claude Code or any agentic tool, a single AGENTS dot md will eventually fail you."

elvis (@omarsar0), X

A solução não é um arquivo maior, e sim mais arquivos: um arquivo curto na raiz mais um aninhado em cada pacote, para que o agente sempre leia instruções voltadas ao que está tocando.

Importações e o limite de 4 níveis

O CLAUDE.md pode trazer outros arquivos com a sintaxe @path/to/import. Caminhos relativos e absolutos funcionam, arquivos importados podem importar outros até uma profundidade máxima de quatro níveis, e envolver um caminho em crases impede a importação (útil quando você só quer mencionar um arquivo). Uma pegadinha para quem tenta reduzir o contexto: dividir em importações não reduz o uso de tokens, porque os arquivos importados ainda são carregados na inicialização. Ajuda na organização, não no tamanho.

O que colocar em um bom AGENTS.md (ou CLAUDE.md)

Não há seções obrigatórias, mas as mais populares são visão geral do projeto, comandos de build e teste, estilo de código, instruções de teste, notas de segurança e regras de PR ou commit. O exemplo canônico da especificação é assim:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package.
- Run `pnpm install --filter <project_name>` to add a package to your workspace.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check.
- Fix any test or type errors until the whole suite is green.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

O detalhe que faz disso mais do que documentação: os comandos de teste que você lista são executados automaticamente. O agente tenta rodar as verificações relevantes e corrigir as falhas antes de terminar. Então uma linha precisa com pnpm test não é uma anotação, é uma instrução sobre a qual o agente age.

Quanto à escrita em si, o guia da Anthropic para o CLAUDE.md vale igualmente para o AGENTS.md, porque ambos são carregados na janela de contexto e tratados como contexto, não como configuração imposta:

• Seja curto. Mire em menos de 200 linhas; arquivos maiores consomem contexto e, segundo a documentação, na verdade reduzem o quanto o agente os segue.
• Seja específico. Segundo o guia de escrita, "Use 2-space indentation" vence "Format code properly"; "Run npm test before committing" vence "Test your changes." Escreva regras concretas o bastante para serem verificáveis.
• Estruture. Títulos e marcadores em Markdown para agrupar instruções relacionadas.
• Mantenha a consistência. Se duas regras se contradizem, o Claude pode escolher uma arbitrariamente, então revise os arquivos aninhados periodicamente.

Bem feito, isso rende mais do que a maioria espera. Como um desenvolvedor disse em uma discussão do Ask HN sobre a manutenção desses arquivos:

"AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes."

bisonbear, Hacker News

O caminho mais rápido para um primeiro rascunho é o /init, que analisa a sua base de código em busca de comandos de build, testes e convenções e escreve um arquivo inicial (ele também pode migrar um arquivo do Cursor ou do Copilot). Depois edite com /memory e confirme o que realmente foi carregado com /context. E, como um CLAUDE.md é entregue como uma mensagem de usuário depois do prompt do sistema, não há garantia de cumprimento estrito; se você precisa que uma regra seja aplicada de qualquer jeito, a documentação indica um hook PreToolUse em vez do arquivo de instruções.

Como compartilhar um arquivo com todos os agentes

Se você usa o Claude Code junto com Codex, Cursor ou Gemini, o objetivo é uma única fonte da verdade. Com o suporte nativo, isso agora é o padrão: coloque tudo no AGENTS.md e não adicione um CLAUDE.md.

Se você está em uma versão mais antiga, ou em uma configuração em que a leitura nativa não está disponível (Amazon Bedrock, outros provedores de terceiros ou telemetria desativada), a alternativa é importá-lo a partir de um CLAUDE.md:

# CLAUDE.md
@AGENTS.md

Há também o clássico link simbólico, embora a documentação agora o trate como último recurso:

ln -s AGENTS.md CLAUDE.md

O caminho do link simbólico tem ressalvas reais: as ferramentas Edit e Write do Claude se recusam a gravar através do link (elas redirecionam as edições para o AGENTS.md de destino), e no Windows um link simbólico commitado é baixado como texto simples, a menos que core.symlinks esteja ativado. Por isso a importação é a opção mais limpa hoje. O comando oficial de uma linha para migração ao consolidar um arquivo antigo é:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Erros comuns a evitar

Algumas armadilhas que vejo com frequência, a maioria vinda diretamente das regras de precedência:

• Um CLAUDE.md esquecido sobrepondo em silêncio o seu AGENTS.md. Se os dois existem, o Claude lê o CLAUDE.md. Apague o desatualizado ou importe o outro.
• Tratar importações como dieta. Dividir um arquivo enorme em importações com @ não reduz o contexto; tudo ainda é carregado. Corte conteúdo em vez disso.
• Regras vagas. "Write clean code" não faz nada. Dê o comando exato, a indentação exata, o formato exato do título do PR.
• Um arquivo de 600 linhas. Acima de ~200 linhas, a aderência cai. Mova procedimentos de vários passos para skills ou subagentes, e regras de partes da base de código para arquivos .claude/rules/ com escopo por caminho.
• Presumir que é imposto. Arquivos de instruções são contexto, não uma barreira rígida. Para um bloqueio real, use um hook.

Para o ambiente ao redor dos seus arquivos de instruções, vale dar uma olhada no guia do settings.json e nas permissões, já que ambos interferem em como as regras realmente são aplicadas.

Experimente a eesel: a mesma ideia, para os agentes que cuidam do seu suporte

Aqui está o elo. AGENTS.md e CLAUDE.md são a forma de entregar a um agente de programação as suas instruções permanentes em um arquivo. Esse agente de programação é uma infraestrutura que você configura. A eesel é a outra metade do quadro: em vez de uma ferramenta que você instrui, é um colega de equipe de IA pronto para trabalhar que você contrata para uma função definida, hoje um agente de helpdesk com IA que cuida da sua fila de suporte e um redator de blog com IA.

E ela segue a mesma filosofia de "as instruções ficam em um só lugar". As regras permanentes de um agente da eesel não ficam espalhadas por telas de configuração; são um único conjunto editável de instruções, mais o seu conhecimento real (tickets anteriores, central de ajuda, documentação). É o modelo mental do AGENTS.md aplicado a um colega de suporte.

Se você já vive no terminal, isso vai soar familiar. A eesel oferece uma CLI (@eesel/cli) de verdade, e a documentação é direta quanto à intenção: tudo o que você faz no painel pode ser feito pelo terminal, inclusive deixar um agente de programação com IA cuidar da configuração. Você pode executá-la sem instalar (npx @eesel/cli init), conversar com o agente (eesel chat), editar suas regras permanentes (eesel instructions) e ver o que ele fez (eesel activity). Todo comando imprime JSON e aceita --dry-run, justamente o que o torna controlável por um script ou por um agente, em vez de uma pessoa clicando.

Melhor ainda, todo workspace da eesel também é um servidor MCP. Execute eesel mcp token e ele imprime uma linha pronta para colar de claude mcp add, para que o Claude Code (ou o Cursor, ou o Codex) possa gerenciar as instruções do seu agente de suporte, verificar sua atividade e aprovar ações retidas sem sair do editor. O mesmo agente, três superfícies: terminal, scripts e agentes de programação via MCP.

O preço é uma mensalidade fixa a partir de $299/mês por 500 créditos (1 crédito por ticket ou chat), as perguntas no painel são em sua maioria gratuitas, e há um plano gratuito com 100 créditos e sem cartão. Se você já escreve arquivos AGENTS.md, vai se sentir em casa. Experimente a eesel ou aponte o Claude Code para ela e deixe que ele faça a ligação.