Migração de Código Legado com IA — Guia Prático

Como usar IA para migrar, modernizar e refatorar código legado. Estratégias incrementais, testes de segurança e como evitar regressões.

Migrar código legado é a tarefa onde IA gera mais valor — e mais risco. O código legado geralmente não tem testes, tem dependências antigas, e ninguém lembra como funciona. A IA pode acelerar a migração 10x, mas sem estratégia, pode criar 10x mais bugs.

Os 4 tipos de migração

Tipo	Exemplo	Risco	Valor da IA
Linguagem	JavaScript → TypeScript	Alto	Muito alto
Framework	Express → Fastify	Médio	Alto
Versão	Node 16 → Node 22	Baixo	Médio
Arquitetura	Monolito → Microservices	Muito alto	Alto

Estratégia: o "Strangler Fig"

Nunca reescreva tudo de uma vez. Use o padrão Strangler Fig — substitua peça por peça, mantendo o sistema funcionando.

Antes:          Durante:              Depois:
┌─────────┐    ┌─────────┬────────┐   ┌───────────┐
│  Legacy  │ →  │ Legacy  │  New   │ → │   New     │
│  (100%)  │    │  (70%)  │ (30%)  │   │  (100%)   │
└─────────┘    └─────────┴────────┘   └───────────┘

Passo a passo

Mapear dependências — a IA lê o código legado e gera mapa de dependências
Criar testes de aceitação — testes que validam comportamento atual (antes de mudar)
Migrar um módulo — a IA migra + gera testes unitários
Validar — rodar testes de aceitação + testes unitários
Deploy — deploy do módulo migrado
Repetir — próximo módulo

Prompt para mapear dependências

Analyze the codebase in src/legacy/ and generate:

1. A dependency graph (which files import which)
2. A list of external dependencies (npm packages, APIs, databases)
3. A risk assessment for each module (high/medium/low)
4. Suggested migration order (start with lowest risk, highest isolation)

Output: docs/migration-plan.md

Prompt para gerar testes de aceitação

Read src/legacy/api/users.js and generate acceptance tests that
capture the CURRENT behavior (not the ideal behavior).

Requirements:
- Test all public functions
- Test edge cases: empty input, null, invalid types
- Use descriptive names: "currently returns 200 even with invalid email"
- These tests will be the baseline — if they pass after migration, behavior is preserved

Output: src/__tests__/legacy/users-acceptance.test.ts

Prompt para migrar módulo

Migrate src/legacy/api/users.js to TypeScript.

Context:
- Target: src/api/users.ts
- Stack: TypeScript, Express, Prisma
- Acceptance tests: src/__tests__/legacy/users-acceptance.test.ts

Process:
1. Read the legacy file and acceptance tests
2. Create the new TypeScript file
3. Write unit tests for the new implementation
4. Run BOTH acceptance tests and unit tests
5. If any test fails, fix until all pass
6. Do NOT change behavior — only type safety and code quality

Constraints:
- Same function signatures (or document changes)
- Same error codes and response formats
- Same database queries (convert to Prisma syntax)

Erros comuns em migração

Erro	Consequência	Correção
Reescrever tudo de uma vez	Sistema para de funcionar	Strangler Fig — módulo por módulo
Sem testes de aceitação	Comportamento muda sem perceber	Gerar testes ANTES de migrar
Migrar sem mapear dependências	Quebra imports em cascata	Mapear primeiro, migrar depois
Mudar comportamento durante migração	Bugs + regressão	Migrar = mesmo comportamento, novo código
Não versionar migrações	Rollback impossível	Git branch por módulo