IA para Reescrever Código Legado: Fluxo que Funciona

Imagem: Pexels
Código legado tem uma armadilha conhecida: ninguém tem certeza do que ele faz de verdade. A função com nome estranho tem três comportamentos não documentados, um deles é bug que cliente depende. A promessa de "a IA reescreve tudo em uma tarde" morre exatamente aí — modelo gera código bonito e moderno que quebra o comportamento implícito. Existe um fluxo que funciona, e ele começa longe do prompt de refatoração: primeiro você prova o comportamento atual, depois delega a reescrita por pedaços, e só então troca de verdade.
1. Nunca comece pela reescrita: comece pelos testes de caracterização
Antes de tocar em uma linha, cubra o comportamento atual com testes de caracterização: testes que documentam o que o código faz hoje, incluindo as esquisitices. Não precisa de cobertura total — comece pelos caminhos que o negócio usa: fluxo de compra, cálculo de imposto, geração de relatório, autenticação. A IA ajuda aqui de verdade: peça para o agente ler a função e listar todos os efeitos observáveis (retorno, exceções, escrita em banco, logs), e transforme cada item em asserção. Se o teste passa no código velho, você tem rede de segurança. Sem ela, a reescrita é aposta.
2. Mapeie o escopo com o próprio agente
Pedir "melhore este arquivo" é receita para diff de 2 mil linhas impossível de revisar. Em vez disso, use o agente para mapear: quais funções este módulo chama, quem o chama, onde há estado compartilhado, quais dependências externas. Saída esperada: um diagrama simples (texto resolve) e uma lista do que é interface pública versus detalhe interno. Arquivos que ninguém chama podem sair do escopo na hora zero — em legado, parte relevante do trabalho é descobrir o que dá para apagar com segurança.
3. O fluxo de reescrita: um módulo por vez, diff pequeno
- Escolha um módulo coeso com testes passando (não o arquivo mais odioso — o mais isolado).
- Peça a reescrita com restrições explícitas: manter assinatura pública, não adicionar dependência nova, manter comportamento de erro.
- Rode os testes de caracterização e a suíte inteira.
- Leia o diff como revisor de estranho: efeito colateral, tratamento de erro, performance em laço, conversão de tipos.
- Merge e siga. Nada de branch de três semanas com "refatoração geral".
A restrição "sem dependência nova" evita o cenário clássico em que o código legado ganha três bibliotecas para substituir quatro linhas. Modernizar a sintaxe é barato; mudar o grafo de dependência é o que quebra produção.
4. Onde o modelo erra em código legado
- Comportamento implícito: o valor default "errado" que o sistema inteiro depende. Por isso os testes vêm antes.
- Side effects escondidos: escrita em log, cache, arquivo temporário — código novo costuma "limpar" isso e quebrar integração.
- Ordem de operação: em processamento de lote e transações, trocar a ordem das etapas muda resultado numérico.
- Detalhes de locale: fuso, formato de moeda e ordenação de string variam entre ambientes — teste com dados brasileiros reais.
- Escopo grande demais: quanto mais arquivo, mais o modelo "inventa" estrutura nova em vez de preservar a existente.
5. Checklist do review humano em 10 minutos
Para cada diff de agente, faça estas perguntas: os testes novos cobrem o comportamento antigo ou só o novo? A assinatura pública mudou? Apareceu dependência nova? O código usa a biblioteca de logs do projeto ou print? Tem caminho de erro que agora falha em silêncio? O diff está dentro do módulo escolhido? Um diff que responde "não" em mais de uma pergunta volta para o agente com comentário específico — não com "melhore", e sim com "mantenha o comportamento de erro do arquivo original" e afins.
6. O que automatizar depois do primeiro módulo
Depois de três ou quatro módulos nesse ritmo, dá para ganhar velocidade: gerador de testes de caracterização por módulo novo, verificação automática de dependência (CI bloqueando biblioteca que não estava no projeto), e um prompt padrão de reescrita versionado no repositório para o time inteiro usar igual. O que não vale automatizar é o merge — quem aprova continua sendo gente, porque é ali que o conhecimento tácito do sistema é conferido.
Recomendação prática: escolha um módulo pequeno e isolado desta semana, escreva os testes de caracterização com ajuda do agente, peça a reescrita com as restrições do checklist e meça o tempo total. Você vai descobrir que o gargalo nunca foi digitar o código novo — era provar que o velho funcionava como todos achavam que funcionava. Domine essa etapa e a IA vira o acelerador que a propaganda promete; pule ela e a IA vira o jeito mais rápido de quebrar produção.