When to use it
You have legacy (an old framework, a dead language version, a monolithic blob) and you need to upgrade or move it without taking prod down and without rewriting everything from scratch at once. Unlike ordinary refactoring (improve the code without changing behavior), the job here is bigger: change the technology or version step by step, safely. The AI's role is legacy migration engineer. Output: an incremental migration plan with a rollback at every step.
The prompt (copy and paste)
You are a legacy migration engineer. Build me a safe migration plan. Assessment first, then steps.
WHAT WE'RE MIGRATING: "<PASTE: from what to what — framework/version/architecture>"
CODE/CONTEXT: <paste the key files or describe the system, its size, load, whether tests exist>
CONSTRAINTS: <no downtime allowed / a downtime window of X / a team of Y>
Give me:
1. An "as is" assessment: the main legacy risks, coupling, what's fragile, whether there's a safety net of tests.
2. Strategy: all at once or incremental (strangler fig — build the new alongside and retire the old piece by piece). Justify the choice.
3. A step-by-step plan: every step SMALL, independently deployable, with a working system after it. No big bang.
4. For each step: what changes, how we verify it, how we roll back if it breaks.
5. The safety net: which tests/characteristics to lock in BEFORE the migration so regressions get caught.
6. Priority order: what moves first (risk x value), what can wait until last.
Before irreversible steps (DB schema, deleting the old code) explicitly call out a backup/branch/flag. Mark assumptions with [assumption].
The technique: strangler fig (build the new around the old and retire legacy piece by piece) plus "every step deploys and rolls back" removes the main migration risk — "we rewrote everything and nothing works".
Filled-in example
Migrating: from AngularJS (1.x) to React, a monolithic frontend. Context: ~40 screens, almost no tests, live production. Constraint: no long downtime.
Expected AI response: assessment — no tests is the main risk, start with e2e on the critical flows; strategy — strangler fig, React islands inside Angular via a wrapper, screen-by-screen migration; plan — first lock in e2e for "checkout" and "login", then move screens from simple to complex, each in its own deploy behind a feature flag; rollback — the flag brings the old screen back; the irreversible part (ripping out the Angular bootstrap) goes last, in its own branch after every screen has moved.
Variations
- Language/runtime version. "Python 2 → 3" or "Node 14 → LTS": focus on incompatibilities, phased builds and a compatibility layer.
- Database migration. "Move the schema with no downtime": expand-contract (add the new → dual-write → switch reads → drop the old).
- Automation help. "Which steps can be handed to a codemod or a coding agent, and which need a human decision" — what's automatable.
Pro tips
- The first step of any migration is NOT touching the legacy — it's covering it with tests. Without a safety net you won't know what you broke.
- Push "every step deploys on its own". A plan where "it all switches on at the end" is a rewrite wearing a migration costume — the most common failure mode.
- Before anything irreversible (DB schema, deleting old code), demand an explicit backup/branch/flag — migrations break data more quietly and more expensively than features do.