Wrapping Old Code Instead of Rewriting It

Michael Feathers defines legacy code simply as code without tests. His point is not about age: it is that without automated tests you cannot verifiably change behavior, so fear of touching the code becomes rational (BSSw). He states the consequence plainly: with tests we can change behavior quickly and verifiably; without them "we really don't know if our code is getting better or worse" (BSSw).

That creates a paradox: you should have tests before you change code, but getting tests in place usually requires changing code. The way out is minimal, safe refactoring first: identify change points and seams, break dependencies, write the tests, make the change, then refactor (Understand Legacy Code). A seam is a place where you can alter behavior without editing the source, most commonly by substituting a subclass or an injected dependency in the test.

The test type that gets you started is the characterization test: a test that captures what the code actually does, not what you think it should do. If a method returns 12 for inputs 1 and 1, you assert 12 and move on. Once code is in the wild, users build processes around its quirks, so "right" and "wrong" stop mattering and "what is" becomes the specification (DaedTech).

Feathers himself says AI tools are genuinely useful for exactly this job, listing explaining code, identifying potential issues and generating tests among the productive uses (Tech Lead Journal). That is the narrow, high-value role: the agent proposes the test, you confirm the captured behavior is the one you want to keep.

Both patterns put a stable interface in front of the old code. They differ in where the decision lives.

Facade (strangler fig at the edge). A proxy sits between clients and the backend. Clients keep calling the same address. The proxy decides per request whether to forward to the legacy system or the new service. This is the Microsoft model: the facade routes most requests to the legacy system initially, shifts them incrementally, and is removed once the legacy system is decommissioned (Microsoft Learn). AWS frames the same pattern as a way to migrate a monolith incrementally with reduced transformation risk and less business disruption, since coupled code cannot be tested in isolation and every change forces broad retesting (AWS Prescriptive Guidance).

Branch by abstraction (inside the code). You insert an interface over the component being replaced, refactor callers to use it, add the new implementation, and have the interface delegate to old or new as required. Then you delete the old implementation and, if you like, the interface (Continuous Delivery). Confluent's walkthrough of extracting notifications from a monolith shows the same three moves: adapter in front of the old code, new implementation built alongside, swap the adapter when ready (Confluent).

The routing rule is the same shape in both. A worked example: a slice that starts at 1 percent of traffic, moves to 5 percent, then 25, then 100, with automatic reversion if the error rate on the new path exceeds the old path by a set margin over a set window. The percentages and thresholds are yours to set; what matters is that each step is a config change, not a deploy.

The harness has three layers, and you need all three before the first slice takes traffic.

1. Characterization tests on the legacy slice. Target only the code you are about to replace, not the whole codebase, and aim for near-total coverage of that slice, because without it you cannot tell whether behavior was preserved (BSSw). Generate these with an agent, review each assertion by hand, and commit them before any routing changes. Feathers notes some vendors now offer to write all your tests for you, which alarms a test-driven developer but works well for characterization testing specifically (Tech Lead Journal).

2. Golden-input replay. Record real request and response pairs from production for the slice, then replay them against the new implementation offline and diff the outputs. This catches the long tail that hand-written tests miss. Agent-driven modernization work commonly lands in the 60 to 80 percent automation range precisely because automated refactoring still needs this kind of verification and human issue resolution (InterSystems).

3. Contract tests at the interface. These assert the shape of the response (fields, types, error codes, ordering) independently of either implementation, so they keep passing when the old code is deleted.

A small comparison wrapper makes shadow mode practical:

def handle(request):
    old_result = legacy.handle(request)
    if not in_shadow(request):
        return old_result
    new_result = modern.handle(request)
    if not equivalent(old_result, new_result):
        log_divergence(request, old_result, new_result)
    return old_result  # old system stays authoritative during shadow

Shadow mode means calling both implementations and comparing, while still returning the old result. Confluent describes this exact use: run both, log the differences, and monitor how close you are to completion before you swap which one returns the answer (Confluent). The comparison function needs judgement: exact equality on IDs and amounts, tolerance on timestamps and float rounding, and an explicit ignore list for fields you know will differ, such as a generated request ID.

Coding agents help most when the task is bounded and the feedback loop is tight. The failure mode is the opposite: agents make changes based on incomplete understanding of a large system and add new debt while removing old debt. One team's 12-week modernization of a 10 million line Java ERP stalled for more than nine months because agents were productive but operating without context infrastructure, going down rabbit holes and introducing inconsistencies the humans then had to clean up (Driver).

The practices that keep agents useful on legacy code, from a practitioner walkthrough of the workflow, are worth treating as rules (Google Cloud Tech):

• Document the local build, linter and test commands in a README so the agent can self-correct against real feedback instead of guessing.
• Map the blast radius first: ask what files, APIs and tables break before a line is touched.
• Lead with the failing test, written by a stronger model, then let a cheaper, faster model write the implementation until it goes green.
• Break large tasks down and keep a running markdown checklist to prevent context drift.

A practitioner thread on scaling LLMs to large codebases adds two specific hazards: agents assume your language is C or Python wearing a costume, and they ignore surrounding code that could be reused, producing copy-paste sprawl (Hacker News). Both are mitigated by naming the seam explicitly in the prompt and asking the agent to cite which existing functions it reused.

If your team is running several agents across slices and wants a shared, tested capability instead of re-prompting from scratch, Quanta Skills (https://quantaintelligence.ai/skills) covers that workflow at the tool level.

A partial migration is in production for weeks. The review process has to treat "half old, half new" as a normal state, not a temporary mess to be tolerated.

The data point that bites most teams is the fifth. Microsoft's guidance flags shared data stores explicitly: when both systems use the same store, you must decide how to keep access compatible and how to handle updates that race between them (Microsoft Learn). The safe default for a first slice is to route reads to the new path and keep writes on the old path until the new path has proven idempotent under retry.

For the sixth gate, Wikipedia notes a quieter use of the pattern: adding logging to old code to see how often it runs, which is exactly the metric that tells you when a slice is truly dead and safe to delete (Wikipedia). Treat the call count, not the calendar, as the removal signal.

Rollback is not a document. It is a switch, and its behavior under load is something you test before you need it.

Feature flags give per-feature rollback without redeployment, while rolling back a canary typically means rolling back the whole deployment, which is why the two are complements rather than substitutes (Harness). For a slice migration, the flag should have four properties:

1. One name, one owner. A single flag per slice, named after the slice, with a named person responsible for flipping it.
2. Fail-closed to the old path. If the flag service is unreachable, traffic goes to the legacy implementation. The old code is the safe default until the very last step.
3. No deploy required. The flip happens through configuration, in seconds.
4. Rehearsed. Flip to new and back in staging under production-like load, and time it. If the reverse flip takes twenty minutes, you do not have a rollback.

Set the trigger before you start, in numbers. A workable default: automatic reversion when the new path's error rate exceeds the old path's by more than a fixed absolute margin over a fifteen-minute window, or when p95 latency on the new path exceeds the old by more than a set percentage. Write the thresholds into the slice's checklist so that nobody negotiates them mid-incident.

Two operational details finish the job. First, keep the comparison logging running after you flip to 100 percent, for at least a full business cycle, because some divergences only appear on month-end or quarter-end paths. Second, before deleting the old implementation, remove the flag and the interface in the same change window, and confirm from the call-count metric that nothing else reached in.

When the migration ends, the transitional code becomes debt of its own. Schedule its removal as the final slice ticket with the same rigor as the first, because adapter code left in place quietly becomes the next generation's legacy.