Como escrever um AGENTS.md que de fato ajuda seu agente de codificação de IA

Se você usou um agente de codificação de IA em um projeto real, provavelmente chegou ao momento em que ele roda o comando de teste errado, ignora seu formatador ou reinventa um helper que você já tem. A solução geralmente não é um modelo mais esperto — é dar ao agente o contexto específico do projeto que ele não consegue inferir. É para isso que serve um arquivo AGENTS.md.

O que é o AGENTS.md

O AGENTS.md é um formato Markdown simples e aberto que dá aos agentes de codificação um lugar previsível para encontrar contexto e instruções de projeto. Começou como uma colaboração entre OpenAI Codex, Amp, Google Jules, Cursor e Factory, e agora é mantido pela Agentic AI Foundation, sob a Linux Foundation. Mais de 25 ferramentas o leem — incluindo Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed e goose — e ele aparece em mais de 60.000 repositórios de código aberto.

Pense nele como um README escrito para o agente em vez de um humano: o README explica seu projeto para um novo contribuidor; o AGENTS.md diz ao agente as coisas que ele, de outra forma, adivinharia errado. (Usuários do Claude Code vão reconhecer o CLAUDE.md como o equivalente; muitas equipes mantêm os dois, ou criam um symlink de um para o outro.)

Onde ele fica

Coloque o AGENTS.md na raiz do repositório. Em um monorepo, adicione arquivos aninhados dentro de cada pacote — os agentes leem o arquivo mais próximo na árvore de diretórios, então um packages/api/AGENTS.md tem precedência sobre o da raiz quando o agente está trabalhando naquela pasta. Isso permite que um serviço Python e um frontend TypeScript cada um receba instruções sob medida.

O que colocar nele

O formato é apenas Markdown — use os cabeçalhos que quiser. Seções comumente úteis incluem:

• Comandos de build e teste — os comandos exatos, não aproximações
• Estilo de código — formatador, linter e quaisquer convenções que um linter não pegue
• Instruções de teste — como rodar um único teste, o que precisa passar antes de uma mudança ficar pronta
• Considerações de segurança — arquivos ou operações em que nunca tocar
• Convenções de commit / PR — formato de mensagem, nomenclatura de branch
• Passos de deploy — só se o agente deve mexer neles

Aqui vai um exemplo mínimo e de alto sinal:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

Note o que não está ali: nenhuma aula de arquitetura, nenhuma reafirmação da estrutura de pastas, nenhum "este é um app web moderno construído com boas práticas." Isso é deliberado.

Mais curto costuma ser melhor

Há uma tentação de pedir ao agente para gerar um AGENTS.md gigante para você. Resista. Um estudo de 2026 da ETH Zurich, noticiado pela InfoQ, mediu o impacto real desses arquivos e descobriu que o efeito é marginal e misto. Arquivos de contexto gerados por LLM na verdade reduziram as taxas de sucesso das tarefas em cerca de 3% em média, ao mesmo tempo em que elevaram os custos de inferência em mais de 20%. Arquivos escritos por humanos ajudaram modestamente — um ganho de cerca de 4% no sucesso — mas ainda empurraram os agentes a dar mais passos, aumentando o custo em até ~19%.

O mecanismo é instrutivo: os agentes seguem obedientemente o que o arquivo diz, então um documento extenso os manda rodar testes extras, ler mais arquivos e realizar verificações de qualidade que não eram necessárias para a tarefa em questão. A recomendação dos pesquisadores: pule completamente os arquivos de contexto gerados automaticamente e limite as instruções escritas por humanos a detalhes não inferíveis — as ferramentas específicas e os comandos customizados que o agente genuinamente não consegue descobrir sozinho.

Em outras palavras, cada linha deve merecer seu lugar ao evitar um erro concreto que você de fato viu o agente cometer.

Um fluxo de trabalho que funciona

1. Comece vazio. Não escreva o AGENTS.md até ter visto o agente errar algo.
2. Adicione a correção, não a teoria. Quando ele rodar o comando de teste errado, adicione o certo. Quando ele reformatar um arquivo do seu jeito e o linter reclamar, adicione a regra.
3. Mantenha enxuto. Se uma linha só reafirma o que o agente poderia ler do package.json ou dos nomes das pastas, apague-a.
4. Use aninhamento para monorepos para que o arquivo de cada pacote permaneça pequeno.
5. Releia mensalmente. Instruções desatualizadas são piores que nenhuma — um agente que segue um comando de build desatualizado falha com confiança.

Os melhores arquivos AGENTS.md se leem como uma cola de onboarding concisa para aquele único colega que nunca esquece, mas também nunca infere. Anote as coisas que ele não consegue adivinhar, e nada além disso.