AGENTS.md vs CLAUDE.md vs SKILL.md: qual arquivo para qual agente? O que a pesquisa diz (2026)
Arquivos como AGENTS.md / CLAUDE.md realmente ajudam os agentes de programação? Um estudo de 2026 responde: sim, mas por pouco — e escrevê-los longos sai pela culatra. Em muitos agentes e modelos, os arquivos de contexto não melhoraram de forma confiável o sucesso das tarefas, enquanto o custo de inferência subiu mais de 20%. A solução não é abandonar o arquivo — é escrevê-lo enxuto (comandos de teste/build, regras que não se pode quebrar, caminhos principais) e empurrar o resto para arquivos carregados sob demanda, no estilo divulgação progressiva.
- Os números da pesquisa e o status das ferramentas (AGENTS.md como padrão multiferramenta, sintaxe de import) foram conferidos com as fontes na época em que escrevi; essas ferramentas mudam rápido, então confirme na documentação atual.
AGENTS.md e CLAUDE.md — são a mesma coisa?
No fundo são a mesma ideia — um arquivo que o agente lê para aprender as convenções do projeto — só com um nome diferente por ferramenta. O CLAUDE.md é a convenção do Claude Code. O AGENTS.md é o padrão multiferramenta em ascensão: lido pelo Codex CLI, Copilot CLI, Gemini CLI, Cursor e também pelo Claude Code.
Os dois fazem o mesmo trabalho: dar ao agente um briefing persistente que sobrevive entre as sessões de chat, para ele não perguntar suas convenções de novo toda vez. A única diferença que vale lembrar: o CLAUDE.md mantém alguns recursos específicos do Claude Code que o AGENTS.md não padroniza — em especial o carregamento hierárquico e os imports. Para aprender a escrever um CLAUDE.md do começo ao fim com um modelo pronto, veja o guia do CLAUDE.md.
Uma linha para não confundir três parecidos: o AGENTS.md (o padrão de arquivo) é diferente do AgentKit (o kit para Claude Code, agentkit.best) e do OpenAI AgentKit (Agent Builder/ChatKit).
AGENTS.md vs CLAUDE.md vs SKILL.md: qual arquivo faz qual trabalho?
AGENTS.md e CLAUDE.md já não são o único arquivo de projeto que um agente lê. O SKILL.md é um tipo de arquivo totalmente diferente: uma pasta que contém um arquivo SKILL.md (frontmatter YAML com name/description, mais um corpo em Markdown, opcionalmente ao lado de scripts/, references/ ou assets/) que empacota uma capacidade reutilizável, sob demanda — não um contexto sempre carregado. O agente compara a tarefa com a description da skill e a carrega só quando é relevante (ou você a invoca explicitamente). A Anthropic criou o formato para o Claude Code (out/2025) e o publicou como o padrão aberto Agent Skills (agentskills.io); o Codex adotou em poucas semanas — a própria documentação da OpenAI confirma que no Codex "skills build on the open agent skills standard" (learn.chatgpt.com/docs/build-skills).
A diferença em relação ao AGENTS.md/CLAUDE.md é de tipo, não só de nome. AGENTS.md e CLAUDE.md são contexto persistente, sempre carregado — exatamente o que a pesquisa abaixo mede, e exatamente por que inchá-los custa mais de 20% de inferência. O SKILL.md é carregado sob demanda, só quando a tarefa combina — o modelo de divulgação progressiva que a seção mais adiante toma emprestado como técnica de escrita. Agora você sabe por que essa técnica funciona: é literalmente como as skills evitam gastar contexto com capacidades que você não está usando agora.
Os três arquivos também diferem em quem os lê, que formato usam e para que servem:
| AGENTS.md | CLAUDE.md | SKILL.md | |
|---|---|---|---|
| Sempre carregado? | Sim | Sim | Não — sob demanda |
| Quem lê | Codex, Copilot CLI, Gemini CLI, Cursor, Claude Code | Só o Claude Code | Só Claude Code + Codex |
| Formato | Markdown puro | Markdown + imports @path | Frontmatter YAML + Markdown, scripts/refs opcionais |
| Melhor para | Convenções de projeto multiferramenta | Configuração específica do Claude Code | Um fluxo de trabalho ou capacidade reutilizável |
Um fato que vale dizer com todas as letras: o Codex lê o AGENTS.md — ele não lê o CLAUDE.md de jeito nenhum. Se o Codex está na sua caixa de ferramentas, o AGENTS.md é o arquivo que ele de fato enxerga; veja a mecânica de configuração do AGENTS.md no Codex para a ordem de carregamento completa. Para como o Codex carrega skills especificamente, veja como funcionam as Codex Skills.
Escolha rápida: precisa que o agente saiba sempre seus comandos de teste/build e as regras que não pode quebrar? Use AGENTS.md (ou CLAUDE.md no Claude Code). Precisa de uma capacidade reutilizável que você aciona só de vez em quando — um fluxo, um pacote de scripts? Então use SKILL.md.
O que a pesquisa encontrou — ajuda, mas por pouco
A pergunta "os arquivos de contexto ajudam mesmo" agora tem dados. O estudo "Evaluating AGENTS.md", de Gloaguen et al. (submetido em fev/2026) mediu arquivos de contexto em muitos agentes, modelos e repositórios. Os resultados merecem uma pausa:
- Nenhuma melhora geral no sucesso das tarefas — vale para ambos, arquivos gerados por LLM e arquivos commitados por desenvolvedores. Isso contraria a recomendação comum.
- O custo de inferência subiu mais de 20% em média.
- Visões gerais do repositório — populares e recomendadas pelos provedores de modelos — não ajudaram. Em contraste, as instruções dentro de um arquivo de contexto foram devidamente seguidas pelos agentes.
Uma coisa que costuma ser exagerada: não é que "arquivos escritos por devs são melhores". O estudo achou que nenhum dos tipos melhora o sucesso de forma confiável. Mas como as instruções são seguidas enquanto as visões gerais não, a conclusão prática é afiada: corte o enchimento de visão geral, mantenha as instruções acionáveis. Arquivo menor, mesmo sucesso, custo menor.
O paradoxo — o agente obedece com entusiasmo demais
O interessante é que o agente não ignora as instruções — ele as segue um pouco entusiasmado demais. Cite testes, e ele roda mais testes. Cite ferramentas, e ele usa mais ferramentas. Cite fluxos específicos do repositório, e ele explora mais.
O problema é que muitas dessas instruções não ajudam a resolver a tarefa mais rápido — só a deixam mais pesada. Cada linha que você acrescenta é mais uma linha que o agente sente que "precisa" cumprir. É por isso que um arquivo inchado queima tokens e arrasta a tarefa sem um resultado melhor.
Então o AGENTS.md não está errado — errado é o jeito de escrever
A lição não é "largue o arquivo de contexto". É: não transforme o AGENTS.md num manual de 2.000 palavras para o agente reler toda vez que corrige um bug.
Mantenha as partes acionáveis:
- O comando de teste, o comando de build, o comando de execução.
- As regras que ele não pode quebrar (não mudar a API pública, não mexer no diretório X…).
- Os caminhos / diretórios importantes.
Depois deixe o agente descobrir o resto. Sem rodeios: se amarrarmos os agentes rápido demais ao nosso próprio conhecimento, eles vão acabar… burros feito a gente. Dê a eles espaço para voar e depois traga-os de volta para os requisitos de verdade.
Escreva no estilo "divulgação progressiva" (como o SKILL.md)
Como vimos acima, o SKILL.md carrega sob demanda — aplique a mesma ideia ao AGENTS.md: divida em arquivos pequenos e faça carregamento preguiçoso: "se estiver fazendo A, leia o arquivo X." Quando não é preciso, o agente pula e não gasta contexto com isso.
No CLAUDE.md você faz isso com a sintaxe de import @path/to/file (confirme a sintaxe atual, já que as ferramentas mudam rápido): o arquivo raiz guarda só o núcleo sempre verdadeiro, enquanto os detalhes de cada tipo de trabalho ficam em arquivos separados, puxados quando relevantes. É o mesmo mecanismo que as skills do Claude Code usam para carregar instruções por contexto; para criar uma, veja como criar uma skill personalizada. Para o orçamento geral de contexto, veja como gerenciar contexto e memória.
Um arquivo ou dois? (o truque do symlink)
Se você mantém só um arquivo, faça dele o AGENTS.md, já que é lido pela maioria das ferramentas. Se o Claude Code é seu agente principal mas você ainda quer que toda ferramenta funcione, um truque popular é ter uma única fonte da verdade: escreva o AGENTS.md e crie um symlink do CLAUDE.md para ele.
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.mdAssim o conteúdo fica num só lugar e ainda serve todas as ferramentas. O custo: você perde o carregamento hierárquico e os imports do CLAUDE.md — então, se você depende muito de imports @path, pense em manter o CLAUDE.md como arquivo de verdade em vez de symlink.
Antes/depois: de um manual longo para ~uma dúzia de linhas
Quem usou um kit de Claude Code desde o começo até agora vai notar: de um CLAUDE.md longo, eu comprimi para pouco mais de uma dúzia de linhas. Porque esse arquivo deve ser específico do projeto — guardando exatamente as regras extras que este projeto precisa — e não um faz-tudo genérico que acumula de um pouco de tudo.
A regra da poda: cada linha precisa responder "onde isso muda a decisão do agente?". Se não muda, é enchimento de visão geral — corte, ou empurre para um arquivo de carregamento preguiçoso. Um modelo enxuto de CLAUDE.md para copiar está no guia do CLAUDE.md.
Checklist manter / cortar
| ✅ Manter | ❌ Cortar (ou carregar sob demanda) |
|---|---|
| Comandos de teste / build / execução | Visão geral do repositório |
| Regras que não se pode quebrar | Textos longos de explicação |
| Caminhos / diretórios importantes | Fluxos raramente usados |
Import @path para o detalhe quando precisar | Conhecimento geral que o agente já tem |
Um kit com contexto enxuto de fábrica (AgentKit)
Se você prefere não ajustar tudo na mão, kits como o AgentKit (agentkit.best, CLI ak — diferente do OpenAI AgentKit) já vêm com uma convenção enxuta de CLAUDE.md mais um conjunto de skills escritas no estilo divulgação progressiva, então você pula a parte de montar um manual inchado. Para uma visão geral, leia a resenha do AgentKit ou veja o AgentKit (20% de desconto pelo link).
Perguntas frequentes (FAQ)
AGENTS.md e CLAUDE.md são a mesma coisa?
Mesma ideia, nome diferente por ferramenta. O CLAUDE.md é a convenção do Claude Code; o AGENTS.md é o padrão multiferramenta lido por muitas ferramentas (Codex, Copilot CLI, Gemini CLI, Cursor e Claude Code). O CLAUDE.md ainda guarda alguns extras, como carregamento hierárquico e imports.
O Claude Code lê o AGENTS.md?
Do jeito que está, o Claude Code consegue ler o AGENTS.md junto com o CLAUDE.md — mas essa área muda rápido, então confirme na documentação atual. Se você depende de imports @path e de carregamento hierárquico, o CLAUDE.md ainda é o arquivo raiz que vale a pena manter.
Os arquivos de contexto ajudam mesmo os agentes?
Segundo um estudo de 2026, eles não melhoram de forma confiável o sucesso das tarefas (tanto os gerados por LLM quanto os escritos por devs) e elevam o custo em mais de 20%. As visões gerais do repositório em especial não ajudaram, enquanto instruções concretas foram seguidas. Lição: mantenha instruções acionáveis, corte as visões gerais.
Quão longo deve ser o CLAUDE.md?
O mais enxuto possível — guarde só o núcleo sempre verdadeiro e empurre os detalhes para arquivos de carregamento preguiçoso via imports @path. Cada linha deve mudar a decisão do agente; se não muda, corte.
O que é "divulgação progressiva" no CLAUDE.md?
É dividir o conteúdo em arquivos pequenos carregados sob demanda: "se estiver fazendo A, leia o arquivo X." Quando não é relevante, o agente pula e não gasta contexto com isso — do mesmo jeito que as skills carregam instruções quando o contexto combina.
O que manter e o que cortar no AGENTS.md?
Manter: comandos de teste/build/execução, regras que não se pode quebrar, caminhos importantes e imports para o detalhe quando precisar. Cortar: visões gerais do repositório, textos longos, fluxos raramente usados e conhecimento geral que o agente já tem.
Como o SKILL.md é diferente do AGENTS.md?
O SKILL.md é uma capacidade reutilizável carregada sob demanda, só quando uma tarefa combina com ela; o AGENTS.md, por outro lado, é contexto persistente sempre carregado. Para o passo a passo completo de criar e instalar skills, veja como funcionam as Codex Skills.
Conclusão
Arquivos de contexto funcionam — quando são enxutos e escritos no estilo divulgação progressiva. Escrevê-los longos é sabotar a si mesmo: mais de 20% de custo sem resultado melhor. Corte as visões gerais, mantenha as instruções acionáveis, carregue o resto sob demanda. Veja o guia do CLAUDE.md para um modelo e, se você também roda de forma autônoma, combine com como usar o modo /goal com eficiência.