The Code Modernization Plugin, Explained

The core idea: modernization fails when teams skip steps

Ask any engineer who has lived through a rewrite: the failure mode is almost never the new technology. It’s the skipped homework — transforming code before understanding it, or shipping without a harness that catches behavior drift.

The plugin’s answer is to enforce a sequence. Per the official README, it runs: preflight → assess → map → extract-rules → brief → (reimagine | transform | uplift) → verify → harden. Each step stands alone, so you can stop and review after any of them — and the build steps refuse to run until a human approves the brief.

This also explains the plugin’s shape: it’s not one smart agent but seven slash commands plus five specialist agents that argue with each other — a critic whose job is to call out over-engineering, a test engineer who checks whether your tests actually pin behavior, a security auditor tuned for the mistakes cross-stack rewrites introduce. The sequence is the product; the agents are the crew that walks it.

The enforced path: understand, approve, build, prove

Every command ends with a “next step” line telling you exactly what to run next. Here’s the full path, from the README’s own table.

Step 0 — say what you want. /code-modernization:modernize asks a couple of short questions, writes your answers to INTENT.md once, and every later command reads it — nothing is asked twice. Not sure what you want yet? Choose understand it first: you get the assessment, the map, the business rules, and a plan, and no code is rebuilt.

Step 1 — preflight. modernize-preflight checks 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, is anything off limits), proves a build works on this code, and finds missing source. Your legacy code is linked, never copied, and nothing edits your legacy source — commands write only to analysis/<name>/ and modernized/.

Steps 2–4 — assess, map, extract-rules. modernize-assess inventories the codebase: complexity, debt, security posture, and a recommended pattern. modernize-map draws the structure — dependencies, data flow, entry points, business flows — as an interactive map. modernize-extract-rules mines the business rules out of the code as testable Given/When/Then cards, each with a file:line citation, and each card is re-checked by a second agent. A companion modernize-review step lets a person confirm or correct the rules that look wrong — your corrections flow into the plan and the build.

Step 5 — the brief, the approval gate. modernize-brief synthesizes everything into a phased plan a steering committee can approve. Nothing is built until you approve it. The README is explicit: a person decides at six points — the five preflight answers, the rules that look wrong, approving the brief, accepting any difference the proof finds, signing the proof, and applying the security patch — and the plugin never decides any of them for you.

Steps 6–8 — build, verify, harden. One of three build methods (next section), then modernize-verify — the proof — then modernize-harden, a security scan of the legacy system with a reviewed patch you apply yourself. A modernize-status command tells you where you are and the exact command to paste, any time.

The five agents: a team that argues with itself

The plugin’s own addition notes describe five specialist agents. Each does one job — and the adversarial ones exist so the team checks its own work.

The heavy steps run many agents at once: the README says extract-rules started 50 to 200 agents in its trial runs, and every fan-out step announces how many it will start before it does. That’s also why the README warns to expect real usage on a large system — and to start with one module as a pilot, not the whole estate.

Three ways to build: transform, reimagine, uplift

The brief recommends one of three methods — they’re genuinely different operations, not three names for “rewrite it.”

Two things the brief won’t recommend a build for: rehost (move the system as-is) and replace (buy a product instead) — neither changes code, so no build command applies, though the analysis is still useful for both. And if the delta catalog shows an “uplift” would rewrite most of the code anyway, the command says so and points you at transform instead.

The proof step: trust, but byte-compare

This is the part that separates the plugin from “AI rewrote my code, hope it works.” Modernization fails quietly: the new code passes the tests someone wrote, and differs on the inputs nobody thought of.

So modernize-verify builds its proof from evidence a script can check, not from the model’s opinion — and it re-does the work instead of trusting the build’s notes:

• The tests, run again from clean. Build output is deleted, the full suite runs, and counts come from the runner’s own result files. A run that executed no tests is a failure; a count the command merely typed in does not count.
• Old and new on the same inputs. Where the legacy code can run, both versions run on identical inputs and a script compares every byte — only fields that must vary (timestamps, generated IDs) are masked, and every masked field is listed.
• Inputs nobody used. It invents at least ten new inputs — boundaries, empty, huge, unusual order, malformed records — and compares again, so a suite that only passes on cases the model chose gets caught.
• Tests that can fail. A deliberate one-line break must turn the tests red — the canary — and the comparison itself is checked by changing one byte of an output.
• Every critical rule is backed by a test that ran. Each P0 business rule must be named by a test that executed and passed; a rule named only by a skipped test is listed as “named, not run.”

Each module gets one verdict, recomputed from current evidence every time: PROVEN, PARTLY PROVEN (with what’s missing), or NOT PROVEN. If the old system can’t run where you work — a mainframe program, a system that only runs in production — the best possible verdict is PARTLY PROVEN, and the report says so plainly. Anything a person must decide is listed as waiting for a person and never ticked for you.

Real-world use cases

Anthropic ran the plugin for real, headlessly, on public codebases while building it — and published what happened, including the runs that didn’t pass. Every number below is the README’s own reported figure from those runs.

The pattern across all of them: the value isn’t the rewrite — it’s the cited understanding and the proof. The rewrite is just what you do once you have both.

Install it

You need Claude Code. Then it’s one command, per the README:

# from inside a Claude Code session:
/plugin install code-modernization@claude-plugins-official

Then open a folder for the work and type /code-modernization:modernize — it asks what you want to do, finds the code, and gives you the exact first command. Or go step by step with modernize-preflight <name> --source <path> and follow each command’s “next step” line.

Prerequisites (helpful, checked by preflight):

• Python 3.8+ on your PATH — the map, the proof, and the report run on Python.
• A build toolchain for your stack — this enables the strongest proof (old and new running side by side). Without one, the plugin falls back to recorded-output tests and says so.
• scc or cloc for size metrics; the whole system in the tree (deployment descriptors, copybooks, DDL) so entry points and data lineage resolve.

Lock down the workspace — the commands never edit your code by convention, and the README recommends backing that up with a deny rule in .claude/settings.json (preflight checks for it):

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

Honest limits

The plugin is unusually candid about its own limits — the README documents them at length. Here’s the short version.

Heavy steps cost real usage. Rule extraction fanned out 50 to 200 agents in the trial runs. On a large system, expect meaningful model spend — which is why the README says to start with one module as a pilot, not the whole estate. This is not a fire-and-forget tool; it’s a project.

Rule extraction isn’t deterministic. A model does the mining, so two runs can find different rules. The README says to treat BUSINESS_RULES.md as reviewed output, not a deterministic build artifact — which is exactly why the human review step exists.

Some systems cap at PARTLY PROVEN. If the legacy code can’t run where you work — a mainframe program, a production-only system — old-versus-new comparison is impossible, and the report says PARTLY PROVEN plainly. That’s a property of your environment, not a bug, but it bounds what the proof can promise.

Analyzed code is untrusted input. A hostile codebase can plant “ignore previous instructions” comments or credential-shaped traps. The plugin treats file content as data, lists instruction-shaped text it found without following it — Anthropic even tested this with a booby-trapped codebase, and reports that nothing planted was obeyed — but the README still says to treat discovery artifacts with the same skepticism as the code.

It counts what you do. The plugin sends usage telemetry — whole numbers only, never code, paths, or prompts — through Claude Code’s own telemetry. You can turn it off with CODE_MODERNIZATION_TELEMETRY=0, Claude Code’s DISABLE_TELEMETRY=1, or the plugin’s own Usage-counts option.

FAQ

Key takeaways

1. code-modernization is Anthropic’s official, free plugin for Claude Code that enforces a strict modernization sequence — understand first (preflight, assess, map, extract-rules), get human approval (brief), then build (transform, reimagine, or uplift), then prove (verify) and secure (harden).
2. Five specialist agents do the deep work: legacy-analyst reads unfamiliar dialects like COBOL, business-rules-extractor mines Given/When/Then rules with file-and-line citations, architecture-critic argues against over-engineering, security-auditor reviews cross-stack translation risks, and test-engineer checks that tests pin behavior rather than chase coverage.
3. Three genuinely different build methods: transform rewrites cross-stack (COBOL to Java), reimagine rebuilds greenfield on a new architecture, and uplift bumps the version (Java 8 to 17, .NET Framework to .NET 8) while preserving your code — the brief recommends which one fits.
4. The proof step is the differentiator: old and new run on the same inputs with byte-level comparison, invented edge-case inputs, and a canary break that must turn tests red. Verdicts are PROVEN, PARTLY PROVEN, or NOT PROVEN — recomputed from evidence on every run, never carried over.
5. Safety by design: legacy source is never edited (backed by a permission deny rule), analyzed code is treated as untrusted input, discovered secrets are masked, and a person decides at six gates — including brief approval and proof sign-off.
6. Honest limits: heavy steps fan out dozens to hundreds of agents (pilot one module first), rule extraction isn’t deterministic across runs, systems that can’t execute cap at PARTLY PROVEN, and usage telemetry sends counts only — with an opt-out.

Sources

Every claim, number, and trial-run result in this guide comes from the sources below. The explanations are entirely our own — the measurements and figures are the original authors’.