Skip to main content
Published in Engineering Insights

Claude Code for Legacy Code Modernization: What It Can Do

Claude Code for Legacy Code Modernization: What It Can Do
Table of contents
  1. What can Claude Code actually do with a legacy codebase?
  2. What Anthropic ships for legacy code: the modernization plugin
  3. What do people on your team still have to decide?
  4. Why are the business rules the hard part?
  5. What if the old system only runs in production?
  6. How to run a first Claude Code pilot on one module
  7. What can go wrong when an AI agent reads old code?
  8. What does Anthropic's Spotify story show, and what does it not?
  9. When is a code audit the better next step?
  10. What happens after the audit if the answer is rebuild?

Claude Code can read a legacy codebase and hand back a map of how it fits together, a list of code that looks unused, a plain description of what each part does, and draft tests that pin down how it behaves today. It cannot tell you which of the business rules buried in that code are still true for your operation, and it does not approve the plan. A senior engineer and the people who run the work still make those calls.

This post is for the CIO at a distributor running an old order, pricing or warehouse system that nobody inside fully understands. It walks through what Claude Code can pull out of that system, what Anthropic ships to help, what a person still has to decide, and when an outside read is the cheaper next step.

The Gnar Company, a Claude Select Services Partner, offers a code audit for exactly this kind of system. Ask for the code audit. No fee, and it can come back saying your codebase is in reasonable shape.

What can Claude Code actually do with a legacy codebase?#

Claude Code reads the code you point it at and writes up what it finds. Anthropic's code modernization page lists the jobs: generate dependency graphs, identify dead code, write documentation for undocumented code, and help write regression tests, plus unit tests for refactored code. Each of those comes back as a draft. None of them is a decision.

The same page says Claude Code performs dependency mapping and helps with incremental refactoring strategies "while keeping humans in the loop." Here is what each job returns, and who has to check it before anyone acts on it.

Job What Claude Code hands back Who has to check it
Map the code Which parts call which, and where data flows An engineer who knows how it runs
Find dead code Code that looks unused An engineer, plus the logs from production
Explain the code A plain description of each part Someone who uses the system daily
Draft the business rules Rules with the file and line they come from (from the plugin README) The person who owns that process
Write tests Tests that pin how the system behaves today An engineer who can run old and new

The first three jobs are reading. Most of the answer is in the code, though code that looks unused can still run in production. The last two are different. The code shows what the system does. It does not show whether that is what your business still wants.

That gap is where most of the risk sits. An old pricing routine might apply a discount that sales stopped offering years ago. The code will still run it, and a careful reader will still report it as a rule. Only the person who owns pricing can say it should go.

What Anthropic ships for legacy code: the modernization plugin#

Anthropic publishes a code modernization plugin for Claude Code, under the Apache 2.0 license. Its README on GitHub promises four things: "an understanding of what it is and what it does, a plan you approve, the modernized code, and proof that the new code behaves like the old." It puts the work in an order, and each step stands alone, so you can stop and review after any of them.

The command names below are Anthropic's. Each one writes a file you can stop and read before you run the next.

  1. modernize-preflight checks whether the environment is ready. It asks five questions only a person can answer: is this the whole system or a slice, can it build and test here, is there custom build tooling, has anyone tried before, and is anything off limits.
  2. modernize-assess reports inventory, complexity, debt, security, and a recommended pattern.
  3. modernize-map draws the structure: dependencies, data flow, entry points and business flows.
  4. modernize-extract-rules writes the business rules as Given, When, Then cards. Each card cites the file and line it came from, and a second agent checks it again.
  5. modernize-review is where a person confirms or corrects the rules that look wrong.
  6. modernize-brief writes the phased plan. The README says nothing is built until you approve it.
  7. A build step follows. The plugin offers three: a newer version of the same technology, a module by module rewrite in another one, or a rebuild on a new architecture.
  8. modernize-verify re-checks the result and gives each module one verdict.
  9. modernize-harden runs a security scan of the old system, with a reviewed patch you apply yourself.

The README's own advice on scope is plain: "Start with one module or one unit as a pilot, not the whole estate." It also warns that some steps start many agents at once, "so expect real usage on a large system."

One more line from the README matters for a CIO. A few steps need someone who knows how the system is built and run, "so bring an engineer for the first questions."

What do people on your team still have to decide?#

People on your side still make six decisions, and Anthropic's README lists them: the preflight answers, the rules that look wrong, approving the brief, accepting any difference the proof finds, signing the proof, and applying the security patch. In its words: "A person decides at six points, and the plugin never decides them for you." Those six points are the work your people do. They do not go away when a tool does the reading.

Here are the six, in the README's words, with what each one asks of your team.

  • The five preflight answers. Someone has to know whether the code in the repository is the whole system, and whether anyone tried this before.
  • The rules that look wrong. Someone has to read the extracted rules and say which ones the business no longer follows.
  • Approving the brief. Someone signs off on the phases, the target and the order of work.
  • Accepting any difference the proof finds. When old and new give different answers on the same input, someone decides whether the old answer was a bug or a requirement.
  • Signing the proof. Someone puts their name on the verdict.
  • Applying the security patch. Someone reviews the patch and applies it.

Anthropic's article on COBOL modernization makes the same split. It says the tool can automate much of the exploration and analysis. At the point where work gets ranked and the target is chosen, it says, "This is where human judgment becomes essential."

A difference between old and new is not always a defect in the new code. Sometimes the old system was wrong for years and everyone worked around it. Deciding which is which takes someone who knows how the operation runs.

Why are the business rules the hard part?#

Business rules are hard because the code records what the system does, and only your people know what it is supposed to do. The plugin writes each rule as a card with a citation, so a person can check it against the source. Its README also says that "a model does the extraction, so two runs can find different rules."

That second line is honest, and it changes how you treat the output. The rules file is a draft for review. The README puts it as "reviewed output, not a deterministic build artifact," and names "a business expert per domain" as the reviewer.

Here is a made-up example of what that review looks like at a distributor. Say the rule card reads: given a customer on contract pricing, when the order includes a drop ship item, then the contract discount does not apply to that line. Claude Code can find that rule and point to the line that enforces it. It cannot tell you whether the rule came from a supplier agreement that ended, or one that still binds you.

So the first check for each card is the cited line: does the code say that? The next question is "do we still want it?" That question belongs to the person who owns pricing, receiving or returns. If no one owns a process anymore, that is a finding too, and it is worth knowing before anything gets rebuilt.

What if the old system only runs in production?#

The strongest proof needs the old system running somewhere safe, beside the new code. If you cannot do that, you cannot fully prove the new code behaves like the old. The plugin's README is direct about this case: "the old behavior can only be checked against recorded outputs, and the best verdict is PARTLY PROVEN."

If your system runs on one server, nobody has built it from source in years, and there is no copy to test against, you are in this spot. The README names this case, along with mainframe programs.

It also explains why the proof matters. "Modernization fails quietly: the new code passes the tests someone wrote, and differs on the inputs nobody thought of." That is why its verify step invents at least ten new inputs and compares again.

A simple rule follows. If your engineers can build and run the old system in a test environment, a pilot can reach the strongest proof the plugin offers. If they cannot, the first job is to get it running somewhere safe, or to accept that the best result for now is partly proven. That is a decision for your leadership, made with the facts in hand.

How to run a first Claude Code pilot on one module#

Run the first pilot on one bounded workflow, with the source set to read only and an engineer who knows the system in the room. Anthropic's COBOL article says to start with a single component that has clear boundaries and moderate complexity. Pick something a person can check in a day, such as how one report is calculated.

Before you start, have these in place:

  • The code for that module in a repository your team controls, with access for whoever runs the pilot.
  • A way to build and run the old module outside production, or an agreed fallback of recorded outputs.
  • One engineer who knows how the system is built and deployed.
  • One person who owns the business process the module supports.
  • A list of anything off limits: production data, live supplier links, customer records.
  • A place to write down what you learn, so it carries from one session to the next.

For the last item, Claude Code reads a file called CLAUDE.md at the start of every session, according to its memory docs. That makes it a good place to record the rules and decisions your team confirms, so the next session starts from them.

The plugin's commands never edit the source, by convention, and the README has you back that with a settings file, which preflight checks for. This is the example from Anthropic's README:

JSON
{
  "permissions": {
    "allow": ["Read(**)", "Edit(analysis/**)", "Edit(modernized/**)"],
    "deny": ["Edit(/legacy/**)"]
  }
}

The README notes the rule covers Claude's file tools and the shell commands it recognizes, not a script that opens files itself. The plugin points to your code through a link and copies nothing, so also block edits to the folder where the code really sits and allow reads from it.

Then run the steps in order, and stop after each one. Read the assessment. Walk the map with your engineer. Put the rule cards in front of the process owner. Only after those three reads should anyone talk about a plan.

What can go wrong when an AI agent reads old code?#

The main risks are planted instructions in the code, exposed secrets, usage on a system too big for a first pass, and trusting a confident draft. Anthropic's README addresses each one, and a CIO should ask how the team handles them before the pilot starts.

  • The code itself can carry instructions. The README says "analyzed code is untrusted input." A hostile codebase can plant comments such as "ignore previous instructions." The plugin's agents treat file content as data. Code someone else left you deserves the same care.
  • Old code holds old passwords. The README says discovered credentials are masked and kept out of shared reports. Check that your own setup does the same before reports go around the company.
  • Usage grows with size. Some steps start many agents at once. The size index that the assess step reports is "a relative measure for ranking systems, never a schedule or a cost." Do not read it as an estimate.
  • Drafts read like facts. A dependency map and a list of rules look finished. They are not, until someone who knows the system has checked them.

What does Anthropic's Spotify story show, and what does it not?#

Anthropic's Spotify customer story reports that Spotify saves "up to 90% of engineering time on complex code migrations" and merged "650+ agent-generated pull requests into production per month." Those are Anthropic's figures for migrations on code Spotify's own engineers maintain, with build and test tooling in place. They do not show what happens on a system nobody fully understands.

Spotify built the agent into its own Fleet Management system using the Claude Agent SDK. The story says the agent runs formatting, linting, builds, and tests before it sends a pull request. On one standardization effort, Claude "automated a majority of the implementation and engineers only have to review."

Read that setup closely. The work was migrations across code Spotify's own engineers maintain, with build and test tooling already in place and a verification step before every pull request. That is close to the newer-version-of-the-same-technology path in Anthropic's plugin.

A distributor's old order system is often a different problem. The people who wrote it may be gone. The tests may not exist. The rules may not be written anywhere. Spotify's numbers are real for Spotify. They are not a forecast for a system nobody fully understands.

When is a code audit the better next step?#

A code audit is the better next step when nobody inside can check what Claude Code hands back, or when the decision in front of you is whether to keep, fix or rebuild. Drafts nobody can judge do not move the decision. An outside read by engineers who do this work answers the question first.

At The Gnar Company, senior engineers in the U.S. read the code, with help from an AI tool Gnar built, and explain what they find. The audit has no fee. Gnar signs an NDA before it sees any code. You get back the risks worst first, quick fixes to start on, what the code really does, and your options: keep it, fix it, or rebuild it.

Two published cases show how the answer can go either way.

  • For the AARP Foundation, Gnar audited the old code first. The AARP Foundation case study says the audit found no integrated testing and security vulnerabilities. It showed replatforming would cost less and carry less risk than building on the old code. Gnar rebuilt 14 tools on React and Ruby on Rails, with 40% fewer clicks to complete an application, on average.
  • For First Line Technology, a full technical review pointed the other way. The First Line case study says it was more cost effective to build a new front end on the existing WordPress back end.

The audit can come back saying your code is fine, and we will say so. If your own engineers can make the fixes, the audit says that too. You can still run Claude Code yourself afterward, on a module the audit points to.

What happens after the audit if the answer is rebuild?#

If the audit says rebuild, the next step is a written plan for the new software, built from what the old code does. The Gnar Company does not copy the old code line by line. It turns the old code into a written plan, then builds from that plan. That is the same order Anthropic's plugin uses: understand, plan, approve, then build.

The plan comes from Gnar Discovery and Design. Foundation costs $15,000 for two weeks, Core $20,000 for four and Accelerator $30,000 for six, as listed on the Discovery page. Each tier ends with a Milestone Project Plan and a fixed price for your build. The build is typically $150K to $300K+.

The build carries Gnar's terms. Three commitments on every build engagement: a fixed milestone price with any overage on us, a guaranteed outcome meaning the software works as specified or we fix it, and a twelve-month bug-free warranty.

Not every answer is a full rebuild. Gnar's modernization work includes another path: keep your system of record and build a modern experience on top of it. Our posts on whether to replatform, refactor or rebuild and on modernizing an ERP without a big bang cutover walk through those choices.

Start with one module, put the drafts in front of the people who own the work, and decide from there.

Frequently asked questions

Can Claude Code modernize a legacy system on its own?

No. Claude Code can read the code, map it, draft the business rules and write tests, but a person still decides which rules are true and whether to approve the plan. Anthropic's own plugin README lists six decisions it never makes for you, from the preflight answers to applying the security patch.

Does Anthropic's code modernization plugin change our existing code?

Not by design. Its README says nothing edits your legacy source, and the commands write only to their own analysis and modernized folders. Your team adds a deny rule to the workspace settings file, and the plugin's preflight step checks that it is there. A script that opens files itself is not covered. A build check can still write build output where your build normally does.

Which languages does Anthropic's code modernization plugin work with?

Anthropic's plugin README says it works with any language. Its test runs include COBOL, Java, PHP, Perl, Python 2, C and AngularJS code. Reading a language is not the same as knowing your business, so the rules it extracts still need a person who knows how the system is used.

How many agents does Anthropic's plugin start on a large legacy codebase?

In Anthropic's test runs, the heaviest step, extract-rules, started 50 to 200 agents, and it asks before a big run. The README also says the size index from its assess step is a relative measure for ranking systems, never a schedule or a cost. Run one module first and read what it used.

Does The Gnar Company offer a code audit for a legacy system?

Yes. The Gnar Company signs an NDA, then senior engineers in the U.S. read the code with help from an AI tool Gnar built, and report the risks worst first. Ask for the code audit. No fee, and it can come back saying your codebase is in reasonable shape.

What does The Gnar Company charge to plan a rebuild after the audit?

Gnar Discovery and Design costs $15,000 for two weeks, $20,000 for four or $30,000 for six. Two weeks, $15,000, and you walk out with a build plan that has a fixed price on it. The build that plan scopes is typically $150K to $300K+.

Stay In The Loop

Never miss an update. Get the latest blogs, webinars, and expert insights straight to your inbox from The Gnar.