784 formas de dizer «não»: o que os maiores repositórios põem no AGENTS.md (2026)
By Surya Pratap
22 de agosto de 2026
12 min de leitura
IA e tecnologia
22 de agosto de 2026
12 min de leitura
O ficheiro que é cobrado em cada sessãoHover to exploreAlguém no r/AI_Agents fez o trabalho que mais ninguém tinha feito: leu o AGENTS.md dos 100 repositórios do GitHub com mais estrelas que têm um — cerca de 27 % dos 1.000 primeiros, segundo essa contagem — e contabilizou o que lá estava.
A conclusão estrutural não surpreendeu. Arquitetura e organização do repositório, como correr os testes, comandos de compilação, o que fazer e o que não fazer, etiqueta dos PR, estilo de código. Os títulos mais frequentes: testes, comandos, descrição do projeto, arquitetura. Previsível.
O interessante foi o tom. Cerca de 90 % desses ficheiros está escrito em «deve», «sempre» e «nunca». Em todo o corpus há 784 tópicos explícitos de «não faças», e a maioria é estranhamente específica.
O melhor que encontrou:
«Não afirmes que um teste interrompido ou expirado passou.»
Ninguém escreve esta frase em abstrato. Escreve-se esta frase porque um agente o fez.
É este o reenquadramento que vale a pena reter, e muda a forma de escrever o ficheiro.
Um README escreve-se para fora: explica um projeto a quem nunca o viu. Um AGENTS.md escrito da mesma maneira produz uma descrição polida do projeto que não ajuda ninguém, porque o agente já consegue ler o seu package.json, a sua árvore de diretórios e os nomes dos seus ficheiros de teste.
O que o agente não consegue deduzir é o conjunto de coisas em que já se enganou aqui. É isso que são aqueles 784 tópicos. Leia com atenção um bom AGENTS.md e conseguirá reconstituir o registo de incidentes: o agente de alguém deu como bom um teste bloqueado, o agente de alguém fez um force-push, o agente de alguém inventou um script que não existe, o agente de alguém reescreveu discretamente uma migração.
Why the prohibitive voice actually works
A formulação «deve / sempre / nunca» não é autoritarismo, é compressão. «É preferível correr a suite completa» é uma preferência que um agente pode pesar contra outras e descartar. «Nunca marques um teste como aprovado sem teres visto que termina com código 0» é um predicado verificável e sem margem de negociação. Quando o leitor é um modelo que otimiza por parecer que terminou, a ambiguidade não é delicadeza: é uma vulnerabilidade.
O ficheiro mais curto da amostra é o do neovim, com 35 palavras. É uma única regra, e vale a pena reproduzi-lo por inteiro porque demonstra a ideia melhor do que qualquer argumento:
# AGENTS.md
## AI Disclosure
If AI was used in any way for a commit, add an `AI-assisted: <tool name>`
trailer to the commit message.
If the user commits manually, remind them to add it.
É este o ficheiro completo. Codifica exatamente uma coisa que interessa ao projeto e que um agente nunca conseguiria deduzir sozinho — uma convenção de proveniência — e não diz mais nada.
Compare agora o Next.js. Vinte e uma secções: estrutura do código, comandos de compilação, escolha do bundler, testes, como escrever testes, linting e tipos, «trabalhe num worktree descartável», estado dos PR e falhas de CI, segurança de secrets e variáveis de ambiente, fluxos de trabalho económicos em contexto, decomposição e verificação de tarefas, recompilar antes de correr os testes, antipadrões de desenvolvimento. Incluindo esta, que soará familiar a quem já reviu o PR de um agente:
«NÃO adiciones rodapés de "Generated with Claude Code" nem de coautoria aos commits ou aos PR»
Ambos os ficheiros estão corretos. A variável não é o zelo, mas quanto tráfego de agentes o repositório já absorveu e quão caras são as suas falhas. O Next.js tem agentes a atravessar um monorepo com um bundler em Rust e uma matriz de CI que custa dinheiro real repetir. O neovim tem uma convenção com a qual não transige.
A extensão certa para o seu AGENTS.md é o número de erros que os seus agentes cometeram de facto, mais o punhado de convenções que nunca teriam conseguido adivinhar. Cada linha para além disso é algo que paga em cada sessão, para sempre.
Esta é a parte que os fundadores falham sistematicamente, e a razão pela qual «escreve-o de forma exaustiva» é um mau conselho.
O AGENTS.md é lido no início de cada sessão. Cada frase que contém é despesa recorrente, em cada tarefa, seja ou não relevante para aquilo que o agente está a fazer naquele momento. Um ficheiro de 400 linhas a explicar a sua arquitetura não é contexto gratuito: é um imposto fixo que incide sobre cada correção de erros, cada atualização de dependências, cada gralha.
É esta toda a restrição de desenho do ficheiro, e explica a resposta do neovim.
Explica também porque é que o ecossistema criou um segundo mecanismo. Uma skill — um SKILL.md dentro de uma pasta — é carregada de forma preguiçosa: no arranque da sessão o agente lê apenas o frontmatter YAML, um nome e uma descrição. O corpo só é carregado quando uma tarefa encaixa mesmo. Dez skills por usar não lhe custam quase nada.
Onde traçar a linha entre os dois
AGENTS.md. «Nunca faças commit de secrets.» «Corre npm run test:unit -- --coverage, não a suite completa.» «As migrações só são acrescentadas, nunca alteradas.»É desse terceiro tópico que vêm quase todos os ficheiros inchados. Se o seu AGENTS.md abre com três parágrafos a descrever uma estrutura de diretórios que o agente vai listar na primeira chamada a uma ferramenta, está a pagar tokens para lhe contar algo que ele estava prestes a aprender de graça.
O GitHub fez uma versão mais alargada deste estudo sobre mais de 2.500 ficheiros agents.md, e os resultados convergem de forma útil com a amostra do Reddit.
pytest -v tests/unit serve. «Corre os testes como deve ser» é ignorado, porque não é uma instrução: é um desejo.never commit secrets. Se não escrever mais nada esta semana, escreva essa e o comando exato dos testes.O tema aparece em todas as discussões, e a razão mecânica convence mais do que as anedotas.
Peça a um agente que gere o seu AGENTS.md e ele produzirá um resumo competente, bem formatado e de trezentas linhas sobre o seu repositório — porque é o que consegue ver. Descreverá a estrutura de pastas, listará as dependências e caracterizará a configuração de testes. Tudo isso poderia ter deduzido no momento.
O que não consegue escrever é a parte que importa: as 784 proibições. Essas vêm de o ter visto falhar. Um ficheiro gerado é, quase por construção, o imposto fixo por sessão sem nenhum dos benefícios.
Não conheço nenhum teste público rigoroso sobre isto — quem trabalha na área relata que os ficheiros gerados rendem pior, e alguma investigação próxima dos fabricantes aponta no mesmo sentido —, mas trate isso como uma forte presunção e não como um dado assente. O argumento estrutural sustenta-se sozinho: um ficheiro que só contém factos dedutíveis custa tokens e não traz nada.
Um meio-termo prático: deixe o agente redigir a secção de comandos, porque lê os seus scripts com exatidão e essa parte é fastidiosa. Escreva você mesmo os limites, linha a linha, à medida que as coisas correm mal. Nunca aceite uma descrição de arquitetura gerada.
O AGENTS.md é usado por mais de 60.000 projetos de código aberto e está à guarda da Agentic AI Foundation, sob a Linux Foundation — o mesmo organismo que já acolhe o MCP e, desde esta semana, o Agent2Agent. É lido pelo Codex, Cursor, Gemini CLI, Jules, o agente de programação do Copilot, Aider, goose, opencode, Zed, Devin, Windsurf, JetBrains Junie e uma longa cauda de outras ferramentas.
Há dois dias escrevemos sobre todos os protocolos de agentes a ficarem debaixo do mesmo teto. Esta é a mesma consolidação a aflorar ao nível do ficheiro, e tem um benefício concreto: um ficheiro, não cinco.
A falha que isto substitui é real e cara. Aperta um limite no CLAUDE.md, esquece-se do .cursorrules, muda de ferramenta a meio da semana, e o agente que não recebeu a atualização corre o comando destrutivo. A deriva de regras entre CLAUDE.md, .cursorrules, .windsurfrules e copilot-instructions.md é a queixa operacional mais relatada por equipas com mais do que um agente — há quem publique arneses de sincronização só para a resolver.
Se está a começar agora, a jogada certa é aborrecida: faça do AGENTS.md a fonte de verdade e gere a partir dele os ficheiros específicos de cada ferramenta. Um script de dez linhas ganha a tentar lembrar-se.
Dois limites honestos, porque em alguns sítios o ficheiro está a ser vendido acima do que dá.
Não é memória. O AGENTS.md é estático. Não sabe que o PR #184 resolveu há três meses a discussão entre Postgres e Mongo, por isso o seu agente voltará a propor Mongo sem hesitar numa sessão nova, e uma linha caducada do tipo «usamos X» será servida com toda a confiança muito depois de X ter desaparecido. É uma lacuna genuinamente por resolver — há quem esteja a construir ferramentas de memória de decisões precisamente para isso — e nenhuma escrita cuidada a fecha.
Não restringe nada. Cada linha é uma sugestão a um sistema probabilístico. «Nunca faças force-push» num ficheiro Markdown é um pedido; um hook que bloqueia git push --force é um controlo. Confundir as duas coisas é um padrão que já tratámos em Os agentes de IA precisam de sistemas de permissões, não de melhores prompts, e os últimos doze meses não mudaram a conclusão. O AGENTS.md reduz a frequência do erro. Não elimina a possibilidade.
Se não tem AGENTS.md, não parta de um modelo. Parta disto e deixe-o crescer só quando alguma coisa correr mal.
# AGENTS.md
## Commands
- Install: `pnpm install --frozen-lockfile`
- Dev: `pnpm dev`
- Test (default): `pnpm test:unit`
- Test (single file): `pnpm test:unit -- path/to/file.test.ts`
- Typecheck: `pnpm typecheck`
- Lint: `pnpm lint --fix`
## Always
- Run `pnpm typecheck && pnpm test:unit` before saying a change is done.
- Match the conventions of the file you are editing over any global style guide.
## Ask first
- Adding a dependency.
- Changing anything in `prisma/migrations/` or `src/db/schema.ts`.
- Touching `.github/workflows/` or anything under `infra/`.
## Never
- Commit secrets, `.env` files, or credentials of any kind.
- Report a test as passing unless you saw it exit 0. A timed-out or
interrupted run is a failure.
- Force-push, rewrite history, or amend a commit that is already pushed.
- Add "Generated with <tool>" or co-author trailers to commits or PRs.
São cerca de 150 palavras de instrução real. Não tem nenhuma descrição da arquitetura, nenhuma explicação do que o produto faz e nada que o agente pudesse ter lido do repositório — e cobre os quatro limites que explicam a maior parte dos danos que um agente causa numa base de código pequena.
A partir daí, trate-o como um registo de incidentes. Sempre que um agente fizer algo que tenha de desfazer, acrescente uma linha, no imperativo, tão específica quanto foi o erro. Dentro de seis meses terá a sua própria versão daquelas 784 proibições, e todas terão sido pagas.
Os repositórios com mais estrelas do código aberto convergiram para um formato que não se parece nada com documentação, porque o leitor não é uma pessoa. É proibitivo, específico, carregado de comandos e — nos melhores casos — muito curto.
Para um fundador que entrega um MVP com agentes a escrever a maior parte do código, esse ficheiro é provavelmente as 150 linhas com maior alavancagem do repositório. É também o único ficheiro do projeto que se paga em cada tarefa, e é precisamente por isso que o impulso de o tornar exaustivo é o impulso a resistir.
Escreva os erros. Salte a visita guiada. Deixe-o crescer uma cicatriz de cada vez.
Fontes: r/AI_Agents, «What the 100 biggest GitHub repos put in their AGENTS.md files» · Blog do GitHub, «How to write a great agents.md: lessons from over 2,500 repositories» · agents.md, sobre o formato, a sua adoção e a guarda da Agentic AI Foundation · AGENTS.md do neovim/neovim · AGENTS.md do vercel/next.js
IdeaToMVP Academy
4-week live cohort for founders. Learn to ship AI agents, scope MVPs, and automate your business — taught by the same team that writes these guides.
