The reason your framework upgrade has been on the roadmap for three quarters is not that the changes are hard. Most of them are mechanical, and a codemod could do them. The reason is that nobody can tell whether the change broke anything.
That is the whole problem. Legacy code is not code that is old, it is code whose behaviour is not described anywhere except in the code itself. There is no specification, the person who wrote it left, the comments describe an earlier version, and the test suite covers the paths that were easy to test in 2019. So a migration is not a refactoring problem, it is an epistemology problem: you are being asked to change something whose current behaviour nobody can state.
AI tooling changes the economics of this substantially, and in a way that is worth being precise about. It does not make the change safer. It makes the mechanical part nearly free, which shifts the entire cost of the project onto verification and onto the residue, meaning the cases the automation could not handle. If you do not plan for those two things, cheap mechanical change makes your migration worse, because you now have a very large diff and the same inability to tell if it is correct.
So the order of operations is not what most teams try. Characterisation tests first, mechanical transform second, residue third, and the residue is where an experienced engineer earns their salary.
Key takeaways
- The test suite you do not have is the thing blocking the migration, not the migration itself. Generate characterisation tests before changing anything.
- Deterministic codemods and generated edits are complementary: use a codemod for anything expressible as a pattern, and a model only for what is not.
- The valuable output of an automated migration is the list of cases it could not handle. A tool that reports success without that list has made your job harder.
- Language ports produce code that runs and is not idiomatic. Budget the rewrite; the translation is the cheap half.
- Migrate in small reviewable increments with the old and new paths coexisting. A single large migration diff is unreviewable no matter who wrote it.
The test suite you do not have
Before any migration tool touches the code, you need a way to detect behaviour change. Not good tests, in the sense of tests that express intent. Characterisation tests, which pin down what the system currently does, bugs included.
This is the one job in software where generated tests asserting current behaviour are exactly right rather than exactly wrong. In normal development, a test that asserts whatever the implementation does is worthless, because it locks in the bug and it breaks on every harmless refactor. In a migration, that is the point: you want to know if anything changed, including the wrong things, because preserving a bug is usually safer than silently fixing it during an upgrade.
Three approaches, in increasing order of value and effort.
Generated unit tests from the implementation. A model reads the module and writes tests asserting what it currently returns. Fast, and works anywhere. The weakness is that it tests what the code does under the inputs the model imagined, which skew toward the obvious ones. Grade these by injecting faults and seeing which survive; the method is in AI test generation tools.
Recorded traffic. Capture real requests and responses from a running system and replay them against the changed version. Enormously more representative than anything generated, because production traffic contains the inputs nobody would think to write down: the malformed ones, the ancient client versions, the empty arrays. This is the single highest-value technique in legacy work and the most underused.
Differential execution. Run old and new side by side on the same inputs and diff the outputs. The gold standard, and only available when both can run at once, which is why the coexistence pattern below is worth the effort it costs.
Whichever you use, take a coverage measurement before you start and treat anything uncovered as unknown territory rather than as low risk. The uncovered code in a legacy system is disproportionately the weird code, because it was hard to test for the same reasons it is hard to change.
Needs first-hand data: Before migrating, measure line and branch coverage on the modules in scope, then generate characterisation tests and measure again. Inject ten deliberate faults into the covered code and record how many the generated suite catches. That catch rate, not the coverage number, is your actual safety margin.
Three kinds of legacy work, three different tools
These get lumped together and they are not the same problem.
Framework and library upgrades
A known source version, a known target version, and a documented set of breaking changes. This is the most tractable category and the one where deterministic tooling wins outright, because the transformations are rules and rules should be written once and run everywhere.
The right shape is a recipe or codemod library maintained by someone other than you, run across your repositories, with a report of what it changed and what it skipped. Generated edits belong only in the gaps, on the files where the rule did not apply and a human would have to think.
The trap is the upgrade that is mostly mechanical with a few semantic changes buried in it: a default that changed, an API that now returns null instead of throwing, a lifecycle hook that fires in a different order. Codemods cannot see those and neither can a model reading one file at a time. They are found by your characterisation tests or by your users.
Language and platform ports
Moving a service from one language to another, or off a platform whose runtime is end of life. Models are genuinely good at this in a narrow sense: they will produce target-language code that compiles and mostly works.
What they produce is a translation, not a rewrite. The output preserves the structure, idioms and mistakes of the source language, so you get Java written in Python syntax, or a Go service that handles errors the way the old C# code did. It runs. It is not code your team will enjoy owning, and the review is harder than reviewing new code because the reviewer has to hold both languages and the original intent simultaneously.
Budget for this explicitly. The translation is the fast part. Making the result idiomatic, and deciding which of the original oddities were load-bearing, is the actual project. Any plan that treats the port as the deliverable will ship something nobody maintains.
Untested code that must keep working
No version boundary at all, just a module everyone is afraid of. Here the AI work is entirely the test generation described above, plus using an agent to produce something that does not exist yet: an explanation. Pointing an exploration-capable agent at a module and asking it to trace the call paths and explain the branching produces a genuinely useful document, and unlike a generated migration it is cheap to verify because you can check its claims against the code.
That artifact is worth keeping. It belongs alongside the code, which is the argument in documentation generation tools and knowledge base tools for engineering teams.
Deterministic transforms versus generated edits
The strongest mental model for this category is a division of labour that most teams get backwards.
A deterministic transform parses the code into a syntax tree, matches a pattern, and rewrites it. Same input, same output, every time. It either matches or it does not, and when it does not match you get told. It cannot do anything its author did not anticipate, and it will never produce something surprising at three in the morning.
A generated edit puts the code in a prompt and takes back a modified version. It handles cases nobody anticipated, understands intent in a loose sense, and can follow a convention it inferred from a neighbouring file. It is also non-deterministic, unverifiable at scale, and will happily produce a plausible edit to a case it misunderstood.
The correct allocation is: everything expressible as a pattern goes to the deterministic tool, and the model handles what is left. Teams that invert this, running a model across three hundred files because it is easier than writing a codemod, end up reviewing three hundred non-deterministic diffs instead of one rule plus a residue list.
The multiplier is that a model is very good at writing the codemod. Describing a transformation in English and getting a working recipe or a GritQL pattern back collapses the main barrier to deterministic tooling, which was always that writing AST queries is unpleasant. That is the workflow worth building around: model writes the rule, deterministic engine applies the rule, model helps with the residue, human reviews the rule once instead of every application of it.
The coexistence pattern
Do not migrate a system in one change. Make the old and new paths run side by side, route a fraction of work to the new one, and compare. This gives you differential testing for free, makes rollback a configuration change, and turns an unreviewable diff into a sequence of small ones. Feature flag platforms are the mechanism, and database migration tools cover the equivalent pattern where state is involved and rollback is not free.
The residue: what always needs a human
Every automated migration leaves a set of cases the automation cannot decide. Naming them in advance turns a surprise into a plan.
Semantic changes that look syntactic. A method whose name survived but whose behaviour changed. No tool matching on structure will flag it, and a model reading the diff has no reason to suspect it. Only your characterisation tests find these.
Anything reflective or dynamically dispatched. String-built class names, dynamic imports, serialised type names in a database, configuration referring to code paths. AST tools cannot see these because they are not in the AST. This is the largest source of migration incidents in my experience and it is almost always found in production rather than in review.
Generated and vendored code. Migrating generated output rather than regenerating it is a mistake that survives silently until the next regeneration overwrites everything.
Tests that encoded the old behaviour deliberately. Some of your assertions exist because of a bug you decided to keep. A migration that fixes it breaks the test, and the person reviewing does not know that the test was right.
Performance characteristics. The migrated code is correct and does four times the database queries because the new ORM lazy-loads differently. No functional test catches this. Only load testing and production monitoring do, which is why a migration project needs APM coverage in place before the cutover rather than after the incident.
Claude Code

Claude Code is Anthropic’s agentic coding tool, running as a CLI, a desktop app for Mac and Windows, a web app, and VS Code and JetBrains extensions. For legacy work its relevant property is that it explores rather than retrieves: it greps, reads and follows imports on demand, so it finds the call site in the odd file that similarity search skips, and it shows you which files it read. On a migration, that trail is the difference between a reviewable change and a mystery.
Pros
- Exploration finds dynamically named and unusual references that pattern matching and embedding retrieval both miss
- Excellent at the two highest-value legacy tasks: writing characterisation tests for an unfamiliar module, and explaining what a module actually does before you touch it
- Writes codemods and recipes from an English description, which is the highest-leverage use of a model in this category
- The visible file-read trail makes a large migration diff auditable, because you can check what informed each decision
Cons
- Applying changes file by file across hundreds of files is slower and less reproducible than running one deterministic rule, so use it to write the rule rather than to be the rule
- Autonomy is bounded by your tests, and legacy code is defined by not having them, so the first phase of any project is unavoidably manual judgment
- No built-in multi-repository orchestration, so a migration spanning forty services needs something else driving it
Best for: Building the characterisation tests and the codemods that the rest of the migration runs on, and handling the residue afterwards.
Pricing: Included with consumer subscription tiers, or usage-based against the API where teams want per-seat control and spend reporting.
Cursor

Cursor is a VS Code fork with an agent built into the editor and an embedding index of your repository. For legacy work its strength is the review surface: migration diffs render inline in the editor, which is where you want to be when you are evaluating a change to code you do not fully understand. Its indexing also makes the orientation phase fast, when you are asking where things live rather than changing them.
Pros
- Inline diff review in the editor is the most comfortable surface for reviewing changes to unfamiliar code
- Indexing gives quick answers to “where is this concept handled” across a repository nobody on the team has fully read
- Familiar to teams already on VS Code, so the migration project does not also become a tooling project
Cons
- Embedding retrieval misses call sites that do not resemble the query, which is exactly the failure mode that turns a migration into an incident
- Index staleness during a large migration is a real problem, because the repository is changing under the index continuously
- Not designed for cross-repository work, so a migration spanning services is many separate efforts
Best for: Single-repository migrations where the reviewer wants to stay in the editor and the codebase is unfamiliar.
Pricing: Per seat and per month with usage limits, plus a business tier adding administrative and privacy controls.
Moderne
Moderne is the commercial platform built around running OpenRewrite recipes at organisational scale. It ingests your repositories, builds a serialised lossless syntax tree for each, and runs recipes across all of them at once, producing impact analysis before anything is committed. The distinctive capability is that it operates across hundreds of repositories rather than one, which is the actual shape of an enterprise framework upgrade.
Pros
- Multi-repository execution with an impact report before commit, so the migration is planned from data rather than from optimism
- The lossless tree preserves formatting and type information, which means the output diffs are clean rather than reformatted noise
- Recipes are deterministic and reviewable once, which is the correct economics for a change applied ten thousand times
- Strong on the enterprise JVM ecosystem where these migrations are largest and most painful
Cons
- Ingestion and build infrastructure is a real deployment, not a tool you try on a Tuesday afternoon
- Value concentrates in ecosystems with mature recipe coverage, and thins out quickly outside them
- Enterprise procurement and cost make it hard to justify for a single repository or a small team
Best for: Organisations running framework upgrades across dozens or hundreds of repositories, particularly on the JVM.
Pricing: Enterprise licensing, generally scaled by the size of the codebase estate under management.
Sourcegraph

Sourcegraph is a code intelligence platform, and its Batch Changes feature is what belongs in a migration plan: define a change, run it across every repository matching a search, and get back a set of pull requests you can track to completion as a single campaign. The precondition is the index, which is also the thing that makes the inventory phase of a migration possible at all.
Pros
- Search across every repository answers the question migrations start with, which is how many places this pattern actually appears
- Batch Changes turns a hundred repositories into one tracked campaign with visible completion status, rather than a spreadsheet
- The change itself can be any script or codemod, so it composes with deterministic tooling rather than replacing it
- Self-hosted deployment available, which matters when the index covers your entire source estate
Cons
- The platform is a substantial deployment and most of its cost is not the migration use case
- Batch Changes runs whatever you give it, so the correctness of the transformation is still entirely your problem
- Pull request sprawl across many repositories creates a review coordination problem that the tool tracks but does not solve
Best for: Organisations with many repositories that need inventory, execution and completion tracking as one workflow.
Pricing: Enterprise plans priced per user for the platform, with Batch Changes included in the higher tiers.
Grit
Grit is built around GritQL, a query language for matching and rewriting code structurally across languages. The value proposition is that expressing a transformation should not require learning a per-language AST API, and that patterns should be shareable. It sits between a hand-written codemod and a full migration platform.
Pros
- One pattern language across multiple languages, so a polyglot codebase does not need a different toolchain per stack
- Patterns are far more approachable than raw AST manipulation, which is the barrier that keeps teams from writing codemods at all
- Deterministic by construction, so a rule reviewed once is trustworthy across every file it touches
Cons
- Still a pattern language with a learning curve, and the awkward transformations are awkward to express in any syntax
- Coverage and depth vary by language, so verify your stack specifically rather than trusting the supported list
- Purely a transformation tool, so inventory, test generation and residue handling are all elsewhere
Best for: Teams who want deterministic, reviewable structural transforms across a polyglot codebase without writing AST code by hand.
Pricing: Open source core with commercial plans for hosted and team features.
Codemod
Codemod is a platform and registry for structural code transformations, with a CLI for running them and a shared library of published migrations for common framework upgrades. The idea is that the codemod for a popular framework’s major version should be written once by someone and then run by everyone, rather than reinvented in every company.
Pros
- A registry of existing migrations means a common upgrade may already be solved, which is the cheapest possible outcome
- CLI-first workflow drops into existing CI and scripts without adopting a platform
- Deterministic transforms with a review step, so the change is auditable before it lands
Cons
- Registry coverage is strongest for popular JavaScript and TypeScript ecosystem migrations and much thinner elsewhere
- A published codemod encodes someone else’s assumptions about your codebase, so it needs the same review as any dependency
- Handles only the mechanical portion, and the residue is still yours
Best for: JavaScript and TypeScript teams doing framework version upgrades where a published codemod may already exist.
Pricing: Open source CLI with paid platform tiers for teams and hosted execution.
OpenRewrite
OpenRewrite is the open source engine underneath a large part of enterprise migration tooling. It parses source into a lossless semantic tree that preserves formatting and type attribution, then applies recipes, which are composable transformations you can chain. Its recipe catalogue for JVM framework and library upgrades is the deepest in existence, and you can run it from your build tool without adopting any platform.
Pros
- Type-attributed parsing means recipes can reason about what a symbol actually resolves to, not just what it looks like
- Lossless formatting preservation, so diffs contain the change and nothing else, which is what makes a large migration reviewable
- A very large public recipe catalogue covering common JVM upgrades, usable directly from Maven or Gradle
- Recipes compose, so an upgrade is assembled from existing pieces rather than written from scratch
Cons
- Strongest by a wide margin on the JVM, with other language support markedly less mature
- Writing a new recipe is real work, and the parsing model takes time to understand
- Running across many repositories without a platform means you build the orchestration, the reporting and the tracking yourself
Best for: JVM teams doing framework or library upgrades who want deterministic, reviewable transforms driven from their own build.
Pricing: No vendor bill for the open source project itself. Commercial tooling built on top of it is licensed separately.
How to choose
Sequence the project, then pick tools per phase. Choosing one tool for the whole migration is the mistake that makes all the others possible.
Phase one, inventory. How many places, in how many repositories, and which ones are unusual. A search platform or an exploration-capable agent, depending on whether the scope is one repository or fifty.
Phase two, safety net. Characterisation tests, recorded traffic replay, or differential execution. Do not skip this to save a week; it is the week that decides whether the project ships or gets reverted.
Phase three, mechanical transform. Deterministic tooling, every time, for anything expressible as a rule. Use a model to write the rule.
Phase four, residue. An exploration-capable agent plus a human who understands the domain. Insist that the tooling from phase three produced an explicit list of what it skipped, because that list is the work plan.
Phase five, verification and rollout. Coexistence behind a flag, differential comparison, and monitoring in place before cutover rather than after.
One rule that overrides all of this: if a tool reports success and cannot tell you what it skipped, do not use it for migration work. Silent incompleteness converts a bounded task into an unbounded one, and it is the single most expensive failure mode in this category.
| Tool | Transform type | Scope | Strongest phase |
|---|---|---|---|
| Claude Code | Generated, exploratory | One repository | Safety net, rule writing, residue |
| Cursor | Generated, editor-based | One repository | Orientation and diff review |
| Moderne | Deterministic recipes | Whole estate | Mechanical transform at enterprise scale |
| Sourcegraph | Runs anything you supply | Many repositories | Inventory and campaign tracking |
| Grit | Deterministic, GritQL patterns | One to many repositories | Polyglot mechanical transform |
| Codemod | Deterministic, published codemods | One repository or a few | Common framework version upgrades |
| OpenRewrite | Deterministic recipes | One repository, build-driven | JVM mechanical transform |
Needs first-hand data: On a pilot module, run the mechanical transform, then have an experienced engineer complete the residue by hand and log the hours. The ratio of automated change to residue hours is the number that makes your migration estimate credible, and it is specific to your codebase.
Frequently asked questions
Can I just point an agent at the repository and ask it to do the upgrade?
On a small service, sometimes. On anything substantial, no, and the reason is not capability. It is that you get a large non-deterministic diff with no statement of what was skipped, applied to a codebase whose behaviour you could not verify beforehand. The failure is not that the tool is bad, it is that you cannot review the result.
Should generated characterisation tests be kept after the migration?
Keep the ones that assert behaviour you actually want, and delete the rest deliberately rather than by neglect. A characterisation suite left in place becomes a suite that fails on every legitimate change, and a team that routinely deletes failing tests has lost more than it gained.
How do I handle a port to a different language?
Translate in slices, not at once, and run both versions against the same traffic until you trust the new one. Expect the translated code to be unidiomatic and plan the cleanup as part of the project rather than as follow-up work that never happens. The most common failure is declaring victory at the compiles-and-passes stage.
What if the original developers are gone and there is no documentation?
Then the first deliverable is documentation, not a migration. Use an exploration-capable agent to trace the call paths and explain the branching, verify its claims against the code, and write down what you confirm. It is slower than starting the migration and it is the only order that works.
Related reading
- Best AI coding assistants — the five-task suite, where task five is a migration and the grading criterion is honesty about the residue.
- Best AI test generation tools — how to build the characterisation suite this whole process depends on.
- Best AI coding agents — the agents that handle the residue, and how their context gathering differs.
- Best code search tools — the inventory phase, and knowing how many places actually match.
- Best database migration tools — the same coexistence pattern where rollback is not free.
- Best feature flag platforms — running old and new paths side by side so differential testing is possible.