Código legado com IA: como documentar e migrar com segurança

Código legado com IA: como documentar e migrar com segurança

Para usar IA em código legado com segurança, siga quatro etapas: mapear o sistema, documentar o que ele realmente faz, escrever testes de caracterização que congelam o comportamento atual e migrar por partes pequenas. A IA acelera a leitura e o rascunho, mas cada saída precisa passar por uma verificação executável, como um teste ou uma comparação de resultados, antes de virar decisão.

Principais pontos

• A IA lê e resume código rápido, mas não sabe o que o negócio espera. Quem valida o comportamento é a equipe, com testes e com quem usa o sistema.
• Documente primeiro, migre depois. Uma documentação revisada serve de contrato para a migração.
• Testes de caracterização registram o que o sistema faz hoje, inclusive o que parece erro, e protegem cada passo da mudança.
• Migre por partes com ponto de retorno claro: uma fatia, um critério de aceite, um plano de reversão.
• Limite o que a IA enxerga e o que ela pode executar. Código legado costuma conter segredos, dados pessoais e regras que ninguém lembra por quê existem.

Por que código legado pede um cuidado diferente com IA?

Em um projeto novo, o código costuma ser pequeno, recente e coberto por testes. No legado, acontece o contrário: o conhecimento está espalhado entre o código, o banco de dados, planilhas, rotinas agendadas e a memória de poucas pessoas. Um modelo de linguagem consegue ler o arquivo, mas não consegue ler o contexto que não está nele.

Isso gera um risco específico. A IA produz explicações fluentes e plausíveis, mesmo quando erra. Em código antigo, uma explicação plausível e errada é pior do que nenhuma, porque vira documentação, depois vira requisito da migração e só aparece como defeito em produção.

Por isso o roteiro abaixo trata a IA como um assistente que propõe e a equipe como quem confirma. Cada etapa termina com uma verificação que não depende da opinião do modelo: um teste que passa, uma consulta que confere, uma pessoa de negócio que reconhece a regra.

Etapa 1: como mapear o sistema antes de pedir qualquer coisa à IA?

Mapear significa saber o que existe, o que depende de quê e o que é crítico. Sem isso, a IA recebe pedaços soltos e devolve respostas soltas. O mesmo princípio vale para qualquer automação, como descrevemos em mapeamento de processos antes de aplicar IA: primeiro o processo e a linha de base, depois a ferramenta.

Um mapa útil de sistema legado responde a estas perguntas:

• Quais são os módulos, serviços e rotinas agendadas, e quem é a pessoa responsável por cada um?
• Quais integrações externas existem (pagamento, nota fiscal, ERP, WhatsApp, e-mail) e como falham?
• Onde estão os dados, quais tabelas são centrais e quais campos guardam dados pessoais?
• Quais partes mudam com frequência e quais ninguém toca há muito tempo?
• O que, se parar, interrompe a operação no mesmo dia?

A IA ajuda aqui de forma modesta e verificável. Ela pode listar dependências importadas, gerar um inventário de pontos de entrada (rotas, comandos, jobs), resumir a estrutura de pastas e apontar trechos que chamam sistemas externos. Cada item do inventário deve ser conferido por busca no código ou por execução, não aceito por confiança.

O resultado desta etapa é um inventário curto e uma classificação de risco por módulo. Ele também define a ordem do trabalho: comece por partes que são importantes o bastante para valer o esforço, mas isoladas o bastante para falhar sem derrubar tudo.

Etapa 2: como documentar com IA sem registrar fantasia?

Documentar com IA funciona bem quando o pedido é estreito e a evidência é citada. Pedir que o modelo explique o sistema inteiro gera texto genérico. Pedir que explique uma função específica, apontando as linhas que sustentam cada afirmação, gera algo que se pode conferir.

Um método simples, módulo a módulo:

• Entregue à IA apenas o módulo e suas dependências diretas, não o repositório inteiro. Contexto enxuto e relevante tende a render respostas melhores, como discute a Anthropic em seu material sobre engenharia de contexto para agentes.
• Peça três coisas separadas: o que o código faz, as regras de negócio que ele implementa e os pontos em que ela está em dúvida.
• Exija referência a arquivo e linha em cada afirmação. Afirmação sem referência é descartada.
• Marque cada trecho do documento como confirmado, hipótese ou desconhecido.
• Leve as hipóteses a quem opera o processo. A pergunta é concreta: quando o pedido tem este status, o sistema faz isto, é isso mesmo que vocês esperam?

A separação entre confirmado, hipótese e desconhecido é a parte mais importante. Ela impede que um palpite do modelo seja lido, meses depois, como regra oficial. Também mostra onde a empresa depende de conhecimento que só existe na cabeça de alguém, o que já é um achado valioso.

Se a equipe usa uma ferramenta de código com agente, vale registrar convenções e comandos de verificação do repositório em um arquivo de instruções. Explicamos como fazer isso em como escrever um bom CLAUDE.md. A documentação gerada deve ficar no próprio repositório, versionada, para ser revisada como qualquer outra mudança.

Etapa 3: o que são testes de caracterização e como a IA ajuda?

Teste de caracterização é um teste que registra o que o código faz hoje, sem julgar se está certo. Você chama a função com entradas variadas, anota as saídas reais e transforma isso em teste. Se uma mudança futura alterar uma saída, o teste falha e você decide se a diferença é uma melhoria desejada ou uma quebra.

É a rede de proteção da migração. Sem ela, qualquer reescrita depende de fé. Com ela, a pergunta passa a ser objetiva: o novo código se comporta como o antigo nos casos que importam?

A IA é útil para gerar variações de entrada e rascunhar os testes, principalmente nos casos de borda que a equipe esqueceria: campos vazios, datas limite, valores negativos, caracteres acentuados, arredondamentos. O cuidado é este: o teste gerado deve ser executado contra o código atual, e a saída esperada deve vir da execução real, nunca da suposição do modelo. Se o modelo escreve a expectativa de cabeça, você testa a imaginação dele, não o sistema.

Um passo a passo prático:

• Escolha a fatia a ser migrada e liste suas entradas e saídas observáveis (retorno de função, registros gravados, mensagens enviadas, arquivos gerados).
• Peça à IA um conjunto de entradas variadas, incluindo casos de borda e casos reais anonimizados.
• Execute essas entradas no sistema atual e grave as saídas como resultado esperado.
• Revise com quem conhece o negócio os resultados que parecem estranhos. Alguns são defeitos antigos, outros são regras escondidas.
• Decida caso a caso se o defeito será preservado na migração ou corrigido de forma explícita, com registro.

Para medir se o conjunto de testes está confiável, a ideia de avaliação contínua descrita nos guias da Anthropic e da OpenAI sobre evals se aplica bem: casos fixos, repetíveis, com resultado verificável. Quando o próprio uso da IA faz parte do fluxo, o texto sobre como medir um piloto de automação com IA ajuda a definir métricas e critérios de decisão.

Etapa 4: como migrar por partes sem parar a operação?

Migrar tudo de uma vez é a forma mais cara de descobrir o que você não sabia. A alternativa é cortar o sistema em fatias e substituir uma por vez, mantendo o antigo e o novo convivendo até a confiança ser suficiente.

O roteiro por fatia:

• Defina a fronteira da fatia: o que entra, o que sai, quem chama.
• Garanta que os testes de caracterização da fatia passam no código antigo.
• Peça à IA o rascunho da versão nova, em pequenos trechos, com o documento da etapa 2 e os testes como referência.
• Rode os mesmos testes no código novo. Toda diferença é investigada, não ajustada às pressas.
• Coloque o novo código em operação paralela ou sombra, comparando resultados com o antigo sem afetar o usuário.
• Libere gradualmente, com um interruptor para voltar ao código antigo.
• Só desligue o antigo depois de um período combinado sem divergências relevantes.

A IA entra como redatora de rascunho e revisora, não como autora final. Peça que ela explique o que mudou entre a versão antiga e a nova e que liste riscos. Depois confirme os riscos com os testes. Se o modelo disser que o comportamento é equivalente, a resposta correta é rodar a comparação, não aceitar a frase.

Também separe migração de melhoria. Reescrever na nova linguagem e mudar regras de negócio no mesmo passo mistura causas e torna qualquer diferença impossível de diagnosticar. Primeiro preserve o comportamento, depois evolua.

Como fica na prática? Um cenário ilustrativo

Cenário ilustrativo: uma distribuidora tem um módulo antigo que calcula frete e prazo de entrega. Ele foi escrito há muitos anos, não tem testes e só uma pessoa da logística sabe explicar algumas exceções. A empresa quer migrá-lo para um serviço novo.

Na etapa de mapeamento, a equipe descobre que o módulo é chamado pelo pedido online, pelo atendimento no WhatsApp e por uma planilha de cotação. Na documentação, a IA descreve a regra principal e sinaliza uma dúvida: por que certos CEPs têm um acréscimo fixo? A pessoa da logística explica que é uma região atendida por transportadora específica. A regra vira texto confirmado.

Nos testes de caracterização, a IA gera entradas variadas e a equipe executa tudo no módulo antigo, gravando as saídas. Um resultado chama atenção: pedidos com peso exatamente no limite de uma faixa pagam a faixa superior. A logística confirma que é intencional. O teste fica, com um comentário explicando.

Na migração, a primeira fatia é só o cálculo de prazo. O serviço novo roda em sombra, comparando respostas com o antigo. As divergências são investigadas uma a uma. Só depois a fatia é liberada, com interruptor de retorno, e o frete fica para a rodada seguinte.

Nenhuma etapa dependeu de acreditar na IA. Todas terminaram em um teste, em uma comparação ou em uma confirmação de quem conhece o processo.

Que limites e controles definir antes de começar?

Código legado costuma carregar três problemas de segurança: segredos embutidos no código, dados pessoais em arquivos de exemplo ou logs e dependências antigas com falhas conhecidas. Antes de apontar uma ferramenta de IA para o repositório, defina o que ela pode ler, o que pode executar e para onde os dados vão.

• Retire ou mascare segredos antes de compartilhar qualquer trecho com um modelo e troque os que já estiveram expostos.
• Nunca use dados reais de clientes em prompts ou testes. Anonimize ou gere dados sintéticos. A LGPD aplicada a projetos de IA exige atenção a finalidade, minimização e a quem o fornecedor do modelo trata como operador.
• Dê à ferramenta de código permissões mínimas: leitura por padrão, execução em ambiente isolado, sem acesso ao banco de produção. Veja segurança no Claude Code: permissões, sandbox e segredos.
• Trate conteúdo do repositório como entrada não confiável. Comentários e arquivos podem conter instruções que tentam desviar o agente, risco catalogado pelo OWASP no material sobre aplicações com LLM.
• Exija revisão humana em todo código que a IA propõe, com os testes rodando antes da aprovação.

O método que aplicamos em projetos de IA segue a mesma lógica: mapear o processo atual e a linha de base, limitar dados e ações, pilotar uma fatia real com registros e um critério de sucesso combinado, e transferir com decisão explícita de expandir, ajustar ou parar. Em código legado, a fatia piloto é um módulo pequeno e relevante, e a decisão de continuar se baseia nos testes e nas divergências observadas, não na impressão de que a IA ajudou.

Perguntas frequentes

A IA pode migrar um sistema legado inteiro sozinha? Não é recomendável. Ela é boa para rascunhar trechos, explicar código e gerar casos de teste, mas não conhece regras que só existem fora do código. A migração segura depende de testes de caracterização, revisão humana e liberação gradual.

Por onde começar a documentar um sistema sem nenhuma documentação? Comece pelo módulo mais crítico que seja razoavelmente isolado. Peça à IA uma descrição com referência a arquivo e linha, marque cada afirmação como confirmada, hipótese ou desconhecida e valide as hipóteses com quem opera o processo. Guarde o resultado no repositório.

É seguro enviar código legado para uma ferramenta de IA? Depende do que o código contém e do contrato com o fornecedor. Remova segredos e dados pessoais, defina quais repositórios podem ser compartilhados e confirme as condições de tratamento de dados. Em caso de dúvida sobre dados pessoais, consulte a orientação da ANPD e o jurídico da empresa.

Como saber se a migração mudou o comportamento do sistema? Compare o novo código com o antigo usando os mesmos testes de caracterização e, quando possível, rode os dois em paralelo com dados reais anonimizados. Toda divergência precisa ser classificada como melhoria intencional ou quebra e registrada. Sem essa comparação, equivalência é só uma opinião.

Fontes

• Anthropic: Effective context engineering for AI agents
• Anthropic: Demystifying evals for AI agents
• OWASP Top 10 for LLM Applications
• ANPD: Autoridade Nacional de Proteção de Dados