AI and legacy code: migrating and documenting existing systems

Taking on legacy code isn’t just about an old language. It’s mainly a black box: code no one truly understands anymore, packed with implicit business rules and lacking documentation. AI fundamentally changes the game here, understand, document and migrate the existing codebase far faster. But it also changes the game for the worse if you ask it to “rewrite everything in modern” on its own. Our stance is clear: AI is an accelerator, not a decision-maker. Here’s how to use it seriously.

The real legacy blocker: understanding, not the language

Many leaders assume a good developer can take over any code. In theory, yes. In practice, the issue isn’t syntax, it’s the lost context. An old system contains business rules that were never written down elsewhere: why this discount is calculated that way, why this customer goes through a special flow, why this data is copied across three tables. When the original developer is gone and documentation is missing, the code becomes unreadable not because it’s complex, but because its intent has vanished. This is exactly where AI is most valuable.

Take a 400-line function that calculates a price. A human might spend half a day untangling its logic; a model can summarize it in seconds: “apply a 5% discount beyond 10 units, except for export-flow customers, where manual validation is required.” Of course, you still need to verify the accuracy, but you start with an understanding in minutes instead of days. This acceleration also makes a technical debt audit far faster and less costly than before.

What AI excels at with old code

When it comes to understanding and reading, recent models are remarkable:

• summarize and explain complex functions in plain language;
• trace dependencies and reconstruct data flows;
• extract business rules buried in the code and rephrase them into plain sentences;
• generate initial documentation: READMEs, data schemas, module descriptions;
• produce characterization tests that lock in the current behavior;
• suggest a target or a translation into a more modern language.

None of these tasks replace an architectural decision. But all of them save considerable time on the most tedious part of the takeover: making sense of the existing system.

A useful caveat goes with that list: even on the most favourable task, summarising a document handed to it, a model still introduces information absent from the source. Vectara's public leaderboard measures, in its 11 May 2026 update, between 1.8% and 6% of occurrences depending on the model. Applied to a pricing function, that means a plausible summary can contain a rule that does not exist. Hence the only method that holds: have every extracted rule reviewed by someone able to find the corresponding line. Leaderboard: Vectara's Hallucination Leaderboard.

Documenting the existing system: the best first step

Before even discussing migration, the most immediate benefit of AI for legacy systems is documentation. Having AI generate, and then have engineers review, a module map, a data schema, and a list of business rules turns a black box into a readable system with minimal risk. Nothing is changed: the system is simply made understandable. This is often what unlocks everything else, as a team that finally understands its application dares to evolve it again. And this documentation becomes the reference for the rest of the project.

The other advantage of this first step is that it is risk-free: you read, you describe, you alter no behavior. It’s therefore the best way to gauge the real value of AI for your code before committing to more sensitive stages. And the documentation produced has lasting value: it reduces dependency on a single person and lowers the "bus factor" that threatens so many legacy systems.

Migrating with AI, without vibe coding

This is where everything is decided. Asking an AI to "rewrite all the old software in modern code" in one go is a bad idea: it will produce code that looks clean, but may overlook a rule, mishandle an edge case, oversimplify a process that shouldn’t be, or introduce a flaw. The right approach is methodical: start with characterization tests, a "golden master" that records what the old system produces for real cases, ensuring the new one delivers exactly the same results. Then migrate module by module, with human review and business validation at each step. AI proposes, generates, accelerates; the engineer verifies, tests, and decides.

Migrating does not mean rewriting everything at once: progress is made in reversible increments, as we detail in modernizing a legacy application without rewriting everything. This is the exact logic behind our project and code takeover missions assisted by AI: recover the value of the existing system without inheriting its pitfalls.

That approach has had a name for twenty years, the strangler fig, described by Martin Fowler: you grow the new system around the old one, function by function, until the old one can be removed. Its main benefit is financial rather than technical, at every stage the system stays in production and the work can stop without a total loss, whereas a full rewrite produces no value until its final week. Reference: the Strangler Fig pattern.

Safeguards: why AI doesn’t fly solo

An AI doesn’t know your company’s priorities. It can’t, on its own, determine what’s critical or which business impacts are acceptable. It may hallucinate a rule, invent one that doesn’t exist, or silently remove an essential one. Hence three non-negotiable safeguards: tests that prove behavior is preserved, a business validation by the people who actually use the system, and an architecture review by engineers. To properly integrate AI with your code and tools, rather than resorting to risky copy-paste, standards like the Model Context Protocol provide controlled and auditable access. Tooling matters as much as the model.

Two public measurements back that framing, and they cut against the prevailing discourse. The 2024 DORA report concludes that AI adoption "significantly increases individual productivity" while "negatively impacting software delivery stability and throughput". And METR's 2025 study, on 16 experienced developers across 246 issues in code they already knew, measures 19% more time taken with AI tools, while participants believed they had gained 20%. For legacy work that result is encouraging, provided you draw the right conclusion: the gain is real on understanding unfamiliar code, much less so on modifying code you already master. Sources: DORA 2024 and the METR study.

Our approach: understand before rebuilding

At Scroll, AI is never an end in itself: it’s a lever that senior engineers use where it delivers real value, reading legacy code, documenting, extracting logic, generating tests, or preparing a new architecture. We understand first, rebuild second, and validate in real conditions. This is our difference: an engineering agency that owns technical decisions, not a pipeline that outsources them to a model. This rigor is part of a broader application modernisation approach, and complements our in-depth series on modernising a legacy IT system with AI.

Legacy code to take over, document, or migrate? We’ll tell you honestly what AI can speed up, and what requires real engineers. Let’s talk.