Big migrations — Vue 2 to 3, React class components to hooks, JS to TS, Next.js Pages Router to App Router — used to take three weeks of mechanical work plus another week of bug hunting. Asking a model to “migrate this repo” in one shot produces a plausible-looking codebase that does not run. This tutorial gives engineers a structured prompt workflow that pairs AI’s mechanical speed with your code-review judgment, cutting a real migration from three weeks to about three days while keeping test pass rates green.
What this tutorial solves
Big migrations done by AI in one shot produce a plausible-looking codebase that does not run. The structure below cuts the work into validated chunks: one reference file by hand, then pattern propagation, then a codemod for the long tail, then a final guide-checklist review. Each chunk has a clear pass/fail; failures stop at one file, not the whole repo.
Who this is for
Developers facing a multi-week migration who want AI to do the heavy mechanical work without producing garbage. Most useful on codebases of 50-1000 files where hand-migrating is too slow and pure codemods miss the judgment cases. Tech leads scoping migration budgets also benefit — this workflow makes estimates real.
When to reach for it
A migration with a clear official upgrade path (Vue, React, Next.js, Angular, Svelte) and where multiple files share the same migration pattern. Also good for typed-language migrations (JS to TS, Python 2 to 3 — for which official codemods exist but still need judgment cleanup). Trigger: when you can name three files and they would all change in the same way.
When this is NOT the right tool
Migrations between fundamentally different paradigms (jQuery to React, REST to GraphQL) where AI cannot mechanically translate. Use AI as a learning aid only — the architecture decisions are yours. Also skip if your codebase has no test coverage; you cannot validate any migration step.
Before you start
- Confirm test coverage above 50%. Without tests, every migration step is a faith move. If coverage is low, write characterization tests on the most-touched files first.
- Pin the version range. “Vue 2.7 to Vue 3.4” is different from “Vue 2.0 to Vue 3.4.” The model needs to know the exact starting point.
- Read the official migration guide once, end to end. AI can summarize it, but you should be able to call out a wrong summary.
- Set up a clean branch with no other refactors in flight. Mixing the migration with unrelated changes kills your ability to bisect.
Step by step
- First chat: ask the model to summarize the official migration guide for your version pair. List the 5-10 most common mechanical changes. Include the source URL in the prompt so the model stays grounded in the official path, not folklore.
- Second chat: pick one file. A medium-complexity file from the middle of the codebase, not the simplest. Prompt:
Apply migration changes 1-5 to this file. Output:
1. The full migrated file
2. A diff against the original
3. A list of any judgment calls you made
Do not refactor unrelated code. Do not rename variables that
do not need renaming. Do not "improve" the file.- Review the diff line by line. Run tests on this file only. Fix issues yourself or with one more focused prompt. This file is now your reference implementation. Commit it.
- Third chat: “Here is the reference migration of File A (paste). Apply the same pattern to File B (paste). Match the style of File A’s migration exactly.”
- Repeat for 5-10 files manually with AI assistance. By the third file you understand the patterns; by the seventh you can spot a wrong AI suggestion in five seconds. Commit each file individually so bisecting works.
- For the long tail (40-200 trivial cases), write a codemod with AI help. jscodeshift, ts-morph, or AST-grep are the right tools. Dry-run on a sample, eyeball the diff, then apply. Tests must pass after each codemod batch.
- Final pass: AI reviews the whole migration against the official guide checklist. Prompt: “Review this branch for any of these official migration items that I missed: [paste checklist].”
First-run exercise
- Pick the smallest non-trivial migration in your roadmap — maybe a single feature folder, 10-20 files. Real stakes, contained blast radius.
- Run the full workflow once: official guide summary, reference file, propagation, codemod, final review. Measure each phase.
- Save the reference-file diff and the codemod script. These become templates for the next migration of the same kind.
- For the next batch, change only one variable: a different model, or attempting more files per AI propagation prompt.
Quality check
- Tests pass after every commit. If a commit has 5 file changes, isolate which file broke before moving on.
- The reference file’s diff is reviewable in under 10 minutes. If not, the model added too much; rewrite the prompt to forbid unrelated changes.
- The codemod’s dry-run diff is reviewable in under 30 minutes. If not, the codemod is too aggressive.
- Final-pass review surfaces fewer than 5 missed items. More than 5 means propagation broke silently somewhere — back up and find the divergence.
How to reuse this workflow
- Save the migration-guide-summary prompt, the reference-file prompt, and the propagation prompt as a project doc. New migration, paste the new guide URL.
- Maintain a MIGRATION-LOG.md (file, status, notes, blockers). When life interrupts the migration for a week, this is what lets you restart.
- Build an internal codemod library. Same patterns recur across projects (class to hooks, prop renames, default imports to named) — write each once, reuse forever.
Recommended workflow
Official guide summary → 1 reference file by hand with AI → 8 files using the reference pattern → codemod for 40 trivial cases (jscodeshift / ts-morph / AST-grep, dry-run first) → final guide-checklist review → release tag. 3 days versus 3 weeks for a React class-to-hooks migration of about 50 components.
Common mistakes
- One-shot migrating the whole codebase. Untestable wall of changes that you cannot bisect.
- Not writing a reference implementation first. Each file ends up styled differently and reviewers reject the PR.
- Trusting AI codemods without dry-run and review. They edit unrelated code more often than you think.
- Skipping tests between files. Errors compound silently across the migration.
- Mixing the migration with feature work. Now you cannot tell which commit broke production.
- Using the wrong model. Models trained before the framework’s migration guide existed will give outdated advice.
Advanced tips
- Pin the migration guide URL in every prompt — keeps AI grounded in the official path, not 2-year-old blog posts.
- For mass-rename refactors (useEffect args, prop names, deprecated lifecycle hooks), grep plus scripted edits beat AI for accuracy.
- Keep a MIGRATION-LOG.md with each file, status, and notes. Resumable when life interrupts.
- For team migrations, run the reference file through the team’s normal code review before propagating. Disagreements caught at file 1 save 50 review comments at file 30.
- Set a “no judgment” rule for the codemod phase. If the codemod cannot mechanically decide, leave a TODO and review by hand.
Output checklist
- Reference implementation file done and tests pass.
- Each subsequent file matches the reference pattern.
- Codemod (if any) dry-run reviewed before applying.
- Tests pass at every commit, not just at the end.
- Final review confirms guide checklist items addressed.
- MIGRATION-LOG.md committed so a teammate could finish if you stopped today.
FAQ
- Use codemods or AI per-file?: Codemod for mechanical bulk; AI per-file for the parts requiring judgment.
- How long does a real migration take?: Depends on size — but AI cuts the mechanical 70% in half, while the judgment 30% still takes the same time.
- What model is best for migration work?: Any frontier model with a long context window. Migrations benefit from feeding the reference file plus the target file in one prompt.
- Should I migrate tests at the same time?: Migrate tests in lockstep with their files. Diverging tests and source is how migrations stall.
- What if the official guide is incomplete?: Search the framework’s GitHub issues for the migration tag. Real-world edge cases live in issues, not the guide.
- How do I review 50 AI-migrated files?: Group by pattern. Files that share the migration pattern can be reviewed as a batch by reading two and skimming the rest.
Related
- AI refactor workflow
- AI dependency upgrade workflow
- Multi-agent coding workflow
- AI monorepo coding workflow
Tags: #AI coding #Tutorial #Workflow