Se um agente de IA vai trabalhar no seu repositório — revisar código, gerar PRs, executar testes, navegar a codebase — ele precisa de documentação. Não a documentação que você escreveu para humanos. Uma documentação diferente, escrita para o agente entender o que pode fazer, como o repositório funciona e onde estão os limites.
GitHub analisou 2.500+ repositórios e identificou os padrões de documentação que fazem agentes de IA mais eficientes e menos propensos a errar. O resultado é um conjunto de práticas que está se tornando padrão da indústria — e que a maioria dos repositórios ainda não segue.
O que é AGENTS.md e por que surgiu
AGENTS.md é um arquivo de configuração para agentes de IA em repositórios. Assim como README.md orienta desenvolvedores humanos, AGENTS.md orienta agentes: o que o projeto faz, como a codebase está organizada, quais comandos rodar, quais partes são críticas, o que nunca mudar sem revisão humana.
A iniciativa veio de um esforço conjunto entre OpenAI, Google, Cursor, Factory e a comunidade de desenvolvedores em agosto de 2025. Não é um padrão oficial da GitHub — é uma convenção emergindo de uso real em projetos que dependem de agentes para fluxos de desenvolvimento.
O problema que AGENTS.md resolve: agentes sem contexto de repositório cometem erros específicos e previsíveis. Modificam arquivos de configuração que não deveriam tocar. Rodam comandos na ordem errada. Ignoram convenções de nomenclatura que o time segue há dois anos. Cada erro desses é um ciclo extra de revisão humana — tempo que o agente deveria ter economizado.
O que a análise de 2.500+ repositórios revelou
A análise do GitHub de repositórios com alta atividade de agentes de IA identificou quatro categorias de documentação que consistentemente melhoram a performance dos agentes:
- Documentação de arquitetura: Não um diagrama bonito para apresentação — uma descrição textual do que cada pasta faz, quais módulos são críticos, quais são opcionais. Agentes que têm esse mapa navegam 40% menos arquivos antes de encontrar o que precisam.
- Documentação de comandos: Quais comandos rodar para build, test, lint e deploy. Em que ordem. O que cada um faz e o que pode dar errado. Agentes sem isso tentam inferir e frequentemente inferem errado.
- Documentação de restrições: O que nunca mudar sem revisão humana. Quais arquivos são críticos de infraestrutura. Quais convenções são não-negociáveis. O equivalente dos permission gates do harness — definido em documentação.
- Documentação de contexto de negócio: Por que o projeto existe. Qual problema resolve. Quem são os usuários. Isso parece redundante mas não é — agentes que entendem o propósito do projeto fazem escolhas de implementação melhores do que agentes que só entendem o código.
Os erros mais comuns em repositórios sem documentação para agentes
O padrão de falha é consistente entre projetos analisados pelo GitHub. Sem documentação adequada, agentes cometem os mesmos erros:
Modificação de arquivos de configuração: Sem saber quais arquivos são de infraestrutura crítica, agentes modificam .env, arquivos de configuração de CI/CD e secrets com a mesma leveza com que modificam arquivos de lógica de negócio. O dano pode ser silencioso e só aparecer em produção.
Ordem errada de operações: Sem documentação de dependências entre comandos, agentes rodam testes antes de rodar migrations, fazem deploy antes de completar build, ou executam limpeza de dados antes de criar backup. Operações que humanos sabem de cor porque já quebraram o ambiente uma vez.
Violação de convenções: Nomenclatura de variáveis, estrutura de commits, padrões de comentários — convenções que vivem na cabeça do time mas nunca foram escritas. Agentes geram código tecnicamente correto mas que viola o padrão do repositório, criando inconsistência que o time precisa corrigir manualmente.
Como estruturar seu AGENTS.md
Com base nos padrões identificados na análise do GitHub, um AGENTS.md eficiente tem cinco seções:
- Project Overview (2-3 frases): O que o projeto faz, em linguagem simples. Qual o problema que resolve. Não para marketing — para contexto de decisão.
- Repository Structure: Mapeamento das pastas principais com descrição do que cada uma contém. Destacar quais são críticas (nunca modificar sem revisão) e quais são seguras para agentes trabalharem.
- Commands Reference: Comandos essenciais com descrição do que fazem. Build, test, lint, migrate, deploy. Dependências entre comandos. O que cada um espera como pré-condição.
- Constraints and Off-Limits: Lista explícita do que agentes não devem modificar. Arquivos de configuração de infraestrutura, secrets, arquivos de migração já executados, qualquer coisa que não deveria mudar sem revisão humana.
- Conventions: Padrões de código do projeto. Nomenclatura, estrutura de commits, como escrever testes, o que comentar e o que não comentar. O que é considerado "código bom" neste repositório.
A conexão com harness engineering
AGENTS.md não é apenas documentação — é o constraint harness do repositório. É o arquivo que define o espaço de ação do agente antes da geração começar. Um repositório com AGENTS.md bem feito tem um harness de restrição implícito: o agente sabe o que pode fazer, como fazer e o que não tocar.
A análise do GitHub mostra que repositórios com AGENTS.md têm menos ciclos de revisão por PR gerado por agente. O agente comete menos erros porque tem contexto suficiente para tomar decisões melhores. Não é o modelo ficando mais inteligente — é a documentação reduzindo o espaço de erro.
Documentação para agentes vs. documentação para humanos
A distinção que muda como você documenta: humanos leem documentação sequencialmente, com paciência para contexto longo. Agentes processam documentação como contexto de sistema — denso, estruturado, com informações críticas nas primeiras posições.
Isso inverte algumas práticas comuns de documentação: bullet points funcionam melhor do que parágrafos; exemplos concretos funcionam melhor do que princípios abstratos; restrições explícitas ("não modifique X") funcionam melhor do que restrições implícitas ("X é crítico"). Escrever para agente é escrever para um leitor que tem 100% de atenção mas zero de intuição sobre o que é óbvio.
Leia também
- Harness agêntico: por que o agente não é a parte difícil do seu sistema de IA
- Como integrar o NotebookLM com o Claude Code (e reduzir até 30% o consumo de tokens)
- 30 agentes de IA que todo AI engineer deveria ter (organizados por categoria)
Perguntas frequentes
O que é AGENTS.md e como ele difere do README.md?
AGENTS.md é documentação escrita para agentes de IA, não para humanos. Enquanto README.md explica como usar o projeto e instalar dependências, AGENTS.md define como um agente deve navegar e modificar o repositório: estrutura de pastas, comandos essenciais, arquivos que nunca devem ser modificados, convenções de código e contexto de negócio. É o constraint harness do repositório em formato documentação.
Como o AGENTS.md melhora a performance de agentes no repositório?
Documentação adequada reduz o espaço de erro do agente. Com contexto sobre o que pode fazer (estrutura, comandos) e o que não pode fazer (arquivos críticos, restrições), o agente comete menos erros de configuração, violações de convenção e operações na ordem errada. A análise do GitHub de 2.500+ repositórios mostrou redução consistente de ciclos de revisão em projetos com boa documentação para agentes.
Preciso de AGENTS.md se já tenho README.md completo?
README.md e AGENTS.md servem propósitos diferentes. README.md é escrito para humanos — sequencial, com contexto de negócio e instruções de instalação. AGENTS.md é escrito para agentes — estruturado, com bullet points concisos, restrições explícitas e convenções documentadas. Um README completo não substitui um AGENTS.md porque a densidade e o formato da informação são otimizados para diferentes leitores.
Qual é o tamanho ideal de um AGENTS.md?
Curto e denso é melhor do que longo e completo. Um AGENTS.md de 200-400 palavras com as cinco seções essenciais (project overview, estrutura, comandos, restrições, convenções) é mais eficiente do que 2.000 palavras de documentação completa. Agentes processam o arquivo como contexto de sistema — quanto mais denso, mais informação útil por token consumido.
