Refatoração com Claude Code
Mantenho WP-AutoInsight sozinho. Ele roda em mais de 3.000 sites WordPress, e foi da versão 3.3 para 4.0 com muito do código escrito junto com Claude Code. Em algum ponto desse caminho, notei um padrão familiar: tarefas que costumavam levar um prompt começaram a levar quatro, e o agente começou a quebrar coisas em arquivos que não tinha negócio de tocar.
Esse padrão tem um nome, e a solução é antiga. Quando seu agente de codificação fica mais lento e começa a introduzir bugs em lugares não relacionados, a base de código precisa de refatoração, e a forma mais segura de fazer isso com Claude Code é modo de plano mais um worktree git isolado mais testes que passam antes e depois. O resto deste post é sobre como eu executo isso, e por que bases de código pesadas em IA atingem essa parede mais rápido do que as exclusivamente humanas.
Por que código escrito por IA se degrada mais rápido?
Código gerado por IA acumula débito estrutural mais rápido do que código escrito por humanos, principalmente através de volume e imitação. Um agente produz em uma semana o que um desenvolvedor costumava escrever em um mês, e cada novo arquivo que escreve copia os padrões que encontra nos já existentes. Se há um componente duplicado no repositório, o agente o duplica novamente. Se o tratamento de erros for inconsistente, o novo código é inconsistente das mesmas formas, mais alguns novos.
Humanos fazem isso também. Sempre fizemos. Bases de código derivam em direção à desordem através do uso normal, sejam as mãos no teclado biológicas ou não. A diferença é a velocidade. Uma equipe humana leva um ano para enterrar uma abstração ruim sob camadas suficientes para que ninguém queira tocá-la. Um agente trabalhando diariamente chega lá em alguns meses.
Há um segundo efeito que importa mais para qualquer pessoa fazendo trabalho sério com agentes: contexto. Uma base de código bagunçada custa mais tokens ao modelo para entender. O mesmo pedido de funcionalidade força a ler cinco arquivos quase idênticos em vez de um componente compartilhado, manter todos na memória, e adivinhar qual é o canônico. Às vezes adivinha errado. É daí que vêm os bugs em "código que você não tocou". Escrevi sobre manter o contexto do agente enxuto em meus fluxos de trabalho Claude Code WordPress, e refatoração é a versão estrutural da mesma ideia.
Remova a cerimônia e refatoração é apenas isto: mudar a estrutura do código sem mudar seu comportamento. Mesmas entradas, mesmas saídas, internos mais limpos. Essa definição não se moveu desde que Fowler a escreveu em 1999. O que mudou é quem se beneficia. Em 2026, o principal beneficiário de uma estrutura limpa é o agente que tem que lê-la duzentas vezes por dia.
Quando você deve refatorar uma base de código assistida por IA?
O sinal é o desempenho do agente, e você deve agir sobre ele mais cedo do que parece necessário. Não há um número de linhas ou data de calendário que dispare uma refatoração. O que você precisa observar é o comportamento:
- O agente leva notavelmente mais tempo em tarefas que costumavam ser rápidas
- Bugs aparecem em arquivos que o agente não foi solicitado a modificar
- Você continua aplicando o mesmo corrige em mais de um lugar
- As explicações do agente sobre a base de código começam a se contradizer entre sessões
Qualquer um desses sozinho pode ser ruído. Dois deles juntos significa desvio.
A tentação é prosseguir. Você está no meio de uma funcionalidade, o prazo é real, e parar para reorganizar pastas parece procrastinação com passos extras. Em um cliente específico no Canadá, lembro do proprietário adiando a refatoração de um plugin crítico do WordPress por quase um ano, e depois reclamando que o time não estava refatorando rápido o suficiente quando tudo quebrou com uma atualização do WP.
Refatoração é manutenção rotineira, a mesma categoria que atualizar dependências. As equipes que se machucam são aquelas que tratam isso como uma emergência em vez de rotina, porque quando se sente como uma emergência, o agente já passou semanas copiando os padrões quebrados em novo código. Se você entregou algo rápido em modo vibe coding, reserve a passagem de limpeza antes da próxima funcionalidade, enquanto a bagunça ainda é rasa.
Como refatorar com Claude Code
Aqui está a configuração que uso, um fluxo de trabalho que funciona com isolamento, planejamento e verificação, nessa ordem:
Comece em um worktree. claude --worktree refactor-name cria um checkout isolado em seu próprio branch e abre a sessão dentro dele. Seu branch principal permanece intocado, e você pode continuar entregando correções do diretório original enquanto a refatoração roda. Se a refatoração der problema, você deleta o worktree e não perde nada.
Planeje antes de tocar em qualquer coisa. Modo plano (Shift+Tab) força Claude a ler a base de código e produzir um plano escrito antes de editar um único arquivo. Para refatoração, esse passo é obrigatório. Digo a ele o que reestruturar e, importante, por quê. "Consolidar as quatro classes de geração de conteúdo porque toda alteração de provedor atualmente requer quatro edições" dá ao modelo o objetivo, então quando o plano tem que fazer uma chamada de julgamento, ele faz a alinhada com a razão. Depois eu realmente leio o plano. Na minha experiência, os planos são geralmente sólidos na primeira passagem, mas "geralmente" está fazendo trabalho naquela frase, e um plano de refatoração ruim executado com confiança é pior do que nenhuma refatoração. Minha estrutura de prompt PACREF cobre como eu enquadro essas solicitações para que o contexto e as restrições sejam explícitos em vez de implícitos.
Testes antes e depois. Isso é inegociável. Refatoração significa que o comportamento não muda, e a única prova disso é um conjunto de testes que passa antes do trabalho começar e passa depois que termina. Se o código não tem testes, escrevê-los é o passo zero da refatoração, e sim, isso torna o trabalho maior. Mas sem testes, tudo que você tem é uma reescrita e uma oração.
Uma refatoração por vez. Trabalho de funcionalidade paralela é bom. Refatorações paralelas é como você acaba com dois branches que cada um reorganizou o mesmo módulo diferentemente, e um conflito de merge que parece uma negociação de reféns.
Sobre configurações de esforço: refatoração é exatamente o tipo de tarefa onde você quer o modelo pensando duro, então use o esforço de raciocínio mais alto que seu plano permite e deixe-o levar seu tempo. Isso roda bem como uma tarefa em segundo plano enquanto você trabalha em algo mais.
Como isso se parece em projetos WordPress
Bases de código WordPress atingem essa parede em lugares específicos, geralmente aquele arquivo inicial do plugin que se tornou uma gaveta de trapos de 3.000 linhas. O site continua funcionando, então nada força a limpeza, e o agente continua empilhando código na pilha.
As refatorações que dão mais retorno rapidamente em projetos WordPress são refatorações de consolidação: uma classe de configurações em vez de cinco, um cliente de API em vez de uma chamada wp_remote_post copiada e colada em cada funcionalidade, hooks registrados em um lugar em vez de espalhados por vinte arquivos. Cada uma dessas reduz o número de arquivos que um agente tem que ler para fazer uma alteração, o que reduz tokens, tempo, e as chances de uma adivinhação errada. É a mesma razão demos de IA falham em produção: estrutura que ninguém nota na semana um decide tudo pelo mês seis.
Então quando você realmente agenda isso?
Trate como uma tarefa recorrente, mensal ou por release, o que vier primeiro. Tenha Claude Code escanear o repositório, sinalizar o que desviou, e executar uma refatoração com escopo em um worktree com testes. Estime duas a seis horas de tempo de parede por passagem em um plugin ou tema de tamanho médio, a maioria dele autossuficiente. Isso é seguro barato contra a alternativa, que é um agente que fica um pouco mais burro a cada sprint até que você não possa entregar sem babá-lo.
Os agentes escrevem o código agora. Manter o código em uma forma que possam trabalhar com ele é a parte que ainda precisa de um humano com opiniões.
Se sua equipe entregou muito código escrito por IA rápido e a velocidade agora está indo na direção errada, auditar essa base de código e configurar um fluxo de trabalho sustentável com agente é exatamente o tipo de consultoria que faço.