Using Claude Code for Legacy Code Modernization

Greenfield coding gets the demos, but legacy work is where agentic tools change project viability. The reasons are structural:

• Comprehension is the bottleneck, and it’s readable work. Most modernization time goes to understanding, not writing. An agent that traces call paths and reconstructs behavior across thousands of files attacks the actual constraint.
• The work is verifiable. Modernization means preserving behavior while changing structure — and behavior preservation can be checked mechanically with tests, which suits agent workflows perfectly.
• Much of it is high-volume and mechanical. API migrations, pattern replacements, and dependency upgrades are exactly the repetitive-but-not-identical work agents do tirelessly and humans do badly.

None of this removes human judgment; it removes the drudgery that made modernization projects economically unjustifiable.

Start every modernization engagement with a comprehension pass, producing artifacts rather than vibes. Point Claude Code at the codebase and have it generate:

• A module map: what exists, what depends on what, where the load-bearing paths are.
• Behavioral documentation for critical flows — reconstructed from the code itself, not stale wikis.
• A risk inventory: dead code, duplicated logic, implicit contracts, undocumented side effects, and the places where the code and the comments disagree.

Use subagents to parallelize exploration across large codebases while keeping the main session’s context clean, and check the resulting documentation into the repo — including a CLAUDE.md so every later session starts oriented. Have system veterans review these artifacts; their corrections are the cheapest risk reduction you will buy in the entire project.

The iron rule of legacy work: never change untested behavior. Legacy systems usually lack tests precisely because writing them retroactively is miserable — which is why it’s an ideal agent task.

Have Claude Code write characterization tests: tests that pin down what the system currently does, including its quirks, rather than what a spec says it should do. Practical discipline:

• Prioritize the load-bearing paths identified in the archaeology phase; full coverage is not the goal, safe change is.
• Review generated tests for assertion strength — a test that runs code but asserts nothing is coverage theater.
• Where behavior looks like a bug, record it and preserve it for now; fixing behavior and restructuring code in the same change is how regressions hide.

This safety net is what converts the refactor from a leap of faith into an engineering process.

With tests in place, modernize in small, independently shippable slices — strangler-fig style — rather than a rewrite branch that drifts for months. Effective patterns with Claude Code:

• Plan-then-execute per slice: the agent proposes which files change and how, a human approves, then it executes with tests running via hooks after every edit.
• One transformation per pass: extract a module, or update a pattern, or rename a concept — never several at once, so diffs stay reviewable.
• Mechanical sweeps at scale: once a human validates a transformation on two or three instances, let the agent apply it across the remaining hundreds, with tests as the gate.

Model choice mirrors the split: frontier models like Claude Fable 5 or Opus 4.8 for gnarly architectural reasoning, faster models like Sonnet 5 or Haiku 4.5 for the validated mechanical sweeps.

Full migrations — framework major-versions, language ports, EOL dependency replacements — follow the same skeleton with extra rigor:

• Build a migration inventory first: every usage of the old API or idiom, categorized by pattern. Claude Code generates this quickly and it becomes your progress tracker.
• Define the target pattern per category with a human-approved reference example, then let the agent replicate it across the inventory.
• Keep old and new paths runnable side by side where feasible, cutting over route by route rather than flag-day.
• For language ports, treat the characterization suite as the contract: the port is done when the new implementation passes the old system’s pinned behavior.

Beware the classic trap: the last ten percent — the weird cases the inventory flagged as “other” — takes disproportionate time and deserves your most senior reviewers, not the least.