TL;DR
Peguei um sistema legado, zero testes, dependências desatualizadas, documentação inexistente. Em 1 dia de trabalho com o Claude Code + metodologia correta, saí de "tenho medo de tocar nisso" para "sei exatamente o que posso mudar e o que não devo."
Aqui estão os 5 passos e os prompts exatos que usei.
O Problema
Todo dev tem um desses sistemas.
Aquele que ninguém quer mexer. Que funciona por algum milagre. Que, se você perguntar "como funciona isso?", recebe um olhar vazio seguido de "acho que foi o João, mas ele saiu da empresa em 2021."
O código legado é o inimigo número 1 da produtividade de times de desenvolvimento, não porque é tecnicamente impossível de trabalhar, mas porque cria paralisia por medo.
E o medo tem um custo invisível: features que demoram 3x mais para implementar. Bugs que persistem porque "ninguém quer mexer ali." Dívida técnica que cresce enquanto o time finge que não existe.
Eu decidi atacar isso de frente essa semana.
A Abordagem Errada (que eu usava antes)
Meu primeiro instinto ao abrir código legado com o Claude era sempre:
"Analise esse código e me diga o que está errado."
Resultado: uma lista de 10 problemas genéricos. Nenhum contextualizado. Nenhum com prioridade. Sem saber qual mexer primeiro sem quebrar o resto.
O problema não era o Claude. Era a pergunta.
O Claude Code não é um oráculo. É um parceiro de trabalho. E como qualquer parceiro, ele precisa de contexto e direção para ser útil.
Os 5 Passos (com prompts)
Passo 1: Mapeamento - Entender antes de tocar
Tempo: 2 horas
Objetivo: Saber o que existe antes de mudar qualquer coisa
Analise este módulo e me diga:
1. O que ele FAZ (em 2-3 frases, sem jargão técnico)
2. Quais são as dependências externas (APIs, bibliotecas, bancos)
3. Quais partes parecem mais frágeis ou confusas
4. O que NUNCA devo mudar sem entender completamente
Não sugira melhorias ainda. Só mapeie.
Por que funciona: Você para de adivinhar e começa a entender. O Claude identifica dependências que você não saberia nem onde procurar.
Resultado no meu caso: Descobri que um módulo aparentemente simples chamava 3 APIs externas em sequência, e a ordem importava. Se eu tivesse refatorado sem saber disso, teria quebrado produção.
Passo 2: Safety Net - Testar o que existe
Tempo: 4 horas
Objetivo: Criar uma rede de segurança antes de qualquer mudança
Este código existe há 7 anos e não tem testes.
Crie testes que documentem o comportamento ATUAL.
Regras importantes:
- NÃO corrija bugs que você encontrar
- NÃO melhore o código
- Teste como o sistema se comporta HOJE, mesmo que pareça errado
- Marque com comentário // COMPORTAMENTO SUSPEITO os testes
que cobrem algo que parece ser um bug
Objetivo: capturar o estado atual para que eu saiba se mudei algo.
Por que funciona: Você tem uma baseline. Qualquer mudança que quebrar um teste existente é uma mudança que você fez sem querer - não uma melhoria.
Resultado no meu caso: O Claude encontrou 2 comportamentos suspeitos marcados como // COMPORTAMENTO SUSPEITO. Um era um bug real em produção que ninguém tinha reportado formalmente. O outro era um comportamento intencional não documentado.
Sem os testes, eu nunca saberia a diferença.
Passo 3: Refactoring Cirúrgico
Tempo: Variável (1-2h por função)
Objetivo: Melhorar sem quebrar o que funciona
Refatore APENAS a função [nome da função].
Critérios:
1. Deve passar em todos os testes existentes após a mudança
2. Máximo 1 responsabilidade por função após o refactoring
3. Não toque em nada fora desta função
4. Se precisar criar funções auxiliares, crie. Se precisar mover lógica, mova.
Antes de fazer qualquer mudança, me mostre o plano.
Por que funciona: "Refatore tudo" é um convite ao caos. "Refatore apenas esta função" é um pedido gerenciável com resultado verificável.
O "me mostre o plano primeiro" é crucial. Vi o Claude sugerir uma estrutura que faria sentido tecnicamente, mas quebraria uma dependência implícita que só aparecia no mapeamento do Passo 1.
Passo 4: Atualização de Dependências sem Drama
Tempo: 1-2 horas
Objetivo: Plano antes de atualizar qualquer pacote
Liste todas as dependências desatualizadas deste projeto.
Para cada uma:
1. Versão atual vs versão mais recente
2. Se tem breaking changes na atualização (resumo)
3. Risco: baixo / médio / alto
4. Recomendação: atualizar agora / aguardar / ignorar
Priorize por risco, não pela versão mais nova.
Não me dê uma lista de "atualize tudo" — dê um plano de prioridades.
Por que funciona: Você para de atualizar no escuro. O Claude identifica breaking changes e categoriza risco - informação que você levaria horas pesquisando no changelog de cada lib.
Passo 5: Documentar as Decisões
Tempo: 30-60 minutos
Objetivo: Garantir que o próximo dev (ou você em 6 meses) entenda por que as coisas estão do jeito que estão
Para este módulo, crie documentação de decisões com:
1. Por que ele existe (decisão de negócio, não técnica)
2. Quais trade-offs foram feitos e por que
3. O que é arriscado mudar e por quê
4. Como testar se algo quebrou após uma mudança
Escreva para um dev competente que nunca viu este código.
Não explique o óbvio. Explique o não-óbvio.
Resultado Final
Sistema: 7 anos de código, zero testes, dependências desatualizadas
Etapa | Tempo | Resultado |
|---|---|---|
Mapeamento | 2h | Entendi o sistema de verdade, não o que eu imaginava |
Safety net de testes | 4h | 67% de cobertura no core, 2 bugs encontrados |
Primeiro refactoring | 1h | 1 função, segura, testada, documentada |
Análise de dependências | 1h | Plano de 3 atualizações de baixo risco |
Documentação | 45min | Decisões registradas para o futuro |
Total: ~1 dia de trabalho
Antes: "Tenho medo de tocar neste sistema"
Depois: "Sei exatamente o que posso mudar e como verificar que não quebrei nada"
O Que Aprendi
1. Claude + metodologia bate Claude + tentativa e erro
Mesmos prompts, resultado 10x diferente quando você tem um processo.
2. Testar comportamento errado é tão importante quanto testar comportamento correto
Você precisa saber quando quebrou algo, mesmo que o "algo" fosse já ruim.
3. Uma função por vez é mais rápido do que "refatore tudo"
Parece mais lento. É mais rápido. Porque você não passa 2 horas desfazendo o que o Claude fez de forma inesperada.
4. "Não invente intenção" é o detalhe que faz diferença
Adicionei isso nos meus prompts de análise. Claude às vezes "infere" contexto que não existe. Deixar explícito que ele deve dizer quando não sabe eliminei várias falsas certezas.
Checklist: Abordando Código Legado com o Claude Code
[ ] Mapeamento primeiro — entender antes de tocar
[ ] Safety net de testes — comportamento atual documentado
[ ] Uma função por vez — refactoring cirúrgico
[ ] Plano de dependências — risco classificado
[ ] Documentação de decisões — para o próximo (ou você)
Gostou desta edição?
📤 Encaminhe para um colega que precisa disso
🐦 Compartilhe no X marcando @adrianoviana
⭐ Responda com feedback (ajuda MUITO!)
Até a próxima edição!
Abraço,
Adriano Viana