Como impedir que um agente de IA deixe a base de código uma bagunça?

Resposta curta: a bagunça que um agente de IA deixa não está espalhada pelo projeto, ela se concentra num punhado de arquivos que toda tarefa precisa tocar. Medindo o repositório deste site em 11 de agosto de 2026, 410 dos 641 arquivos versionados aparecem em um único commit em toda a história, enquanto três arquivos aparecem em 56 commits cada, mais de duas vezes e meia o quarto colocado. Vigiar esses poucos arquivos rende mais do que qualquer regra geral de estilo. Este repositório é escrito por agentes de IA em git worktrees paralelas, e isso nós sabemos por operarmos o projeto, não por termos deduzido do git.

Por que o código escrito por IA parece limpo arquivo a arquivo e mesmo assim apodrece?

Porque a unidade de trabalho de um agente de IA é a tarefa, e a unidade de qualidade de uma base de código é o conjunto. Cada entrega sai internamente coerente: nomes consistentes, teste presente, formatação impecável. O defeito não mora dentro da entrega, mora entre entregas. O agente que resolve a tarefa de hoje não sabe o que o agente de terça inventou, então cria uma função que já existia com outro nome, um segundo jeito de formatar data, uma terceira convenção para tratar erro. Nenhuma dessas escolhas é errada isolada, e é exatamente por isso que passam. A pergunta apareceu com essas palavras em r/ClaudeAI em 5 de agosto de 2026, no título "How are people using Claude Code without letting it make the codebase messy?". No mesmo dia, r/ExperiencedDevs discutia um problema vizinho e não idêntico, "What do you do when a developer submits AI generated code they clearly don't understand?": ali o tema é quem responde pelo código, não o acúmulo. Nossa leitura é que as duas conversas partem do mesmo lugar, a saída do agente ser aceitável peça a peça.

Onde a bagunça de fato se acumula?

Nos arquivos compartilhados, e a concentração é maior do que a intuição sugere. O repositório deste site tem 324 commits entre 18 de julho e 10 de agosto de 2026, com 641 arquivos versionados. Contando pelo comando da próxima seção, 410 desses arquivos aparecem em um único commit e nunca receberam um segundo. No outro extremo, os três catálogos de tradução do site, um por idioma, aparecem em 56 commits cada, e o quarto arquivo mais mexido do projeto aparece em 22. A queda do trio do topo para o quarto colocado, de 34 commits, é maior que a distância entre o quarto colocado e o chão, que é todo o resto do projeto. Isso desloca o problema: uma regra geral de estilo age sobre um projeto em que cerca de dois terços dos arquivos nunca voltaram a ser abertos. O desgaste está na minoria que toda tarefa precisa abrir.

Como descobrir quais são os arquivos compartilhados do seu projeto?

Com um comando só, e ele é o mesmo que produziu os números acima. Rode git log --name-only --format='' | grep -v '^$' | sort | uniq -c | sort -rn | head -10 e leia a lista de cima para baixo: são os arquivos que mais commits tocaram. Nos nossos números, o topo foi ocupado pelos três catálogos de tradução, pelo arquivo de configuração de ambiente e pelo de rotas, seguidos de um trio empatado em 18 commits formado pelo layout da área interna, pelo provedor de serviços da aplicação e pela página inicial. Duas ressalvas de leitura. A primeira é de método: esse comando não enxerga o que entrou por commit de merge, então ele subconta em repositório que integra por merge, e no nosso, contando também os merges, os três catálogos passam de 56 para 59 commits, as nove primeiras posições continuam as mesmas e só a décima troca de arquivo. O que muda de verdade não é a ordem, é o empate, porque o trio de 18 vira 19, 19 e 18 e se desfaz. A segunda é de aparência: com a configuração padrão do git, caminho que tem caractere fora do ASCII sai escapado, e a linha aparece com códigos numéricos no lugar do nome. É de esperar que num projeto sem internacionalização o campeão seja outro, e por isso a lista se roda no seu repositório antes de escrever qualquer regra para os agentes: é ela que diz onde a sua regra precisa valer.

O que fazer com o arquivo compartilhado, especificamente?

Três medidas que atacam o arquivo compartilhado, e não o agente. A primeira é dar a ele uma ordem interna explícita e declarada no topo do próprio arquivo, alfabética ou por seção, porque agente de IA respeita convenção que ele consegue ler ali mesmo e ignora convenção que mora na cabeça do time. A segunda é fazer com que uma inconsistência quebre alguma coisa: um teste que percorre os três catálogos de idioma e falha quando uma chave existe num e não nos outros vale mais que qualquer instrução em prosa, porque instrução se esquece e teste vermelho não. A terceira é aceitar que arquivo compartilhado é ponto de conflito quando vários agentes trabalham em paralelo, e programar a integração para que dois agentes não estejam com ele aberto ao mesmo tempo. Nenhuma das três exige que o agente melhore.

A revisão de código não deveria pegar código duplicado?

A revisão de código não pega, e a distinção é o que torna o problema difícil. Revisão de código julga uma entrega: esta mudança está certa, faz o que promete, tem teste que prova. Uma função duplicada passa nesse teste com folga, porque ela está certa. O que a revisão de entrega não enxerga é o efeito da quinquagésima entrega aprovada sobre o conjunto, já que ninguém abre as quarenta e nove anteriores para comparar. Se o seu problema é a entrega e não o acúmulo, a ordem certa de revisar saída de agente é outro assunto, e nós tratamos dele em como revisar código escrito por vários agentes de IA. O acúmulo pede uma passada periódica com pergunta diferente, do tipo "isto já existe em outro lugar", feita contra o projeto inteiro e não contra o diff.

Um arquivo de instruções e um linter resolvem a bagunça?

Resolvem parte dela, e a comunidade converge para essa combinação: em 6 de agosto de 2026, r/ClaudeWorkflows publicou um roteiro com o título "[Workflow] Claude Code Workflow: Preventing Messy Code with CLAUDE.md, Subagents, Linters, and TDD", que junta arquivo de instruções, subagentes, linter e teste antes do código. Vale a ressalva de que essas quatro peças atacam camadas diferentes. Linter e formatador resolvem a divergência mecânica, que é a mais barata e a menos danosa. Arquivo de instruções na raiz do projeto, seja CLAUDE.md ou AGENTS.md, resolve o que o agente consegue ler antes de agir. Nenhum dos dois enxerga que a função que o agente vai escrever já existe com outro nome três pastas adiante, porque isso não é uma regra, é conhecimento do repositório. Para essa parte, o que nos funcionou foi reduzir a área onde a duplicação cabe: arquivo compartilhado ordenado, teste de consistência, e tarefas menores, que produzem entregas que você consegue recusar.

O que esta medição não prova

Um repositório, 24 dias, um produto. A concentração que medimos aqui pode ser efeito do tipo de projeto, que é um site em três idiomas e por isso tem catálogo de tradução como ponto quente óbvio. Um projeto sem internacionalização teria outro campeão, e talvez uma concentração menos extrema. Há também um limite de método que vale declarar: os 324 commits têm todos o mesmo autor no git, porque os agentes assinam com a identidade da pessoa que os executa. Pelo campo de autor não dá para separar o que foi escrito por agente do que foi escrito à mão, e isso é um problema de rastreabilidade que nós não resolvemos, apenas medimos em volta. O que a medição sustenta é a forma da distribuição, não o número exato: a maior parte dos arquivos nunca é revisitada e uma minúscula minoria concentra o retrabalho.