Todo time tem aquele módulo que ninguém quer tocar: escrito há anos, sem testes, com regras de negócio que só uma pessoa entende — quando essa pessoa ainda está na empresa. É exatamente aí que a IA mais ajuda, desde que usada com método.
1. Mapear antes de mexer
Peça ao agente de código um mapa do módulo: pontos de entrada, dependências, tabelas que lê e escreve, jobs e integrações externas. Agentes que navegam pelo repositório (como Claude Code, Cursor ou Codex) conseguem seguir chamadas entre arquivos — algo que um chat sem acesso ao código não faz.
- Quais são as entradas (rotas, comandos, filas) desse módulo?
- Quais tabelas ele altera e em que ordem?
- Quais integrações externas ele chama e o que acontece se falharem?
2. Extrair as regras de negócio
Com o mapa em mãos, peça a explicação das regras em linguagem de negócio, com a referência do arquivo e da linha de cada uma. Exigir a referência é o que separa uma explicação verificável de um resumo inventado. Valide com quem conhece o domínio — fiscal, financeiro, estoque — antes de registrar.
3. Proteger com testes de caracterização
Testes de caracterização registram o comportamento atual, certo ou errado, para que qualquer mudança que o altere seja percebida. A IA acelera muito essa etapa: gera os casos a partir das regras extraídas e dos dados reais anonimizados. Só depois de ter essa rede de proteção vale refatorar.
4. Documentar onde o time vai ler
Documentação boa fica perto do código: um README por módulo, registros de decisão e as regras do projeto para os agentes (AGENTS.md). Assim, o próximo dev — ou o próximo agente — já começa com contexto, e o conhecimento deixa de depender de uma pessoa só.
5. Refatorar em passos pequenos
Com mapa, regras, testes e documentação, a refatoração vira uma sequência de mudanças pequenas e verificáveis. Cada passo roda os testes; cada pull request passa por revisão (com IA e humana). É assim que se evolui um sistema com anos de produção sem parar a operação.
Cuidados
- Nunca envie dados reais de clientes para o modelo: use dados anonimizados.
- Mantenha segredos fora do repositório e do contexto da IA.
- Desconfie de explicações sem referência ao código.
- Trate a saída da IA como rascunho até ser validada por quem conhece o domínio.