Back to storiesPractical guides

Modernize legacy code with AI: three cases to plan before the rewrite

Plan an AI-assisted legacy upgrade with three concrete cases: runtime updates, service replacement and changed business rules. Includes original diagrams and a runnable compatibility exercise.

Updated 12 min readMarkdown
On this page8 sections

An upgrade request with two different meanings

Decide what must stay the same before delegating the rewrite. Then choose evidence that would expose a wrong result, and agree who can approve the change. Those decisions determine whether AI's output becomes a useful upgrade or a long review argument.

Your team wants AI to replace an aging customer-export service. Engineering wants easier maintenance. Sales adds a small request: merge duplicate customers and sort the file. Finance still needs that file to work with its monthly import.

Before any code is written, the team has two jobs with different definitions of success. Replacing the implementation should preserve agreed behavior. Merging customers deliberately changes it. A test that proves the first job succeeded can reject the second job's correct result.

Anthropic's code modernization article, published September 23, 2026, makes this preparation central to modernization. We apply that idea below to one fictional team: first upgrading its runtime, then replacing its export service, then changing a customer rule. The examples, diagrams and downloadable exercise are our own teaching material. They are not a report of an AI migration we performed.

Find out who depends on the result

Start by tracing one real request. In our example, a sales colleague selects customers, the service checks their access, reads customer records and produces a CSV. Finance imports it; an archive keeps a copy for later reconciliation. Replacing the export function touches only one box, but its output crosses several boundaries.

Fictional customer export: a permission check and customer records feed the export service; finance import and an archive depend on its output. Three questions identify hidden requirements.

Ask the investigator to read the callers, query, serializer and available import specification. For each dependency, record the source file and line, the observed behavior, and any unanswered question. For example: “The query has no explicit sort; the serializer preserves received order. Does finance depend on that order?” Code can establish the first two observations. The finance owner must answer the last question.

A useful first deliverable is a short map of dependencies with unresolved rules attached. It tells the team where to investigate before promising that the replacement is compatible. A diagram with hundreds of nodes is less useful if nobody can explain which relationship makes this change risky.

The original article illustrates discovery with a CardDemo dependency-map screenshot. Our smaller diagram focuses on the callers and consumers that decide the scope of this example.

Case 1: Upgrade the runtime and keep the file unchanged

The first request is narrow: move the service to the team's approved runtime and dependency versions. The API, customer selection and CSV rules stay the same. Anthropic calls this kind of change an uplift.

Take the fictional input B02 / Bea followed by A01 / Ada. The required file still lists B02 before A01, has the same header, and ends with the agreed newline. An empty selection must keep its agreed result too. An access-denied request must still be denied before exporting anything.

In an existing Onevium project, give the session a bounded task:

Plan the runtime upgrade for the customer export service.
Read the current version, lockfile, CI configuration and tests.
Use the target versions in our approved upgrade ticket.
List incompatibilities and the files that need changing.
Keep the API, permissions, row order and CSV format unchanged.
Do not add sorting or customer merging.
Before implementation, identify missing checks and decisions.

Once the plan is reviewed, run the relevant tests on the old and target environments and compare the exported bytes for approved sample inputs. Keep the environment versions, command and output with the change. Tests that passed only on a developer's original runtime do not validate the upgrade.

A plausible failure: all CSV tests pass, but a replaced authentication dependency rejects valid users. That is why the dependency map includes the permission path. The boundary is the working export request, not just its string-formatting function.

Case 2: Replace the service and compare what consumers receive

The team now wants to replace the service with a new implementation, perhaps in another language. The customer-facing behavior should remain the same. The original article calls this a transform. Existing unit tests may not transfer across languages; the observable contract still matters.

Run the same authorized sample request through both implementations in a test environment. For this export, compare CSV bytes, HTTP status, content type and filename. Include invalid requests and permission failures. If a replacement also writes data, test whether old and new readers can consume the stored format.

Two export implementations receive B02 then A01. The approved output preserves that order. A sorted candidate returns A01 then B02 and fails despite containing the same records.

The sorted file in the figure looks reasonable. It still breaks our deliberately order-sensitive contract. A record count or an HTTP 200 check would miss it. For a JSON API, the meaningful comparison may instead be selected fields and semantics: choose the comparison around what consumers rely on, and document any normalization before running it.

Ask the Onevium session to build the comparison before the replacement:

Use the approved export contract to propose independent inputs
and expected results. Cover ordering, empty input, escaping,
invalid data and permission errors. Keep open questions visible.
After review, build a repeatable comparison of old and new outputs.
Do not generate all expected answers by calling the old service.
Do not change expectations to accommodate the new implementation.

The old service may contain a bug. If both versions produce the same wrong answer, a simple comparison still passes. Independently agreed expectations prevent that trap. Record an intentional bug fix as an approved exception, with its own expected result and affected consumers.

Case 3: Change the customer rule and write a new expected answer

Sales still wants the file simplified: one row per customer ID, use the name from the latest record, then sort by ID. This deliberately changes business behavior—what the original article calls reimagine. Matching the old output is no longer the success criterion.

Use a concrete example to get agreement:

Incoming recordNameUpdated at (UTC)
B02Bea2026-09-01T09:00:00Z
A01Ada2026-09-01T10:00:00Z
B02Beatrice2026-09-03T09:00:00Z

The proposed result has two rows: A01 / Ada, then B02 / Beatrice. Previously all three rows remained in their input order. Show both outcomes to the sales and finance owners before asking AI to implement the new rule. Finance may actually need the older records for reconciliation; merging would then require a separate export option rather than replacing its existing file.

Three small follow-up examples expose unfinished decisions: two records with the same ID and timestamp but different names; a missing timestamp; and an empty latest name. Does an empty value erase a known name? Until the owner decides, these are unresolved requirements, not edge cases the assistant should invent a policy for.

The implementation task can now reference a reviewed table of examples, including those decisions. Keep the original export's checks, add tests for the new option, and verify that selecting the old mode still produces its old result. For a limited trial, choose a defined group and monitor rejected imports and disagreements—not merely the number of successful API calls.

This case is a planning example; the downloadable serializer below does not implement customer merging. Its nine passing checks cannot validate the new business rule.

Give each Onevium session a question it can answer

One conversation is enough for the small exercise below. On an actual service, investigation and independent test design can become useful separate tasks. Split by responsibility and timing, rather than asking several sessions to rewrite the same service.

WorkUseful outputHandoff
Trace dependenciesCallers, consumers, source locations and unresolved rulesThe owner resolves the behavior contract
Prepare verificationInputs, agreed expected answers and a deliberate wrong result that failsImplementation uses the reviewed contract
Implement one boundaryA limited diff and recorded test outputA reviewer inspects both the change and its evidence

Use the project's file context through @, and keep the contract and reports in agreed project files. For coordinated members, follow the Team setup and workflow: select @ → Team, check that the team Skill and Sessions tools are available, and have the lead propose responsibilities and dependencies for confirmation before starting. Follow the workflow's confirmations at later stages too.

The investigator and verifier can prepare work in parallel while the owner resolves questions. Implementation waits for the agreed rules; final review waits for actual code. Give shared files a single writer. Members' findings need an explicit handoff through the lead and files—their entire contexts are not automatically shared, and their working directories are not automatically isolated.

In an existing Git project, use Files, Terminal and Review to inspect the contract, run the checks and read the final diff. A member saying “done” is a starting point for review. The person approving the change still needs evidence tied to the revision being released.

Complete one pilot through release before expanding

For the export pilot, “all tests pass” still leaves a practical question: has finance imported the new file successfully? If that trial has not happened, say so. A useful review note separates observed results from missing evidence:

Pilot: customer export replacement; existing contract retained.
Code: the exact revision under review.
Evidence: attach actual commands, outputs and comparison results.
Consumer trial: record who checked an import and what happened.
Open differences: list unresolved cases and affected consumers.
Release decision: owner, limited rollout scope and stop condition.
Recovery: verify how the previous service will be restored.

The original distinguishes a certificate, the agreed evidence required from a change, from a promotion policy, the rule for allowing it into production. For this team, that can be a passing compatibility check plus an approved finance import, followed by a named owner authorizing a limited rollout. A passing local test does not make that decision automatically.

A fictional export pilot moves through local checks, consumer import review, limited release and observation. Failure returns to the relevant step; expansion waits for observed results.

Start with inexpensive build and unit checks. Run the more costly old/new replay and consumer trial after those pass. That saves reviewer attention for changes with useful evidence. The original verification and promotion figure shows the distinction, including the path for changes that need human help.

Select a small service boundary, coordinate changes to it during the pilot, and take it through the team's actual release process. Record checking time, retries and owner review as well as implementation time. Use what happened to improve the next pilot's checks. This follows the original partition rollout figure: complete a pilot before multiplying the work.

Keep the old implementation available during a replacement where feasible. If the new path writes a format the old version cannot read, restoring the old code alone will not recover service. That needs a data recovery plan before rollout. Our small read-and-export example deliberately avoids such a data migration.

Try a small check that catches a convincing mistake

Download the runnable exercise if you want to try the comparison before applying it to a service. It contains a CSV serializer, nine fixed cases and deliberately incorrect replacements. You need Node.js 20 or later; running it needs no packages or network. AI assistance additionally needs a model connection.

Extract into a new folder, open it as an existing project in Onevium, and create a conversation from the project. Read behavior.md and the expected values in cases.json. The contract preserves order and duplicate IDs, defines CSV escaping and TypeError results for invalid rows, and prohibits changing the input.

node verify.mjs
node verify.mjs --candidate=examples/sorted.mjs
node verify.mjs --candidate=examples/mutates-input.mjs

The initial candidate is a copy of the old implementation: 9/9 passed, exit 0. The sorting example reports 8/9 passed, fails input-order, and exits 1. The input-mutation example reports 1/9 passed, exit 1; it changes the first record in every nonempty case, even on error paths. Those two failures are intentional. They show why checking only the returned records would be insufficient.

Now give the session a small implementation task:

Read behavior.md, legacy.mjs, cases.json and verify.mjs.
Refactor candidate.mjs to give CSV escaping a named helper.
Preserve the contract. Edit only candidate.mjs and create review.md.
Do not read examples/ until after your own attempt.
Do not change the old code, expected values or verifier.
Run node verify.mjs; record actual output and uncovered cases.
Stop if a requirement conflicts with existing behavior.
Do not commit, push or deploy.

Inspect the changed file and rerun the checks yourself. The ZIP is not a Git repository; its README explains direct file comparison. A supplied reference implementation passes nine cases, and node --test test.mjs checks that the verifier also rejects the deliberate mistakes. The examples are authored fixtures, not measured AI performance.

These checks cover a serializer, not HTTP permissions, another language, finance software or production capacity. CSV quoting does not prevent spreadsheet formulas from executing; that needs its own rule before exporting untrusted content to spreadsheets. Use approved, appropriately scrubbed data for a real trial and consider what the configured model provider receives.

For your first service pilot, take one output that must remain stable and one failure that must still be rejected. Write their expected results, make a deliberately wrong candidate fail, and then ask AI for the bounded change. The earlier cases show how to extend that evidence when the task grows beyond a function.