Refatoração com o Claude Code: plano, passos pequenos e testes verdes

O que o Claude Code faz em refatoração

• Avança por um backlog de refatoração em passos pequenos, cada um no seu próprio pull request.
• Roda os testes antes e depois de cada passo e para quando eles falham.
• Faz a parte mecânica das migrações: renomeações em todo o código, upgrades de API, a troca para uma biblioteca nova.
• Remove código morto e lógica duplicada e explica cada remoção.

Recursos do Claude Code para refatoração

Como configurar o Claude Code para refatoração

1. Conecte as ferramentas

   Não há nada para conectar. O que torna uma refatoração segura é um comando de teste que o Claude possa rodar e um limite para o tamanho de cada passo, então coloque os dois no CLAUDE.md e comece em um worktree.

   # Comece a refatoração em um worktree próprio
   claude --worktree billing-async
   
   # Combine o plano antes de qualquer edição
   /plan Move the billing module from callbacks to async/await

2. Escreva as regras no CLAUDE.md

   O Claude Code lê o CLAUDE.md no início de toda sessão, inclusive nas execuções com claude -p. Coloque ali as regras do trabalho, ou em uma skill em .claude/skills/ se forem longas. Veja o guia do CLAUDE.md.

   ## Regras de refatoração
   - Nenhuma mudança de comportamento. Se um teste precisar mudar,
     pare e pergunte.
   - Rode `npm test` antes de começar e depois de cada passo.
   - Um passo por pull request, com menos de 400 linhas alteradas.
   - Mantenha o REFACTOR.md em dia: marque o que foi feito e
     acrescente o que você encontrou.
   - Não mexa em migrations/, arquivos gerados ou APIs públicas
     sem perguntar.

3. Rode sem a interface interativa

   claude -p roda uma tarefa e encerra, então o cron, o CI ou outra ferramenta pode iniciá-lo. Escolha o que ele pode fazer sem pedir com --allowedTools ou --permission-mode; --output-format json devolve o resultado com o custo.

   # Um passo por dia do backlog no REFACTOR.md
   claude -p "Faça o próximo item não marcado do REFACTOR.md e mantenha os testes verdes" \
     --allowedTools "Bash(npm test),Read,Edit"

4. Coloque em um agendamento

   Transforme-o em uma tarefa agendada na nuvem com /schedule (Pro, Max, Ultra, Team e Enterprise) ou em uma tarefa agendada no desktop, ou use /loop enquanto uma sessão fica aberta. Veja como deixar o Claude Code proativo.

Fonte: documentação do Claude Code

Limites e segurança

• Sem testes, ele não consegue distinguir uma refatoração de uma mudança de comportamento. Adicione testes para a área primeiro.
• Uma reescrita grande de uma vez só é difícil de revisar. Passos pequenos que entram um a um são mais seguros e, no fim, mais rápidos.
• Ele não sabe qual código estranho é proposital. Marque esses trechos com um comentário ou nas regras.
• Desde o Claude Code v2.1.302, claude -p começa no modo Manual: uma ação que precisa de aprovação é negada, a menos que uma regra a permita. Permita só as ferramentas de que o trabalho precisa.

Claude Code ou Codex para refatoração?

As regras valem para os dois. Escreva-as uma vez no AGENTS.md e coloque @AGENTS.md no CLAUDE.md, e os dois agentes leem o mesmo arquivo.

Passo a passo para o outro agente: refatoração com o Codex.

Coloque alguém responsável por refatoração

Comandos rodam quando alguém lembra de rodá-los. O Crewmark transforma o seu próprio Claude Code em um funcionário de IA com um cargo, uma meta em números, horário de trabalho e um heartbeat, então o trabalho acontece no horário e aparece em um quadro.

1. Comece pelo cargo

   O engenheiro de software com IA, com estas regras no brief.

2. Leve o trabalho para o quadro dele

   Adicione o trabalho como issue recorrente. O funcionário acorda com o heartbeat, faz o trabalho e relata em um comentário.

3. Veja também

   Revisão de código confere cada passo antes do merge.

Perguntas frequentes