Using AI to read legacy code: maps, documentation and business rules

Every modernization starts with the same question: what does this system actually do? The answers live in code written years ago, often by people who have left, in a language or framework the current team rarely uses, with documentation that stopped matching the code long ago. Reading it all by hand takes weeks. AI can do much of the first pass in days, and that changes what a modernization costs. It does not change who is responsible for the answers.

The useful way to think about it: AI writes the first draft of understanding; engineers turn it into knowledge.

What AI does well on old code

• Summarizing modules. Give a model a file or a folder and ask what it is for, what it reads, what it writes and what calls it.
• Mapping dependencies. Which modules call which, which tables each one reads and writes, which external services it talks to. Alongside static analysis tools, AI can draft the map and explain it.
• Tracing data flows. Follow one piece of data, such as an order or an invoice, from the screen where it is entered to every place it is stored, changed or sent.
• Drafting documentation. Explanations of setup, configuration, scheduled jobs and deployment steps that exist today only in someone’s memory or in a script nobody opens.
• Listing business rules. The conditions buried in the code: discounts that apply only on certain days, statuses that block an action, rounding that differs by product. Pulled out into a plain list, they become something the business can confirm or correct.
• Explaining unfamiliar languages and frameworks. An engineer can ask what an old construct or a cryptic configuration line means, and get a useful answer in seconds.

Where it goes wrong

• Confident mistakes. A model can describe what a function “probably” does based on its name, and state it as fact. In legacy code, names lie often: a function called “validate” may also save, send an email or change a status.
• Missing context. The model sees what you give it. Behaviour that depends on database triggers, configuration on the server, a scheduled job in another repository or data that only exists in production is invisible to it unless someone brings it in.
• Dead code that looks alive. Old systems carry code paths that have not run in years. A summary of the code is not a summary of the behaviour.
• Smoothing over oddities. The strange special case is often the most important business rule. A summary that tidies it away loses exactly what the rewrite must keep.

Verify every claim against the code and its behaviour

Each statement the AI produces should be marked as unverified until an engineer has checked it. Checking means two things:

1. Against the code. Open the lines the claim is based on. A good practice is to ask the model to cite file and line for every claim; a claim it cannot point to is a guess.
2. Against the behaviour. Run the system, read the logs, query a copy of the data. If the rule list says orders over a limit need approval, find an order that crossed it and see what happened.

Business rules need one more check: the people who run the process. Some rules in the code are deliberate, some are old bugs everyone works around, and only the business can say which is which.

The checked rules then become tests. A test that describes what the old system does, written before anything is replaced, is the most valuable thing this reading produces: it tells the new system exactly what it must keep doing.

Keep the outputs in the repository

Maps, summaries and rule lists are worth keeping only if they stay next to the code. Store them in the repository as plain text files, review changes to them like code, and note for each one whether it has been verified, by whom and when.

One practical rule before any of this starts: share the code only with AI tools your company has approved for that purpose, under terms that keep it out of model training. Old code often contains credentials, customer data in test fixtures and internal addresses; clean those out first.

Our modernization check is a quick way to see how ready your own system is.