Legacy Migration with AI
AI can accelerate legacy migrations — framework upgrades, language ports, test backfill — when you constrain scope and verify every slice. Ungated agents rewrite entire repos.
Last reviewed: June 2026
Migration tooling varies by stack. Patterns apply across Cursor, Claude Code, and Amazon Q transformations.
Principles
| Principle | Why |
|---|---|
| Incremental slices | One module or route per PR |
| Characterization tests first | Lock current behavior before refactor |
| Explicit forbidden paths | Migrations, prod configs, secrets |
| Human owns architecture | Agent implements approved plan |
| Verify continuously | CI after every slice |
Workflow
- Inventory — list modules, dependencies, test coverage gaps (human + search)
- Spec — Spec-Driven Development per slice with allowed files
- Tests — add characterization tests for behavior you're about to change
- Migrate — agent implements one slice; run full test suite
- Review — AI Code Review + human CODEOWNER
- Repeat — next slice; never "finish the migration" in one prompt
Prompt template
Migration slice 3 of 12 — do not touch other modules.
Goal: Convert src/legacy/billing.js to TypeScript strict.
Allowed: src/legacy/billing.js → src/billing/index.ts, src/billing/index.test.ts
Forbidden: src/legacy/payments.js, database/**, config/**
Steps:
1. Add tests capturing current billing.js behavior
2. Port to TypeScript with same public API
3. Run npm test -- billing
Do not refactor unrelated code.
Stack-specific tools
| Stack | Tool / pattern |
|---|---|
| Java → modern Java | Amazon Q transformations; JetBrains inspections |
| .NET Framework → .NET | Microsoft migration analyzers + scoped agent |
| jQuery → React | Component-by-component; keep old until parity |
| Pages → App Router | Route-by-route; Project Rules for conventions |
Anti-patterns
| Anti-pattern | Result |
|---|---|
| "Migrate entire repo to TypeScript" | Unreviewable mega-PR |
| No tests before port | Silent behavior change |
| Agent edits lockfiles freely | Dependency chaos |
| Skip security review on auth paths | Production vulnerability |