AGENTS.md como loop de feedback: 3 meses depois

Sobre os números deste texto. O padrão de loop de feedback vem do capítulo 13 do meu livro sobre code review com harness. Os intervalos (“3 meses”, “quinzenal”) e as porcentagens deste texto são cenário de trabalho para mostrar o mecanismo, não medição em produção. Meça no seu repositório antes de adotar qualquer número daqui.

O AGENTS.md que você tem hoje foi escrito uma vez, provavelmente na hora de configurar o Codex ou o Claude Code pela primeira vez, e depois virou uma daquelas “políticas” que ninguém lê e ninguém atualiza. Cinco linhas sobre “prefira TypeScript strict”, “não use any”, “commite mensagem em inglês”. Fim.

A tese deste texto: o AGENTS.md serve mal como documento de política. Serve muito bem como o sink pra onde a revisão devolve o que aprendeu, e é aí que ele começa a valer o arquivo.

O que o discurso padrão erra

A comunidade trata AGENTS.md como se fosse um linter escrito à mão. A pessoa senta, pensa “quais regras a IA deve seguir?”, escreve 10 linhas, faz commit. Pronto. No mês seguinte, esse arquivo já está desatualizado — o codebase mudou, o time descobriu 3 padrões novos, mas ninguém devolve nada pro arquivo. Ele fica lá, virando fóssil.

Ao mesmo tempo, o review do PR continua acumulando o mesmo tipo de comentário toda semana. “Você separou lógica de negócio do controller?”, “Esse any aqui pode ser unknown?”, “Faltou include no Prisma, isso é N+1”. Todo review, os mesmos 4 apontamentos. É como uma casa em que se cozinha o mesmo prato há 5 anos e ninguém escreve a receita.

O que a maioria dos times faz: nada. Ou pior, jogam mais IA em cima do problema, achando que uma IA melhor vai revisar melhor.

O que resolve o problema: o comentário que apareceu no review vira uma linha no AGENTS.md, e na próxima rodada a IA já pega o mesmo padrão antes do humano ver.

O loop, um passo por vez

Isso não é abstração. É um ciclo com 5 passos que se fecha:

Review do PR
  ↓
Apareceu apontamento repetido? (mesmo tema em 2+ PRs)
  ↓
Escreve 1 linha no AGENTS.md ("Não faça X. Em vez disso, Y.")
  ↓
Próxima rodada: agente de IA lê o AGENTS.md antes de gerar código
  ↓
O padrão erra menos → aparece menos no review → o review sobra pra decisão de design

Ao rodar isso por 3 meses, dois efeitos aparecem:

1. A qualidade do código gerado sobe — porque o agente para de tropeçar nos mesmos 5 padrões que o time já cansou de apontar.
2. A composição do review muda — cai a proporção de comentário formal (“isso é any, use unknown”) e sobe a proporção de comentário de design (“por que essa camada aqui, e não uma nova entidade?”).

Isso é o inverso do que costuma acontecer com “vamos jogar IA em cima do review”. Sem o loop, o volume de comentário fica igual, só troca de mão — o humano deixou de apontar any, agora a IA aponta. Com o loop, o padrão sobe uma camada e some da lista dos dois.

Onde entra o autoFixable

Uma parte do que sai do review nem precisa virar linha de política. Precisa virar regra de linter.

Se um apontamento de “esse any aqui” aparece 3 vezes em um mês, ele deveria ir pra:

• Nível 1: linha no AGENTS.md (“proibido any, use unknown + type guard”)
• Nível 2: regra do Biome (noExplicitAny: "error") ou do ESLint (@typescript-eslint/no-explicit-any: "error") — e a partir daí é autoFixable: o linter pega, o CI conserta, ninguém digita o comentário

O AGENTS.md é o estágio intermediário. É onde uma prática vira palavra antes de virar código. E o objetivo do loop é que, com o tempo, o item desça do nível 1 pro nível 2 — porque a partir do momento em que existe uma regra de linter que cobre aquele apontamento, escrever no AGENTS.md sobre isso vira redundante.

Essa “descida pro autoFixable” é o que faz a política encolher em vez de crescer sem parar. Sem ela, o AGENTS.md vira aquele documento de 400 linhas que ninguém consegue ler.

Rotina prática: retro da sprint devolve pro AGENTS.md

O que funciona pra mim, na prática:

A cada retro de sprint (a cada 2 semanas) — a última pergunta da pauta é sempre “apareceu apontamento repetido no review esta sprint?”. Se sim, alguém abre um PR pequeno no repo do harness alterando 1-3 linhas do AGENTS.md. Não é discussão de 40 minutos, é um PR de 3 minutos. A discussão de arquitetura fica na retro; o PR é só o output.

A cada mês — olho o harness/memory/review-patterns.jsonl (um log simples com {pattern, category, detected, autoFixable, addedToAgentsMd}). Padrão que apareceu 5+ vezes no mês, se ainda está no AGENTS.md em vez de virar regra de linter, é candidato a subir de nível.

{"id": 1, "pattern": "N+1 no Prisma", "category": "performance", "detected": 5, "autoFixable": false, "addedToAgentsMd": "2026-06-15", "description": "getAll() puxava posts em query separada. Falta o include."}
{"id": 2, "pattern": "any em resposta de API", "category": "type-safety", "detected": 12, "autoFixable": true, "addedToAgentsMd": "2026-06-15", "description": "Resposta tipada como any. Use unknown e estreite com type guard."}
{"id": 3, "pattern": "regra de negócio no Controller", "category": "architecture", "detected": 8, "autoFixable": false, "addedToAgentsMd": "2026-06-15", "description": "Check de auth escrito direto no Controller. Delega pro AuthService."}

Repare que os dois campos detected e autoFixable estão fazendo o trabalho aqui: um mede se o padrão insiste em aparecer, o outro decide se ele pertence ao AGENTS.md ou a uma regra de linter. Isso é o mesmo raciocínio que uso na comparação entre ChatGPT Codex e Claude Code — cada tipo de trabalho pertence à camada mais barata que consegue fazê-lo bem.

Ao mudar o AGENTS.md — o PR de mudança inclui:

• 1 linha de contexto (“apareceu em N PRs neste período”)
• a nova regra em uma frase imperativa
• se possível, ponteiro pra um arquivo de referência no repo (“ver src/utils/type-guards.ts”)

Regra sem contexto morre. Regra abstrata do tipo “prefira boas práticas” morre. Regra em uma frase imperativa, com ponteiro pro código real, sobrevive.

O que muda em 3 meses

Se você rodar esse loop por 3 meses seguidos, uma coisa que quase sempre aparece: o AGENTS.md deixa de ser um documento e começa a ser um artefato de time. Todo mundo sabe que ele existe, todo mundo sabe que ele muda, todo mundo sabe que os PRs de linha única no AGENTS.md são um sinal de saúde e não de burocracia.

Ao contrário do que a intuição diz, o arquivo não cresce sem parar. Ele oscila entre um teto e um piso, porque os itens “graves e frequentes” migram pra virar regra de linter (e saem do arquivo), e novos padrões entram no lugar. Isso é o loop funcionando como um harness em vez de como um arquivo de política.

O contrário disso — AGENTS.md escrito uma vez, revisão sempre com os mesmos 4 apontamentos, cada IA nova entrando com o mesmo susto — é o que acontece quando não existe loop. E aí é fácil confundir “a IA é ruim em review” com “o processo não devolve nada pra IA aprender”.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev · TabNews