Eu mantenho o WP-AutoInsight sozinho. Ele passou de 6.000 downloads no WordPress.org, e foi da versão 3.3 à 4.0 com boa parte do código escrita junto com o Claude Code. Em algum ponto desse caminho, notei um padrão conhecido: tarefas que antes levavam um prompt passaram a levar quatro, e o agente começou a quebrar coisas em arquivos que não tinha nada que tocar.
Esse padrão tem nome, e a solução é antiga. Quando o seu agente de programação fica lento e começa a criar bugs em lugares sem relação com a tarefa, o código precisa de refatoração, e o jeito mais seguro de fazer isso com o Claude Code é modo plano, mais um git worktree isolado, mais testes passando antes e depois. O resto deste post é sobre como eu faço isso, e por que código com muita IA bate nessa parede mais rápido do que código só humano.
Por que código escrito por IA se degrada mais rápido?
Código gerado por IA acumula dívida estrutural mais rápido que código escrito por gente, principalmente por volume e por imitação. Um agente produz numa semana o que um desenvolvedor escrevia num mês, e cada arquivo novo copia os padrões que ele encontra nos que já existem. Se tem um componente duplicado no repositório, o agente duplica de novo. Se o tratamento de erro é inconsistente, o código novo sai inconsistente do mesmo jeito, e mais um pouco.
Gente faz isso também. Sempre fez. Todo código escorrega pra bagunça com o uso normal, sejam as mãos no teclado de carne e osso ou não. A diferença é a velocidade. Um time humano leva um ano pra enterrar uma abstração ruim debaixo de tanta camada que ninguém mais quer mexer. Um agente trabalhando todo dia chega lá em poucos meses.
Tem um segundo efeito, que pesa mais pra quem trabalha sério com agentes: o contexto. Código bagunçado custa mais token pro modelo entender. O mesmo pedido de funcionalidade obriga ele a ler cinco arquivos quase iguais em vez de um componente compartilhado, segurar todos na memória e adivinhar qual é o oficial. Às vezes ele erra. É daí que vêm os bugs em "código que você nem mexeu". Escrevi sobre manter o contexto do agente enxuto nos meus fluxos de WordPress com Claude Code, e refatoração é a versão estrutural da mesma ideia.
Tirando a cerimônia, refatorar é só isto: mudar a estrutura do código sem mudar o comportamento. Mesmas entradas, mesmas saídas, por dentro mais limpo. Essa definição não mudou desde que o Fowler escreveu, em 1999. O que mudou foi quem ganha com ela. Em 2026, quem mais se beneficia de uma estrutura limpa é o agente que precisa ler aquilo duzentas vezes por dia.
Quando refatorar um código feito com ajuda de IA?
O sinal é o desempenho do agente, e vale agir antes do que parece necessário. Não existe número de linhas nem data no calendário que dispare uma refatoração. O que você observa é o comportamento:
- O agente demora visivelmente mais em tarefas que antes eram rápidas
- Aparecem bugs em arquivos que o agente não recebeu pedido pra alterar
- Você vive aplicando a mesma correção em mais de um lugar
- As explicações do agente sobre o código começam a se contradizer de uma sessão pra outra
Qualquer um desses sozinho pode ser ruído. Dois juntos querem dizer desvio.
A tentação é seguir em frente. Você está no meio de uma funcionalidade, o prazo é real, e parar pra reorganizar pasta parece procrastinação com passos extras. Num cliente específico no Canadá, lembro do dono adiando a refatoração de um plugin crítico de WordPress por quase um ano, e depois reclamando que o time não refatorava rápido o bastante quando tudo quebrou numa atualização do WordPress.
Refatorar é manutenção de rotina, da mesma categoria que atualizar dependências. Quem se machuca é o time que trata isso como emergência em vez de rotina, porque quando vira emergência o agente já passou semanas copiando os padrões quebrados pro código novo. Se você entregou algo rápido no modo vibe coding, reserve a passada de limpeza antes da próxima funcionalidade, enquanto a bagunça ainda é rasa.
Como refatorar com o Claude Code
Esta é a configuração que eu uso, um fluxo que funciona com isolamento, planejamento e verificação, nessa ordem:
Comece num worktree. claude --worktree nome-da-refatoracao cria um checkout isolado num branch próprio e abre a sessão lá dentro. O seu branch principal fica intocado, e você continua entregando correções pela pasta original enquanto a refatoração roda. Se a refatoração der errado, você apaga o worktree e não perde nada.
Planeje antes de mexer em qualquer coisa. O modo plano (Shift+Tab) obriga o Claude a ler o código e produzir um plano escrito antes de editar um único arquivo. Em refatoração, esse passo é obrigatório. Eu digo o que reestruturar e, principalmente, por quê. "Consolidar as quatro classes de geração de conteúdo, porque hoje toda troca de provedor exige quatro edições" dá ao modelo o objetivo, e aí, quando o plano precisa fazer uma escolha, ele faz a que combina com o motivo. Depois eu leio o plano de verdade. Na minha experiência, os planos costumam sair sólidos de primeira, mas esse "costumam" está trabalhando pesado na frase, e um plano de refatoração ruim executado com confiança é pior que refatoração nenhuma. A minha estrutura de prompt PACREF mostra como eu monto esses pedidos pra que contexto e restrições fiquem explícitos, e não subentendidos.
Testes antes e depois. Isso não se negocia. Refatorar quer dizer que o comportamento não muda, e a única prova disso é uma suíte de testes que passa antes de o trabalho começar e continua passando depois que ele termina. Se o código não tem teste, escrever os testes é o passo zero da refatoração, e sim, isso aumenta o trabalho. Mas sem teste, tudo o que você tem é uma reescrita e uma reza.
Uma refatoração por vez. Funcionalidades em paralelo, tudo bem. Refatorações em paralelo é como você termina com dois branches que reorganizaram o mesmo módulo cada um do seu jeito, e um conflito de merge que parece negociação de sequestro.
Sobre o nível de esforço: refatoração é exatamente o tipo de tarefa em que você quer o modelo pensando pesado, então use o esforço de raciocínio mais alto que o seu plano permite e deixe ele no tempo dele. Roda bem como tarefa em segundo plano enquanto você trabalha em outra coisa.
Como isso fica em projetos WordPress
Código WordPress bate nessa parede em lugares bem específicos, normalmente naquele arquivo principal do plugin que virou uma gaveta de bagunça com 3.000 linhas, e é o tipo de dívida que a manutenção e engenharia WordPress existe pra pegar antes que ela cresça. O site continua funcionando, então nada obriga a limpeza, e o agente continua empilhando código em cima.
As refatorações que se pagam mais rápido em projetos WordPress são as de consolidação: uma classe de configurações em vez de cinco, um cliente de API em vez de um wp_remote_post copiado e colado em cada funcionalidade, hooks registrados num lugar só em vez de espalhados por vinte arquivos. Cada uma dessas diminui o número de arquivos que o agente precisa ler pra fazer uma alteração, o que diminui token, tempo e a chance de um chute errado. É o mesmo motivo pelo qual demos de IA falham em produção: a estrutura que ninguém nota na primeira semana decide tudo no sexto mês.
Então, quando colocar isso na agenda?
Trate como tarefa recorrente, todo mês ou a cada release, o que vier primeiro. Peça ao Claude Code pra varrer o repositório, apontar o que escorregou e fazer uma refatoração com escopo fechado num worktree, com testes. Conte de duas a seis horas de relógio por passada num plugin ou tema de tamanho médio, a maior parte rodando sozinha. É um seguro barato contra a alternativa: um agente que fica um pouco mais burro a cada sprint, até você não conseguir entregar nada sem ficar de babá dele.
Quem escreve o código agora são os agentes. Manter o código num formato com que eles consigam trabalhar é a parte que ainda precisa de um humano com opinião.
Se o seu time entregou muito código escrito por IA, rápido, e agora a velocidade está indo na direção errada, auditar esse código faz parte do trabalho de desenvolvimento WordPress que eu faço. Me traz o repositório.