Documentação amigável para agentes: o que os agentes de IA realmente leem (e o que ignoram)

Estudo empírico com 557 sessões reais de agentes de código mostra que arquivos como AGENTS.md e notas de trabalho dominam 60,5% das interações com documentação — enquanto referências de API ficam com apenas 1,3%. Entenda os números e aprenda a escrever documentação que agentes usam de verdade.

Por que documentação para humanos não basta

A documentação técnica sempre foi escrita para desenvolvedores humanos. Manuais, guias de referência e tutoriais pressupõem um leitor que forma intenções, se confunde e faz perguntas. Mas esse leitor não é mais o único: uma parcela crescente das mudanças de código em projetos open source hoje é escrita por agentes autônomos — programas que leem repositórios, executam comandos e abrem pull requests sem um humano supervisionando cada passo.

Se os agentes viraram uma classe importante de leitores de documentação, o design dessa documentação deveria ser informado pelo que eles realmente fazem. O problema: até agora, isso nunca tinha sido medido. As recomendações de "documentação amigável para agentes" (escreva títulos claros, dê exemplos executáveis, publique um llms.txt) vinham da intuição sobre como os agentes deveriam se comportar — não de observação.

Isso mudou em 2026, com o primeiro estudo empírico de larga escala sobre o assunto (arXiv:2608.20195). Os resultados surpreendem — e derrubam várias crenças.

O que os agentes realmente leem

O estudo analisou 557 sessões agentic reais (94.813 eventos de desenvolvimento, incluindo 3.033 interações com documentação) e 33.097 pull requests agentic (690.260 registros de mudanças em arquivos). O achado central é a distribuição dos tipos de documento que os agentes consultam:

  • Arquivos de instrução para agentes (AGENTS.md, CLAUDE.md, SKILL.md, regras de Cursor e Copilot): 35,4%
  • Notas de trabalho dos próprios agentes (planos, diretórios thoughts/, logs de verificação): 25,1%
  • Documentação técnica clássica (arquitetura, instalação, exemplos, changelogs, etc.): 10,6%
  • Referências de API: apenas 1,3%
  • Guias de troubleshooting: 0,4%

Ou seja: 60,5% das interações com documentação envolvem artefatos que existem por causa dos agentes — não as documentações clássicas. Um arquivo de instruções recebe cerca de 27 vezes mais interações que uma referência de API. Os arquivos que a indústria mais aprimora (API references, guias de troubleshooting) são justamente os que os agentes menos consultam.

Ler documentação não é o que você imagina

O modelo mental tradicional é linear: o desenvolvedor descobre a documentação, lê, interpreta, aplica no código e valida o resultado. Os dados contam outra história:

  • Consultar docs raramente leva direto a editar código. A probabilidade de editar código imediatamente após ler uma documentação é 0,002 (3 ocorrências em 1.328 leituras). Leitura é seguida muito mais por raciocínio (0,245) ou por mais leituras (0,270).
  • Nenhuma validação explícita baseada em documentação foi observada. Em nenhum momento um agente usou um documento como "oráculo" para conferir o código — e ler documentação se associa a menos testes imediatos (lift de 0,23) e builds (0,15).
  • A consulta é proativa, não reativa. 70,2% das interações são auto-iniciadas; apenas 7,5% são motivadas por falhas. Agentes não leem documentação só quando quebram — leem durante o progresso normal da tarefa.
  • Agentes escrevem documentação quase tanto quanto leem. A produção de docs ocorre a 0,87x a taxa de consulta, e 41,5% dos PRs agentic alteram documentação. Mas o código vem primeiro: quando código e docs mudam juntos, o código é tocado antes em 82,5% dos casos.

O modelo descritivo que emerge não é uma jornada linear, e sim um ciclo de dois lobos: um lobo de consulta (orientar → descobrir → recuperar → interpretar), altamente recorrente, e um lobo de produção (escrever/editar documentação), o maior de todos. O elo entre eles — e com o código — é fraco e ambíguo.

AGENTS.md e CLAUDE.md: o novo centro de gravidade

Se os agentes leem principalmente arquivos de instrução, vale entender o que eles são. O AGENTS.md é um formato aberto, um "README para agentes": um arquivo Markdown na raiz do repositório com contexto e instruções que o agente não consegue inferir do código sozinho — comandos de build e teste, convenções de estilo, considerações de segurança. É adotado por mais de 60 mil projetos open source, apoiado por OpenAI, Google (Jules/Gemini CLI), Cursor e outros, e agora é mantido pela Agentic AI Foundation, da Linux Foundation. O CLAUDE.md, da Anthropic, cumpre papel similar para o Claude Code, com um sistema hierárquico de memória (políticas de organização, memória de projeto e regras por caminho).

Mas atenção: a existência de um arquivo não garante que ele ajude. O estudo da ETH Zurich (AGENTbench — 138 instâncias de 12 repositórios Python, 5.694 pull requests reais) mediu o efeito desses arquivos e encontrou o oposto do hype:

  • Arquivos AGENTS.md gerados por LLM reduziram o desempenho dos agentes em 2–3% — e costumam apenas duplicar documentação que já existe no repositório (removê-los melhorou o desempenho em 2,7%).
  • Arquivos escritos por humanos melhoraram apenas ~4% em média.
  • Ambos aumentaram custos de inferência em mais de 20% (agentes gastam 14–22% mais tokens de raciocínio processando o contexto).

Os agentes obedecem as instruções — usaram ferramentas citadas no AGENTS.md 2,5x mais — mas instruções genéricas e prolixas roubam capacidade de raciocínio da tarefa real. A conclusão dos pesquisadores: arquivos gerados por LLM deveriam, em geral, ser omitidos; arquivos humanos deveriam conter apenas o mínimo essencial que não pode ser descoberto no código.

llms.txt: documentação para a web agentic

O mesmo princípio vale para sites. O padrão llms.txt, proposto por Jeremy Howard em 2024, é um arquivo Markdown na raiz do site (/llms.txt) que dá aos LLMs um mapa curado e econômico em tokens do conteúdo: um resumo curto e links para versões Markdown das páginas. Em vez de navegar por HTML cheio de anúncios e JavaScript, o agente lê o índice e busca só o detalhe que precisa. OpenAI, Anthropic e Gemini já publicam llms.txt para suas documentações, e o Lighthouse do Chrome passou a auditar sites por ele. Enquanto o sitemap.xml lista tudo para buscadores, o llms.txt é um guia selecionado para o consumo por agentes — na prática, "preparar o site para a web agentic".

Dicas práticas: documentação que agentes usam de verdade

Juntando os dois estudos, um guia objetivo para quem mantém repositórios e docs:

  1. Priorize os arquivos de instrução. Eles são a superfície de documentação mais usada pelos agentes (27x mais que API references). Corrija e mantenha AGENTS.md/CLAUDE.md antes de polir manuais clássicos.
  2. Escreva o que não é descoberto no código. Comandos de build/teste, armadilhas de ambiente, convenções não óbvias. Se o agente descobre pelo próprio código, não precisa estar no arquivo.
  3. Seja curto e positivo. Instruções específicas e afirmativas vencem paredes de prosa; alvo de ~30 linhas. Não gere seu AGENTS.md com LLM sem revisão crítica — o estudo mostra que isso costuma piorar o resultado.
  4. Prefira enforcement automatizado a prosa. Regra de estilo? Linter. Tipos? TypeScript estrito. Testes? Gate de CI. O melhor AGENTS.md é o que você não precisa: código limpo, nomes claros e testes bons dão ao agente quase tudo.
  5. Ofereça documentação local e autocontida. Agentes leem em sequência (0,270 de transição leitura→leitura) e quase nunca seguem links cruzados — prefira cada documento completo em si, com exemplos executáveis.
  6. Trate notas de agentes como superfície de manutenção. Planos e thoughts/ acumulam no repositório; inclua-os na higiene do repo e nos critérios de review.
  7. Publique um llms.txt se você mantém um site/docs público — e mantenha versões .md das páginas para leitura eficiente por agentes.

A mensagem central dos dados é simples: documentação para agentes não é um projeto de escrita, é um projeto de engenharia. Os agentes leem — muito. A questão é garantir que o que leem seja curto, executável e impossível de descobrir de outro jeito.

Referências