AGENTS.md Feito Corretamente: Um Aumento de 25% na Precisão — ou uma Queda de 30%

A Augment Code realizou um estudo sistemático sobre arquivos AGENTS.md em seu monorepo. Os melhores arquivos deram ao seu agente de codificação um salto de qualidade equivalente a atualizar de Haiku para Opus; os piores tornaram a saída pior do que não ter nenhum AGENTS.md. O mesmo arquivo aumentou best_practices em 25% em uma correção de bug rotineira e reduziu completeness em 30% em uma tarefa complexa de funcionalidade no mesmo módulo. Veja o que funciona.

Como Eles Mediram

Eles usaram o AuggieBench, um conjunto de avaliação interno. Começaram com PRs de alta qualidade de um repositório grande que refletem tarefas típicas do dia a dia do agente, configuraram o ambiente e o prompt, e pediram ao agente para reproduzir o PR. Compararam a saída com o PR dourado (a versão que foi aprovada após revisão por vários engenheiros seniores). Os PRs tinham que estar contidos em um único módulo ou aplicativo, e o escopo precisava ser algo onde um AGENTS.md pudesse plausivelmente ajudar. Cada tarefa foi executada duas vezes — com e sem o arquivo.

O Que Funciona

1. Divulgação Progressiva > Cobertura Abrangente

Cubra casos comuns e fluxos de trabalho em alto nível; empurre detalhes para arquivos de referência que o agente pode carregar sob demanda. Mantenha o escopo de cada referência claro. Arquivos de 100 a 150 linhas com alguns documentos de referência focados proporcionaram melhorias de 10 a 15% nas métricas em módulos de médio porte (~100 arquivos principais). Acima desse comprimento, os ganhos se reverteram.

2. Fluxos de Trabalho Procedurais

Um fluxo de trabalho numerado de várias etapas pode fazer o agente passar de falha para conclusão. Exemplo: um fluxo de trabalho de seis etapas para implantar uma nova integração. Arquivos de conexão ausentes caíram de 40% para 10%, o agente terminou mais rápido, a correção aumentou 25%, a completeza aumentou 20%. Mantenha o arquivo principal conciso e use arquivos de referência para casos de ramificação.

3. Tabelas de Decisão

Quando duas ou três maneiras razoáveis existem (por exemplo, React Query vs Zustand para gerenciamento de estado), force a escolha antecipadamente com uma tabela. Exemplo:

Pergunta → React Query → Zustand
O servidor é a única fonte de dados? ✅
Múltiplos caminhos de código alteram esse estado? ✅
Precisa de atualizações otimistas misturadas com estado local? ✅

PRs nessa área pontuaram 25% mais alto em best_practices.

4. Exemplos Curtos de Produção

Snippets de 3 a 10 linhas do código de produção real melhoraram a reutilização e a adesão a padrões. Exemplo: modelos de copiar-colar para primitivas do Redux Toolkit (createSlice com estado inicial tipado, createAsyncThunk com tratamento de erros, useAppSelector tipado). code_reuse subiu 20%.

5. Regras Específicas de Domínio

Ainda importam — o padrão que a maioria das pessoas já associa ao AGENTS.md.