A IA Limpa-se a Si Própria

O seu repositório fica mais confuso a cada vez que um agente de IA lança uma funcionalidade. Código morto acumula. Branches partem e ficam ali. Padrões de nomenclatura derivam. Nada disto é dramático. Apenas vai somando, funcionalidade após funcionalidade, até a base de código ser mais lenta de mudar e mais assustadora de tocar.

Este post explica uma equipa de limpeza que trata disso por você, num horário, enquanto dorme. Três workflows. Um agendador. Cada um pega num tipo diferente de bagunça e trata dela em silêncio. Você acorda, lê um email, e sabe o que foi varrido, o que foi corrigido e o que ainda precisa de um olhar humano.

As três pequenas bagunças que se tornam grandes bagunças

A maioria dos problemas de base de código não começa grande. Começa pequena e fica pequena durante um tempo. Depois, algumas funcionalidades mais tarde, a versão pequena tem cópias em três outros lugares e a limpeza é uma semana em vez de uma hora.

Estas são as três que aparecem mais em repositórios com muita IA.

1. Código morto que ninguém elimina

O agente lança uma funcionalidade. Uma semana depois você lança uma versão diferente dessa funcionalidade. O código antigo ainda fica lá. Ninguém o elimina porque ninguém tem a certeza se algo ainda o usa. Três funcionalidades mais tarde, o seu repositório tem três helpers abandonados, duas rotas não usadas e uma página completa para a qual nenhum link aponta.

Num projeto médio, o código morto cresce para cerca de 18% do repositório em poucos meses. É código a ser verificado por tipos, lintado, empacotado e carregado em cada build. Abranda builds a frio, confunde novos colaboradores e torna as refatorações mais assustadoras do que precisam de ser.

O problema não é encontrar código morto. Um linter consegue fazer isso. O problema é eliminá-lo com segurança. Você precisa de saber que remover o ficheiro não parte nada. A maioria das vezes, ninguém tem paciência para verificar isso linha por linha, por isso o código morto fica.

2. Branches partidas que bloqueiam lançamentos

Uma execução de agente termina. Diz que a funcionalidade está feita. Você vai buscar o branch de manhã e a build está vermelha. Erro de tipo, teste falhado, import em falta. Coisa pequena. Você corrige em dez minutos.

Exceto que faz isso várias manhãs por semana. Dez minutos aqui. Vinte minutos ali. Dois dias completos por mês perdidos a corrigir uma entrega partida antes de poder sequer começar o trabalho real. E se a quebra aterra no main, cada outra funcionalidade espera por isso.

A correção é simples em teoria. O agente devia corrigir a sua própria quebra. Na prática, isso significa executar testes, ler o erro, editar o ficheiro certo e não piorar as coisas adivinhando. Esse é um loop que a maioria dos agentes não consegue fechar por si próprios sem estrutura extra.

3. Padrões que derivam silenciosamente

Você tem quatro funcionalidades que todas fazem mais ou menos a mesma coisa: auth, billing, notify, search. Todas seguem um padrão. Mesma forma de pasta. Mesmos nomes de ficheiro. Mesmo nome para as funções chave.

Depois uma funcionalidade deriva. O agente nomeia algo ligeiramente diferente. Ou divide um ficheiro que as outras mantêm junto. Ou pula um padrão que todas as outras partilham. Sozinho, está tudo bem. Três funcionalidades mais tarde, um novo agente vê a que derivou e copia essa forma em vez da original. Agora tem uma bifurcação na sua própria base de código com que ninguém concordou.

A deriva é a bagunça mais cara das três. Um ficheiro morto custa-lhe uma eliminação. Uma branch partida custa-lhe uma manhã. Uma deriva que se propaga para mais três funcionalidades custa-lhe uma refatoração real em toda a pasta.

A equipa de limpeza

O sistema são três workflows do Claude Code que correm num único horário noturno. Pode pensar neles como uma equipa de limpadores, cada um com um trabalho estreito.

Um agendador acorda a equipa à noite. Dispara cada workflow em ordem. Cada um escreve uma nota curta num log partilhado. O último passo monta o log num email e envia-o para você.

Nada lança para o main por si próprio. As edições do slop-cleaner acontecem por trás de testes. O /heal trabalha numa branch lateral, não no main. O /drift apenas sinaliza, não reescreve. Você continua a ser a pessoa que aceita ou rejeita o relatório da manhã.

Limpador um: slop-cleaner

O trabalho do slop-cleaner é eliminar código morto sem partir nada.

O truque é a ordem. A maioria das ferramentas de código morto analisam, listam e depois deixam um humano eliminar. Isso é lento porque ninguém quer ser a pessoa que parte a produção ao remover o ficheiro errado. O workflow inverte a ordem: escreva a rede de segurança primeiro, depois elimine, depois execute novamente a rede de segurança.

Passo um, escrever testes de regressão. O agente analisa os ficheiros que estão prestes a ser tocados e escreve um pequeno teste para cada um que ainda tem um chamador. O objetivo não é cobertura total. O objetivo é um sinal verde que diz "as partes que importam ainda funcionam." Estes testes são confirmados numa branch lateral para que um humano os possa ler.

Passo dois, eliminar o código morto. O agente usa uma verificação estática para listar candidatos: ficheiros com zero imports de entrada, funções nunca chamadas, rotas sem links, tipos nunca referenciados. Remove-os em pequenos lotes.

Passo três, execute novamente os testes. Se todos os testes ainda estiverem verdes, as eliminações ficam. Se algum teste ficar vermelho, a eliminação específica que o causou é revertida. O agente não tenta "corrigir" o teste. Assume que a eliminação estava errada e reverte-a. Nada subtil.

O resultado é um repositório que fica mais leve sem o medo habitual. Numa execução noturna, a equipa removeu 412 linhas de código morto de um SaaS de tamanho médio. Zero testes partiram. Zero páginas pararam de renderizar. Na manhã seguinte, o revisor percorreu o diff, clicou em aprovar e seguiu em frente.

O slop-cleaner só funciona se a rede de segurança dos testes for honesta. Se o agente escrever testes falsos que passam sempre, o padrão todo cai. O workflow aplica uma regra: cada teste deve chamar uma função real e afirmar um resultado real. Testes que nunca importam o ficheiro sob teste são rejeitados.

Limpador dois: /heal

O trabalho do /heal é corrigir branches partidas sem colocar código partido no main.

Quando o /heal acorda, lê a lista de branches de funcionalidades recentes. Para cada uma, executa a build, a verificação de tipos e a suite de testes. Se uma branch estiver vermelha, o /heal começa a trabalhar nela.

O detalhe importante: o /heal trabalha numa branch lateral, não no original. Copia a branch partida para algo como heal/feature-name, faz as suas edições aí e deixa o original intacto. O main fica limpo durante todo o tempo. O autor original ainda é dono da decisão de correção.

O loop de correção é apertado. O /heal lê a primeira verificação falhada e faz uma pergunta: que mudança faz esta verificação específica passar? Edita a menor superfície possível, executa novamente a verificação e passa para a próxima falha. Não refatora. Não melhora. Apenas fecha os sinais vermelhos.

Depois do loop, o /heal executa tudo novamente. Se todas as verificações passarem, pontua a sua própria confiança numa escala de zero a cem. A pontuação é baseada em sinais simples: a correção tocou num ficheiro de teste ou num ficheiro de fonte, quantas linhas mudaram, os erros eram claros e estreitos ou vagos e largos, o mesmo teste falhou duas vezes seguidas antes de passar.

Depois o /heal escreve um veredicto curto e envia por email. O veredicto inclui o nome da branch, a pontuação de confiança, os ficheiros exatos alterados e uma razão de uma linha. Noventa e dois por cento de confiança, dois ficheiros tocados, import em falta no handler. Esse tipo de nota.

Um humano ainda decide se faz merge. Alta confiança com um diff apertado normalmente recebe um sim. Baixa confiança ou um diff largo recebe um olhar mais atento. O ponto não é remover a revisão humana. O ponto é garantir que o humano está a rever uma correção limpa e estreita em vez de uma branch vermelha bruta.

Limpador três: /drift

O trabalho do /drift é detetar divergência de padrões em funcionalidades recentes antes que se espalhe.

Quando o /drift acorda, constrói um mapa de padrões da sua base de código. Escolhe um pequeno conjunto de funcionalidades (normalmente as últimas cinco a dez) e regista a forma de cada uma: layout de pasta, nomes de ficheiro, nomes de funções, estilo de import, localização de testes. Isto é um snapshot simples, não uma análise profunda.

Depois compara. Se quatro funcionalidades têm a mesma forma e uma funcionalidade é ligeiramente diferente, essa é uma outlier. O /drift não reescreve a outlier. Sinaliza-a.

Uma sinalização tem este aspeto: "notify usa sendNotification enquanto auth, billing e search usam sendEmail. Deriva de nomenclatura. Custa 4x mais a corrigir depois de mais três funcionalidades a copiarem." Isso é específico o suficiente para agir e vago o suficiente para deixar a decisão final para um humano.

Por que sinalizar em vez de corrigir. Porque a deriva nem sempre está errada. Às vezes a outlier é a escolha certa e as outras quatro são o legado. Um humano consegue dizer qual é qual. Um agente não consegue, porque a regra muda com base na intenção. Por isso o /drift faz o trabalho para que um agente é bom (detetar o padrão) e deixa o julgamento para você.

A janela crítica é cedo. Se o /drift detetar a deriva em notify antes de mais três funcionalidades copiarem o padrão, a correção é um ficheiro. Se o detetar depois, a correção são quatro ficheiros mais a coordenação entre equipas. É daí que vem o número "custa 4x mais a corrigir."

Uma noite, um horário

O agendador é simples. Um gatilho, uma entrada no estilo cron, dispara a uma hora definida todas as noites.

Quando dispara, uma nova sessão do Claude Code começa. O orquestrador lê o estado atual do repositório e executa os três workflows em ordem: slop-cleaner, depois /heal, depois /drift. Cada um escreve uma nota curta num log partilhado em ./overnight.log.

A ordem importa. O slop-cleaner corre primeiro porque encolhe o código em revisão. O /heal corre segundo porque corrige o que está partido agora. O /drift corre por último porque lê a versão mais limpa do repositório, depois dos outros dois terem feito o seu trabalho.

Cada limpador tem um orçamento de tempo. Se correr muito, o workflow termina esse passo e passa ao próximo. O ponto é um email matinal previsível, não uma noite perfeita. O trabalho inacabado é sinalizado e retomado na noite seguinte.

Nada nesta configuração requer uma plataforma cloud. Uma entrada real de crontab na sua máquina funciona. Uma tarefa agendada do Claude Code Desktop funciona. A escolha é operacional, não arquitetural. O que importa é que o gatilho dispara, uma nova sessão acorda e o orquestrador sabe onde começar.

O relatório da manhã

O último passo da execução noturna monta o log num email e envia-o. O formato é curto, digitalizável e ordenado de "não precisa de nada" para "precisa de revisão."

Um log matinal real tem este aspeto:

overnight.log - janitor crew
01:00  Slop-cleaner swept the repo
       412 dead lines removed. Tests green.

02:30  /heal rescued a broken branch
       Fixed on side branch. 92% confidence.

04:00  /drift caught a naming gap
       1 file out of pattern. Flagged.

07:00  Verdict emailed to you
       3 cleanups ready for review.

Você lê-o com o café da manhã. Quatro minutos, no máximo. Cada linha tem uma hora, um resultado curto e um número que lhe diz o quão confiante o limpador estava. As limpezas com alta confiança normalmente são aprovadas no momento. A deriva sinalizada recebe uma vista rápida e ou uma correção ou um "deixa, esse é intencional."

A forma do email é o ponto. Curto. Concreto. Ordenado. Sem resumos em prosa. Sem "o agente trabalhou muito esta noite". Você quer saber o que mudou, o quão certo o limpador está, e o que precisa de fazer a respeito. Mais nada.

Como construir a sua própria versão

Você não precisa da stack toda para obter o benefício. O padrão é simples. Comece com esta forma e expanda a partir daí.

Escreva três pequenos workflows. Mantenha-os estreitos. O slop-cleaner elimina código morto apenas se um teste passar. O /heal corrige branches partidas apenas numa branch lateral. O /drift sinaliza divergência de padrões apenas em funcionalidades recentes. Cada um tem um único trabalho e um único formato de saída.

Ponha-os por trás de um agendador. O Cron está bem. Uma sessão agendada do Claude Code está bem. Você não precisa de uma fila de jobs ou um message bus. Você precisa de um ping que acorde a equipa a uma hora definida.

Escreva os testes de regressão antes de eliminar, sempre. Esta é a regra que torna o slop-cleaner seguro. Se o agente não consegue escrever um teste honesto para o ficheiro que quer eliminar, a eliminação não acontece. Essa única regra vale o workflow todo.

Mantenha o /heal numa branch lateral. O main deve ficar limpo. Se a correção do /heal estiver errada, a branch lateral é descartada e a branch partida original ainda está à espera de um humano. Sem surpresas no main, nunca.

Faça o /drift sinalizar, não corrigir. Esta é a regra mais difícil de manter. Os agentes querem "melhorar" o código quando o veem. Para a deriva, esse é o movimento errado. Um padrão que parece errado pode ser intencional. O trabalho do agente é surfaciá-lo e parar. O trabalho do humano é decidir qual o padrão a seguir.

Termine cada execução com um email curto e estruturado. Hora, resultado, número, razão de uma linha. Mais nada. Se você não consegue digitalizar o email todo em menos de cinco minutos, o limpador está a fazer demasiado trabalho numa noite. Divida.

Onde mais este padrão se aplica

Uma vez que você tem uma equipa de limpeza a correr no código, a mesma forma funciona para outros tipos de bagunça de combustão lenta.

Limpador de conteúdo. Um workflow que varre posts antigos do blog, sinaliza secções desatualizadas e escreve uma nota para o autor. Não reescreve. Sinaliza.

Limpador de analítica. Um workflow que verifica a nomenclatura de eventos em todo o seu produto à procura de deriva, sinaliza outliers e propõe uma lista canónica. Mesmo mapa de padrões que o /drift, entradas diferentes.

Limpador de dependências. Um workflow que verifica packages não usados, escreve um teste que importa cada ativo e remove o resto se os testes ainda passarem. Mesma rede de segurança que o slop-cleaner, aplicada ao package.json.

A ideia central não é "IA limpa código." É "pequenas bagunças são tratadas num horário, por trás de uma rede de segurança, num formato que você consegue ler em cinco minutos." Isso funciona para código, conteúdo, analítica e qualquer outra coisa que se acumule silenciosamente entre os grandes lançamentos.

Uma equipa. Um horário. Três trabalhos estreitos. Um repositório mais limpo de manhã e um email que respeita o seu tempo. É o sistema todo.