Neste capítulo você vai aprender a mudar a estrutura de um projeto com o Claude Code sem quebrar o que já funciona: extrair funções, renomear com consistência, dividir módulos grandes, atualizar bibliotecas, converter código de JavaScript para TypeScript e pedir uma análise arquitetural com propostas priorizadas. Tudo isso se apoia no que vimos antes: as perguntas progressivas do capítulo três, as instruções com critério de pronto do capítulo quatro e a suíte de testes do capítulo nove.
Antes de refatorar: a rede de segurança
Refatoração é a mudança da forma do código sem mudança do comportamento. Isso só pode ser verificado se existe algo que descreva o comportamento atual, e esse algo são os testes. Portanto a primeira regra é simples: não peça uma refatoração ao Claude Code em código sem testes. Se a área que você quer mexer não tem cobertura, use as técnicas do capítulo nove para gerar testes antes, focando no comportamento observável e não nos detalhes internos que estão prestes a mudar. Um teste que verifica a implementação interna vai quebrar na refatoração mesmo com o comportamento correto, e aí ele atrapalha em vez de ajudar.
A segunda regra é começar de um estado limpo no Git, como discutido no capítulo seis, para que qualquer passo possa ser desfeito sem cerimônia. A terceira é rodar a suíte completa antes de começar, para saber que ela está verde e que qualquer falha posterior foi causada pela refatoração.
Refatorações locais
Refatorações locais são as que cabem em um arquivo ou em um pequeno grupo de arquivos: extrair uma função de um trecho repetido, renomear uma variável ou um método, eliminar duplicação. Aqui o Claude Code trabalha muito bem porque a tarefa é delimitada. Ainda assim, a instrução precisa dizer o que preservar. Um pedido como melhore este arquivo convida a ferramenta a reescrever coisas que você não pediu. Prefira algo assim:
Em @src/services/tarefas.js, a lógica de validação de prazo aparece três vezes: em criarTarefa, atualizarTarefa e duplicarTarefa. Extraia essa lógica para uma função validarPrazo no mesmo arquivo e use-a nos três lugares. Não altere mensagens de erro nem assinaturas públicas. Critério de pronto: npm test passa sem nenhuma alteração nos testes.Renomear pede um cuidado extra: consistência. Um nome mudado em um módulo e esquecido em outro é um erro que só aparece em tempo de execução em linguagens dinâmicas. Peça explicitamente que ele procure todas as ocorrências, inclusive em testes, documentação e textos usados como chave, e que liste os arquivos que pretende tocar antes de editar. Quando o editor oferece renomeação semântica, como no VS Code ou nas IDEs JetBrains, vale usar o editor para o renome em si e o Claude Code para revisar o que o editor não alcança, como comentários e arquivos de configuração.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
Refatorações amplas em etapas
Dividir um módulo de duas mil linhas, introduzir uma camada de repositório entre os serviços e o banco de dados ou trocar o padrão de acesso a dados são refatorações amplas. Elas envolvem muitos arquivos e decisões de design, e por isso o fluxo muda: o primeiro passo é sempre o modo de planejamento.
Peça um plano em etapas, onde cada etapa deixa o projeto funcionando e com a suíte verde. Essa é a diferença entre uma refatoração ampla bem feita e um fim de semana perdido: em nenhum momento o código fica quebrado por horas. Um exemplo na nossa API de tarefas seria isolar o Prisma atrás de uma camada de repositório:
Quero introduzir uma camada de repositório entre os serviços e o Prisma, para que os serviços não importem o cliente do Prisma diretamente. Não edite nada ainda. Proponha um plano em etapas pequenas, cada uma terminando com a suíte verde. Para cada etapa, liste os arquivos afetados. Comece pelo módulo de tarefas e deixe os outros para depois.Revise o plano com espírito crítico. Se uma etapa toca em dez arquivos, peça para dividi-la. Depois execute uma etapa por vez, rodando os testes ao final de cada uma, exatamente como na implementação em etapas pequenas do capítulo sete. Quando uma etapa termina bem, é um bom momento para registrar o progresso no Git; como fazer isso com o Claude Code fica para o capítulo onze.
Mudanças mecânicas em muitos arquivos
Algumas refatorações não exigem raciocínio, apenas repetição: trocar uma importação em quarenta arquivos, substituir uma função descontinuada por outra, ajustar um padrão de log. O risco aqui não é o Claude errar a lógica, mas fazer uma alteração ligeiramente diferente em cada arquivo ou aproveitar para melhorar algo no caminho.
A técnica é a amostra controlada. Peça que ele faça a mudança em um ou dois arquivos primeiro e pare. Revise o diff. Se estiver correto, diga: aplique exatamente a mesma transformação nos demais arquivos, sem nenhuma outra alteração, e me mostre a lista de arquivos ao final. Assim você aprova um padrão, não quarenta diffs individuais. Uma alternativa é pedir que ele escreva um script de transformação, com sed ou um codemod, e rodá-lo. Nesse caso, rode sempre com a árvore do Git limpa e em um branch próprio, porque a edição no lugar sobrescreve os arquivos sem backup, e revise o diff antes de confirmar. Atenção também à portabilidade: no GNU sed do Linux o comando é sed -i, enquanto no macOS e nos BSD o -i exige um sufixo, como sed -i '' — copiar a linha errada pode renomear ou estragar seus arquivos. Scripts são reproduzíveis e o diff resultante é previsível.
Como revisar um diff grande
Um diff de trinta arquivos não pode ser lido linha a linha com atenção real. Três estratégias ajudam. Primeiro, peça ao Claude Code um resumo do que mudou agrupado por tipo: movimentações puras, renomeações e mudanças de lógica. Concentre a leitura humana nas mudanças de lógica, que são poucas e perigosas; movimentações e renomes costumam ser apanhados pelos testes e, quando existe, pelo compilador ou verificador de tipos. Em JavaScript puro essa rede não existe, então complemente com busca textual pelo nome antigo em todo o projeto, incluindo strings e arquivos de configuração, e com o lint. Segundo, use git diff com estatísticas para ver quais arquivos mudaram mais do que o esperado. Um arquivo que deveria só ter ganhado uma importação e mostra oitenta linhas alteradas merece investigação. Terceiro, desconfie de linhas removidas sem correspondente adicionado em outro lugar. Código que sumiu silenciosamente é um dos erros mais comuns da inteligência artificial, e voltaremos a ele no capítulo quinze.
Migrações de versão e atualização de dependências
Atualizar uma biblioteca para uma versão maior costuma gerar uma cascata de erros de compilação e de testes. O Claude Code se dá bem nesse trabalho porque os erros são concretos e a documentação de migração é pública. O fluxo recomendado: trabalhe em um branch dedicado, com o lockfile versionado no Git, atualize uma dependência por vez, rode o build e os testes, e cole a saída completa pedindo que ele classifique os erros por causa antes de corrigir qualquer um. Assim você pode voltar ao estado anterior com um simples descarte do branch. Muitas vezes cinquenta erros têm três causas. Peça então que corrija uma causa por vez, rodando o build entre elas.
Dois cuidados. Peça que ele consulte o guia de migração oficial da biblioteca em vez de adivinhar a nova interface, porque a ferramenta pode inventar nomes de funções que não existem na versão nova. E quando a atualização envolve várias dependências ligadas, como um framework e seus plugins, atualize em grupos pequenos para saber qual mudança causou qual erro.
Conversão entre linguagens ou estilos
Converter um projeto de JavaScript para TypeScript é o caso mais comum e ilustra bem o método. Não peça para converter tudo de uma vez. Configure primeiro o compilador em modo permissivo, aceitando arquivos JavaScript e TypeScript misturados, e converta módulo por módulo, começando pelas folhas do grafo de dependências, ou seja, pelos arquivos que não importam nada do próprio projeto. Para cada módulo, exija tipos reais em vez de any espalhado e proíba mudanças de comportamento: o arquivo convertido deve passar nos mesmos testes. Só no fim, com tudo convertido, ative o modo estrito e corrija os erros restantes em uma etapa própria.
O mesmo raciocínio vale para mudanças de estilo, como migrar de callbacks para async e await: um módulo por vez, testes verdes ao final de cada um, sem misturar a conversão com melhorias de lógica.
Pedindo uma análise arquitetural
Antes de decidir o que refatorar, vale pedir um diagnóstico. No modo de planejamento, com a instrução de não editar nada, peça uma análise arquitetural em três partes: pontos fortes que devem ser preservados, pontos fracos com evidência em arquivo e linha, e propostas de melhoria ordenadas pela relação entre impacto e esforço. A exigência de evidência é o que separa uma análise útil de um texto genérico sobre boas práticas. Se ele afirma que há acoplamento excessivo, deve apontar quais módulos e quais importações. Depois discuta a lista, descarte o que não faz sentido no seu contexto e transforme as duas ou três primeiras propostas em planos de refatoração como os descritos acima.
Quando dividir em várias sessões
Uma refatoração ampla acumula muito contexto: arquivos lidos, diffs gerados, saídas de teste. Quando a janela de contexto se aproxima do limite, a qualidade cai e o Claude Code começa a esquecer decisões tomadas no início. Os sinais são claros: ele repete perguntas já respondidas, sugere reverter algo combinado ou perde o padrão que estava seguindo.
A solução é tratar cada etapa do plano como uma sessão. Ao terminar uma etapa, peça um resumo curto do estado atual e das etapas restantes, grave as decisões importantes no CLAUDE.md com o atalho de memória, limpe a sessão com /clear e comece a próxima referenciando o plano. O plano pode viver em um arquivo Markdown no projeto, o que permite referenciá-lo com @ em cada sessão nova. Para refatorações de dias, isso é mais confiável do que depender de /compact, que resume mas também perde detalhes.
Recapitulando
- Refatorar sem testes é adivinhar; garanta cobertura do comportamento observável e Git limpo antes de começar.
- Em refatorações locais, diga o que extrair ou renomear, o que não tocar e qual é o critério de pronto.
- Em refatorações amplas, comece pelo modo de planejamento e exija etapas pequenas, cada uma com a suíte verde.
- Para mudanças mecânicas, aprove uma amostra e depois peça a mesma transformação nos demais arquivos, ou use um script.
- Revise diffs grandes por tipo de mudança, concentrando-se na lógica e em código removido sem substituto.
- Em migrações de versão, agrupe erros por causa e consulte o guia oficial; em conversões de linguagem, avance módulo por módulo.
- Peça análises arquiteturais com evidência e priorização, e divida trabalhos longos em sessões separadas antes que o contexto degrade.
