# Should we rewrite legacy code to be agent-friendly or add a context layer on top of it?


URL: https://getunblocked.com/answers/rewrite-legacy-code-for-agents-or-add-context-layer/
Published: 2026-11-11T18:30:00Z
Updated: 2026-11-08T16:34:00Z
Author: Dennis Pilarinos
Categories: Context Engine, Engineering Insights

**Short answer:** Add the context layer first. Agents already read old code well. What they lack is the reasons behind it, and a rewrite does not put those reasons in the repo. It tends to lose them. Rewrite only when the platform itself is the problem or the system is small, and do it one piece at a time with the context layer already in place.

---
Add a context layer first, and rewrite only where the platform itself is the problem. A rewrite to make legacy code friendly to AI agents solves a problem they mostly do not have. They can read old code. What they cannot read is why the code is the way it is, and a rewrite does not write that down. It usually throws it away. **A context layer** is a service that sits beside your code and answers an agent's questions from the history around it. That history is the pull requests, tickets, design docs, chat threads and incidents that explain each odd choice. Connecting one is a setup job. Rewriting a large system is a project of many months, and it puts working behavior at risk.

## What agents actually get wrong in legacy code

The case for a rewrite assumes agents fail because old code is hard to read. Anthropic's own guidance says the opposite. Claude "starts every task by reading your code, and current models are _very_ good at this," finding layout, conventions and test frameworks quickly. "What it can't find is the information that was never in the repo," such as "a decision your team made in a meeting" ([Claude Code best practices](https://code.claude.com/docs/en/best-practices)).

Legacy code is full of that second kind of gap. A retry loop that looks pointless guards against a vendor outage from 2019. A column nobody reads feeds a quarterly finance export. Two data-access patterns live side by side, and only one of them is current. Clean names and modern syntax do not tell an agent any of this. A rewritten module with the same missing reasons is easier to read and just as easy to break.

So ask what the agent got wrong last week before you budget a rewrite. If the answer is "it copied the old pattern" or "it removed a check we need," the code was readable. The reasons were missing.

## What a rewrite costs, and what it loses

A rewrite is the riskiest place to lose those reasons. Researchers who built a multi-agent modernization tool open their May 2026 paper bluntly. "Legacy modernization breaks business logic more often than most teams expect." The rules that get lost are "implicit rules, edge-case handling, and cross-module constraints," and "nobody notices until something fails in production" ([Ahmed and Galib, arXiv](https://arxiv.org/abs/2605.17535)). Their fix was to pull the business logic out into an explicit specification before writing any new code. That is a context step, done before the rewrite.

An August 2026 case study measured what happens when an agent does the rewrite. The methodology was direct. The team used Claude Code to port 12 features of a corporate ERP system from Visual Basic 6 to C# on .NET 10. The ported features matched the original's behavior 70 percent of the time on average. Simple features reached 92 percent. The two high-complexity features reached 47 percent and used about six times the tokens ([Alves, Politowski and Montandon, arXiv](https://arxiv.org/abs/2608.28972)).

The token bill was small, about $10 per complex feature on average. The real cost is the other 53 percent: someone has to find every behavior that changed, and the complex features are where the old reasons live. Microsoft's architecture guidance makes the same point about scale: "It's difficult to replace an entire complex system" ([Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/strangler-fig)).

## When a rewrite is still the right call

Some rewrites are worth doing, and a context layer does not remove the reasons for them. The table sorts the common cases.

| Situation | Rewrite? | Why |
| --- | --- | --- |
| The platform is end of life | Yes, in slices | Discontinued platforms are a business risk in their own right. The case study above started from Visual Basic 6 for that reason. |
| The system is small | Yes, all at once | Microsoft says incremental migration "might not be suitable" when "you migrate a small system and replacing the whole system is simple." |
| You cannot hire people to maintain it, or it fails a security or compliance rule | Yes, in slices | The cost of keeping it grows every year. |
| The design blocks the product, such as a shared database two teams fight over | Yes, that part | Rewrite the blocking piece and leave the rest. |
| Agents keep making wrong changes in it | No | The agent is missing reasons, not readable code. Add the context layer. |


The last row is the one most teams get wrong. A context problem follows the code into the new version.

## Do both, in the right order

When a rewrite is justified, the context layer comes first, not instead. **The Strangler Fig pattern** is a way to migrate a legacy system piece by piece behind a routing layer. Microsoft's version replaces "specific pieces of functionality with new applications and services" one at a time, so the old system keeps running while each piece moves. It lets teams "perform high-ROI replacements before low-ROI replacements" (Microsoft Learn, linked above). Each piece is a chance for the agent to ask why the old code behaves as it does before it writes the new one.

A workable order:

1. Connect the history. Give agents one source they can query for the PRs, tickets, docs and threads behind each module.
2. Pin current behavior. **A characterization test** is a test that records what the code does today, odd cases included. Have the agent write those first. Without a check to run, Anthropic warns, "that makes you the test suite" (Claude Code best practices, linked above).
3. Pick the first slice by return on effort, not by how ugly it looks.
4. Port one slice, compare behavior, then move to the next.

Unblocked is one way to do step 1. It is a context engine that reasons across code, PRs, issues, docs, Slack or Teams and incidents. Its `context_research` tool returns "a synthesized answer with citations" over MCP ([Unblocked MCP docs](https://docs.getunblocked.com/unblocked-mcp/mcp-overview)). Engineers and agents reach it from Claude Code, Cursor, GitHub Copilot, VS Code, JetBrains and Slack, and with Data Shield on for a source, answers only contain what the asking engineer is authorized to see there ([Unblocked Data Shield docs](https://docs.getunblocked.com/team-settings/data-shield)). For the history side in depth, see [why was this built this way](https://getunblocked.com/blog/why-was-this-built-this-way/). For the setup steps in one stack, our answer on [giving Claude Code context for a legacy .NET monolith](https://getunblocked.com/answers/claude-code-legacy-dotnet-monolith-context/) walks through them. When you do modernize, the [legacy code modernization guide](https://getunblocked.com/blog/legacy-code-modernization/) and [refactoring legacy code with AI agents](https://getunblocked.com/blog/refactoring-legacy-code/) cover the full plan.

## A test before you decide

Take the last five changes an agent got wrong in the legacy code. For each one, ask whether a cleaner version of the same code would have prevented the mistake, or whether the agent needed a fact that lives in a PR, a ticket or someone's memory. If most answers are the second kind, a rewrite will not fix them. Connect the history, rerun the same five tasks, and decide on the rewrite with that result in hand.

## Read more

- [AI-Powered Legacy Code Modernization: The Complete Guide (2026)](https://getunblocked.com/blog/legacy-code-modernization/)
- [How to Refactor Legacy Code with AI Agents (2026)](https://getunblocked.com/blog/refactoring-legacy-code/)

## Related answers

- [Is an LLM-maintained wiki in git a better fix than a context tool for engineering knowledge?](https://getunblocked.com/answers/llm-maintained-wiki-vs-context-tool/)
- [How do we drive adoption of an AI coding tool from a third of engineering to everyone?](https://getunblocked.com/answers/drive-ai-coding-tool-adoption-across-engineering/)
- [How do I make sure Claude actually calls the context MCP without every engineer editing their CLAUDE.md?](https://getunblocked.com/answers/make-claude-call-context-mcp-without-editing-claude-md/)
- [Atlassian Rovo MCP versus a dedicated context tool for Confluence, Jira and code?](https://getunblocked.com/answers/atlassian-rovo-mcp-vs-context-tool/)