🗺️ Mapeie dependências e faça o inventário
A IA pode mapear dependências, explicar código, documentar interfaces e encontrar código morto — ler muito código e resumir estrutura é onde ela mais rende. Comece por aí: saber o tamanho real do problema antes de propor solução.
Como ler: o processo inteiro em uma imagem. As caixas em ciano são as etapas de evidência — caracterizar, rodar em paralelo, comparar. São elas que transformam "acho que está igual" em prova, e por isso nenhuma delas é opcional.
🆕 Novo aqui?
Legado aqui não significa "velho": significa código em produção que ninguém entende por inteiro e que não tem testes suficientes para ser mudado com segurança. Teste de caracterização é um teste que descreve o que o sistema faz hoje (não o que deveria fazer). Adaptador é uma camada fina que traduz entre o mundo antigo e o novo.
Inventário
Antes do plano
Código morto
Corte mais barato
Quem chama quem
Define a fronteira
Risco
Diminui, não aumenta
🔎 Identifique as regras de negócio escondidas
Todo sistema antigo carrega regras que nunca foram escritas em lugar nenhum: exceções históricas, casos especiais de clientes grandes, arredondamentos com motivo fiscal, prazos herdados de um contrato de 2014. São elas que quebram na reescrita.
⚠️ Riscos típicos do legado
🧪 Exercício copiável — extrair as regras do código
Objetivo: transformar código legado em uma lista de regras auditável. Escolha um módulo que você precisa modernizar.
Leia <caminho do módulo legado> inteiro. Não altere nada. Produza uma tabela de REGRAS DE NEGÓCIO observadas no código, com colunas: regra (em português, uma frase) | onde está (arquivo:linha) | condição que a dispara | o que acontece quando não vale | parece intencional ou acidental? Regras: - descreva o que o código FAZ, não o que deveria fazer; - inclua casos especiais, exceções, valores mágicos e datas fixas; - não invente justificativa de negócio — se não souber, escreva "desconhecido"; - ao final, liste em "PERGUNTAR AO NEGÓCIO" as regras que parecem acidentais ou que você não consegue explicar.
Como verificar: leve a lista "PERGUNTAR AO NEGÓCIO" para quem opera o sistema. Toda regra que alguém reconhecer vira teste de caracterização no próximo tópico; toda regra que ninguém reconhecer é candidata a remoção — mas só depois de confirmada.
Código = verdade
Doc é intenção antiga
Valor mágico
Costuma ser regra
Regulatório
Não se "simplifica"
Perguntar
Antes de remover
🧪 Escreva testes de caracterização
Teste de caracterização registra o comportamento atual — inclusive o que parece errado. Ele não julga; ele fotografa. É a rede de segurança que torna a modernização possível.
✓ Caracterização bem feita
- ✓Registra a saída atual, mesmo a esquisita, com um comentário "comportamento atual, não validado"
- ✓Cobre entradas reais colhidas de produção (anonimizadas)
- ✓Inclui bordas: nulo, vazio, negativo, data limite, valor máximo
- ✓Roda contra o sistema antigo antes de qualquer mudança
✗ Armadilhas
- ✗"Corrigir" o comportamento estranho enquanto escreve o teste
- ✗Testar só o caminho feliz — o legado vive nos casos especiais
- ✗Escrever a expectativa a partir da documentação, não da execução
- ✗Usar dado de produção sem anonimizar
💡 Dica prática
Gerar caracterização em volume é uma das melhores aplicações de IA que existem: peça ao agente para produzir dezenas de casos a partir de entradas reais, rodá-los contra o sistema atual e gravar a saída como expectativa. Você revisa a lista, não escreve os testes um a um.
Fotografa
Não julga
Bug incluso
Também é comportamento
Entrada real
Anonimizada
Volume
Onde a IA brilha
🕵️ Descubra integrações ocultas
O maior gerador de incidente pós-migração é simples: você desligou algo que "ninguém usava" — e alguém usava. Um script, uma planilha, um relatório que lê o banco direto, um job de outro time.
Olhe os acessos, não o código
Logs de API, conexões ao banco, chamadas ao endpoint, leituras do arquivo. Quem consome aparece no tráfego, não no repositório.
Observe por um ciclo completo
Uma semana não basta se existe fechamento mensal, relatório trimestral ou rotina anual. O consumidor mais perigoso é o que só aparece no dia 1º.
Desligue em etapas
Avisar → depreciar (com alerta a cada uso) → degradar → remover. Cada etapa dá chance de alguém aparecer dizendo "isso é meu".
Tráfego
Revela consumidor
Ciclo completo
Mensal, trimestral, anual
Depreciar
Antes de remover
Silêncio
Não prova desuso
🧱 Isole fronteiras e crie adaptadores
Antes de trocar qualquer coisa, crie o ponto de costura: uma interface entre quem consome e a implementação. Com o adaptador no lugar, você troca o motor sem tocar em quem dirige — e pode voltar atrás com uma linha.
📐 Como escolher a fronteira certa
- •Poucos consumidores (você consegue avisar todos).
- •Contrato estreito: poucas operações, dados simples.
- •Comportamento já coberto por testes de caracterização.
- •Valor claro em migrar primeiro (dor conhecida, não só "é feio").
⚠️ Atenção
Sem fronteira definida, a migração vira reescrita: cada pedaço puxa outro, o escopo estoura e o projeto entra naquele estado em que o sistema novo não está pronto e o antigo já não recebe manutenção. Esse é o pior lugar possível.
Costura
Antes da troca
Contrato estreito
Facilita a troca
Estrangulamento
Pedaço a pedaço
Volta fácil
Troca a implementação
⚖️ Rode em paralelo e compare
As duas implementações recebem a mesma entrada; a antiga continua respondendo; a nova só registra o que responderia. Cada divergência vira um caso para investigar. É a prova mais forte que existe.
Painel de comparação (recriação ilustrativa, não é screenshot real)
requisições comparadas .......... 148.302
idênticas ...................... 148.061 (99,84%)
divergentes .................... 241
├─ arredondamento centavo ..... 233 <- regra fiscal esquecida
├─ cliente com contrato 2014 ... 7 <- exceção histórica
└─ data 29/02 ................. 1 <- ano bissexto
nenhuma resposta ao cliente foi alterada (modo sombra)
Como ler: 99,84% de igualdade não é aprovação — as 241 divergências são o conteúdo real do relatório. Cada uma delas é uma regra que a caracterização não pegou. É por isso que se roda em sombra antes de trocar.
Checagem rápida: você vai modernizar um módulo antigo sem testes. Qual é o primeiro passo?
Modo sombra
Novo só observa
Divergência
É informação valiosa
Gradual
1%, 10%, 50%, 100%
Volta
Disponível até o fim
📌 Resumo do Módulo
Próximo Módulo:
4.2 - Arquitetura legível para agentes: estrutura previsível, AGENTS.md e fontes únicas de verdade.