Como usar o Claude Code para refatorar um projeto legado sem quebrar tudo

Fala aí, beleza? Existe um medo bem específico que aparece na hora de apontar uma IA pra um projeto antigo: a refatoração que fica linda no papel e quebra três módulos que ninguém sabia que dependiam daquele arquivo

E legado é quase sempre a mesma cena: pouco teste (ou nenhum), documentação que morreu num Confluence que ninguém acessa mais, convenção de uma época convivendo com convenção de outra, e aquele arquivo gigante que todo mundo tem medo de abrir

Aí o vibe coder animado manda "refatore esse módulo inteiro" e reza

A tese deste post é outra: o ganho não vem de um prompt melhor

Não é fórmula mágica, não é prompt secreto (essas coisas toscas)

O ganho vem de fatiar o trabalho em etapas pequenas e verificáveis, com um ponto de checagem entre cada uma delas

Bora montar esse roteiro? =)

O que você precisa antes de pedir a primeira refatoração

O juiz vem antes do código:

Antes de qualquer coisa, você precisa de um juiz forte

Juiz aqui é o critério que responde "isso ainda funciona?" sem depender da sua fé

A própria Anthropic aponta isso como pré-requisito de um projeto de migração, e o argumento é seco: sem juiz não existe condição de saída nem medida de sucesso

E tem um detalhe que muita gente pula: esse juiz precisa avaliar o código original e o código de destino nos MESMOS termos

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Se o teste só existe pro código novo, ele não é juiz, é torcida haha

Pra ter uma referência de como isso pesa: na migração do Bun de Zig para Rust conduzida com Claude Code, 100% da suíte de testes existente do Bun passava no CI antes do merge

Suíte existente, se liga nisso

Git limpo e modo de permissão escolhido:

Segundo item: repositório sob git, árvore limpa, nada de mudança solta pendurada antes de começar

É o seu segundo cinto de segurança, e ele é independente da ferramenta

Se tu ainda não tem esse fluxo redondo, vale ver como usar o Claude Code com Git pra commit e histórico antes de encarar refatoração pesada

Terceiro item: escolher o modo de permissão de forma consciente

Os modos de permissão controlam se o Claude pergunta antes de editar arquivos ou rodar comandos

No modo manual você revisa cada ação conforme ela aparece

Nos modos mais soltos, ele trabalha em trechos longos sem te interromper e reporta no final

Ou seja: o modo de permissão é literalmente o botão de granularidade da checagem humana

Em legado, começar solto é pedir pra chorar depois

Passo a passo: refatorando um projeto legado sem quebrar tudo

Agora o núcleo do post

Cada passo tem a ação exata e o erro comum que costuma aparecer nele

1. Mapear o terreno antes de tocar em qualquer linha

O Claude Code navega o código como um engenheiro faria: percorre o sistema de arquivos, lê arquivos, usa grep pra achar o que precisa e segue as referências pelo repositório

E olha que massa: isso acontece sem exigir que um índice do codebase seja construído, mantido ou enviado pra um servidor

(é justamente aí que mora boa parte da diferença entre Claude Code e Cursor na hora de encarar repo grande)

Melhor ainda: delega essa investigação a subagentes, pedindo pra ele usar subagentes pra investigar o módulo

A exploração acontece num contexto separado e a tua conversa principal fica limpa pra implementação

Erro comum deste passo: fazer toda a exploração na mesma conversa que vai implementar, e chegar na hora de editar com a janela de contexto já cheia

2. Rodar /init e gerar o CLAUDE.md

O CLAUDE.md é um arquivo markdown que o Claude Code lê automaticamente no início de toda sessão naquele diretório

Contexto persistente, sem tu ter que reexplicar o projeto toda santa vez

   /init

O /init analisa o projeto e gera um CLAUDE.md inicial na raiz, tipicamente com comandos de build, instruções de teste, diretórios importantes e convenções detectadas

A prática recomendada pela Anthropic é manter um único CLAUDE.md na raiz do repositório, versionado no git, com o time inteiro contribuindo

Erro comum deste passo: aceitar o arquivo gerado e nunca mais tocar nele

3. Fatiar a refatoração em mudanças pequenas, cada uma com critério de aceite

Antes de abrir o modo de planejamento, escreve num papel (ou no próprio CLAUDE.md) a lista de fatias

Uma fatia é uma mudança que cabe num diff que tu consegue revisar sem chorar, e que tem uma resposta objetiva de "passou ou não passou"

Tipo: extrair a leitura de configuração pra um módulo só, sem mudar comportamento

Erro comum deste passo: pedir a refatoração inteira num prompt só e depois não saber qual das 40 mudanças derrubou o teste

4. Planejar a fatia no modo de planejamento

O plan mode é acionado pressionando Shift+Tab pra ciclar os modos de permissão (o ciclo é default → acceptEdits → plan)

Dá também pra prefixar um único prompt com /plan pra ganhar um turno de planejamento, ou já abrir a sessão nele:

   claude --permission-mode plan

No modo de planejamento ele pesquisa e propõe sem executar: lê arquivos, roda comandos de exploração e escreve um plano, mas não edita o código-fonte

É somente leitura até o plano ser aprovado

Quando o plano fica pronto, ele apresenta o plano e te pergunta como prosseguir, com opções de aprovação

Ou seja, tem uma etapa explícita de aprovação humana antes de qualquer execução, e é ali que tu ganha ou perde a refatoração

E qual o critério oficial de quando planejar? A documentação recomenda o modo de planejamento quando há incerteza sobre a abordagem, quando a mudança toca vários arquivos ou quando o código é desconhecido

Legado marca os três de uma vez né? haha

Erro comum deste passo: aprovar um plano só porque ele parece bem escrito

Se o plano tá errado, é só pressionar Shift+Tab de novo pra sair do plan mode sem aprovar, e refazer o pedido com mais contexto

5. Executar a fatia aprovada, e só ela

Plano aprovado, deixa ele executar aquela fatia

Resiste à tentação de emendar "já aproveita e arruma aquele outro arquivo também"

Erro comum deste passo: deixar o escopo crescer no meio da execução e transformar a fatia pequena naquele prompt gigante que tu estava tentando evitar

6. Checar antes de seguir

Aqui entra o juiz que tu definiu lá no começo: roda a suíte, roda o build, roda o que for a tua medida de sucesso

E roda AGORA, antes da próxima fatia

Erro comum deste passo: encadear a fatia seguinte antes de verificar a anterior

Quando quebrar, tu perdeu a origem da quebra e vai bissectar na mão, que é exatamente o trabalho que a gente estava tentando não fazer

7. Voltar atrás quando quebrar

Cada prompt enviado cria um checkpoint, e o estado do código é salvo antes de cada mudança

Pra voltar, é só tocar Esc duas vezes ou usar o comando:

   /rewind

Abre um menu com as opções de restaurar só a conversa, só o código, ou ambos

E olha que topzera: os checkpoints são salvos junto com a conversa, então dá pra fechar o terminal, retomar a sessão depois e ainda assim voltar atrás

Erro comum deste passo (e esse é um limite real, tome cuidado!): os checkpoints rastreiam apenas as mudanças feitas pelas ferramentas de edição de arquivo do Claude

Alteração feita por comando Bash ou por processo externo NÃO é capturada

Por isso o git limpo do pré-requisito não é frescura…

8. Alimentar o CLAUDE.md a cada erro observado

Toda vez que ele fizer algo errado (usou a lib antiga, ignorou a convenção de nomes, mexeu na pasta que não devia), escreve isso no CLAUDE.md

Essa é a recomendação da Anthropic: adicionar ao arquivo toda vez que o Claude faz algo errado, pra não repetir o erro

O arquivo vira a memória institucional do teu legado, que é justamente o que o projeto nunca teve

Erro comum deste passo: corrigir na conversa e seguir a vida, o que garante o mesmo erro na fatia seguinte

9. Limpar o contexto entre as fatias

O /clear reseta a conversa pra um contexto vazio, e a recomendação é rodar ele ao trocar de tarefa (sair de um bug de login pra refatorar o módulo de cobrança, por exemplo)

Pode limpar sem medo: o contexto durável vai adiante no CLAUDE.md

   /clear

Se tu ainda está no meio da mesma fatia e só quer aliviar a janela, tem o /compact, que libera contexto resumindo a conversa até ali e aceita instrução de foco pro resumo

Erro comum deste passo: atravessar o projeto inteiro numa sessão só, arrastando a exploração do passo 1 até a última fatia

Por que fatiar rende mais que pedir tudo de uma vez

Essa parte não é opinião, tem razão técnica atrás

A maior parte das boas práticas do Claude Code deriva de uma restrição só: a janela de contexto enche rápido e o desempenho degrada conforme ela enche

Sacou o problema do prompt gigantão? Ele gasta janela justamente onde tu MENOS pode gastar, que é na hora da edição

A fatia pequena chega na edição com a janela folgada

E ainda ganha três coisas de brinde:

Agora o contrapeso honesto, porque nem toda mudança pede esse ritual todo

O próprio critério oficial dispensa o plano quando o diff cabe em uma frase

Renomear uma variável não precisa de plan mode, de fatia nem de cerimônia

O roteiro deste post é pra quando o código é desconhecido e a mudança espalha, que é o caso do legado

Automatizando as checagens: hooks, subagentes e worktrees

Quando esse roteiro manual vira rotina, dá pra tirar a checagem da tua mão

Os hooks PreToolUse e PostToolUse permitem interceptar as chamadas de ferramenta

Na prática: validar um comando Bash ANTES de ele rodar (os rm -rf da vida, né?) e disparar um linter DEPOIS das edições de arquivo

E tu escolhe o alcance: eles podem ser configurados no settings.json, valendo pra sessão inteira, ou no frontmatter de um subagente, valendo só enquanto ele roda

Pra mudança grande feita em lote tem outro truque bem massa: subagentes podem rodar em git worktrees isolados

Basta adicionar no frontmatter do agente:

isolation: worktree

Cada agente mexe na sua cópia, sem um pisar no arquivo do outro

E tem um detalhe de revisão que vale ouro em legado: um contexto novo melhora a revisão de código, porque assim o Claude não fica enviesado em favor do código que ele acabou de escrever

Revisar na mesma sessão que escreveu é pedir autoaprovação haha

Então: /clear, e só depois pede a revisão da fatia

Conclusão: comece pela fatia mais chata do projeto

Recapitulando o roteiro inteiro, que é curto de propósito:

• define o juiz antes de escrever qualquer linha
• roda /init e cuida do CLAUDE.md como um arquivo vivo
• planeja a fatia no plan mode e LÊ o plano antes de aprovar
• executa uma fatia só
• checa com o juiz
• limpa o contexto e vai pra próxima

Se quebrar, Esc Esc ou /rewind, lembrando que o que passou por Bash ou por processo externo não entra no checkpoint

Próximo passo concreto pra hoje: escolhe o módulo legado mais isolado do teu projeto (aquele chato, que ninguém quer pegar), roda /init na raiz e usa o modo de planejamento na primeira fatia

E aí, a parte mais importante: não aprova nada antes de ler o plano inteiro 🙂

até o próximo post!