Reading the Legacy Codebase: Agents That Extract Business Logic from COBOL, AS/400, and Old Java

A legacy codebase reading agent starts with a premise most AI content ignores: the hardest part of modernizing a legacy system isn't the rewrite. It's reading what's already there. A payroll engine that processes $200M a year has accumulated thirty years of special cases, branch logic for one customer, deduction rules that predate current tax law, and a PERFORM call tree that nobody has drawn out in full since 2003. One person understands it. He retires in eight months. Then the organization is flying blind.

Most AI-assisted development articles assume greenfield. You have clean requirements, modern tooling, and a team that can read every file. The legacy comprehension problem is structurally different. There are no specs that match the code. The documentation describes what the system was supposed to do in 1994. The original developers are gone, retired, or unavailable. The business rules — the actual logic driving actual money — live entirely inside programs written in a language 85% of universities stopped teaching in the 1990s.^[5]

The good news: AI code-comprehension agents can extract business logic from these systems with better fidelity than a six-month consulting engagement, if set up correctly. The phrase "if set up correctly" is doing enormous work in that sentence. This piece is about what correct looks like — five extraction patterns that ground every claim in source code lines and stop confident hallucinations before they corrupt your knowledge base.

The rewrite conversation and the comprehension conversation are often treated as the same conversation. They aren't.

A rewrite problem is: given clear requirements, rebuild this functionality in a modern language. A comprehension problem is: we don't have clear requirements, the only source of truth is decades-old code, and we need to extract the requirements from the implementation before we can do anything else. One assumes you know what the system does. The other assumes you don't.

Documentation drift makes this worse than it sounds. Most enterprise legacy systems were documented at some point — and that documentation is now wrong in ways that aren't labeled. The comments describe what a developer intended to write in 1998, not what the code does after fifteen years of patches. The README describes the interface before the last major refactor, which happened in 2011. The flowcharts in the wiki describe a processing flow that was superseded by a hotfix in 2017 that nobody documented at all. The actual business rules have to be inferred from the code itself, with no reliable external reference to validate against.

This means the comprehension problem requires a fundamentally different approach than generating new code. It requires extraction with evidence: every business rule you surface needs to trace back to specific lines in specific files, or it's not a business rule — it's a guess about what the business rule might be. That distinction separates functional knowledge bases from confident-sounding fiction.

What separates extraction that works from extraction that produces plausible-sounding garbage is a single discipline: every claim traces to a source line. An uncited rule is a hallucination. It may be a correct hallucination, but you have no way to know that, which means you can't trust it. The five patterns below all enforce grounding differently, but they all enforce it.

The most common mistake teams make when they first try AI comprehension on a legacy codebase is the context dump. They feed the entire COBOL source file — or worse, multiple files — into the model and ask "what does this do?" The model answers confidently. The answer is wrong in specific, critical ways. The model hallucinated behavior for the section it couldn't attend to closely at the end of the context window, and nobody knows which parts are fabricated.

Function-level summarization works differently. You extract a single COBOL paragraph, PERFORM block, or RPG subroutine — the smallest coherent unit of behavior. You then retrieve and inline the copybooks it references and the immediate callees it invokes. The model sees exactly enough context to summarize what this specific unit does, with its full dependency chain visible, and nothing else.

The critical discipline: the prompt must require the model to cite the paragraph name, the line range, and any copybook it relied on in its summary. A summary without that citation cannot be verified, and an unverified summary is indistinguishable from a hallucination. The moment you establish citation as a hard requirement in the prompt, you discover which summaries the model is confident about and which ones it's guessing. The guesses stop masquerading as facts.^[9]

Business rule extraction is the pattern with the highest upside and the highest failure rate. The upside: a structured, queryable catalog of what the system actually does, written in plain language that business stakeholders can review. The failure rate when done naively: a catalog full of plausible-sounding rules that mix what the code does with what the analyst assumed it does.

The grounding discipline for rule extraction is non-negotiable: every extracted rule must include the source file name, the line range that implements it, and a verbatim snippet of the code that supports the claim. A rule that reads "Premium calculations apply a 12% loading for customers in the high-risk tier" is useless without PREMIUM-CALC.CBL:1203-1241 and the relevant MULTIPLY statement. With the citation, the business analyst can validate it in five minutes. Without it, the validation never happens, and the rule quietly corrupts the knowledge base.^[10]

Run the extraction twice on the same source. If the two runs produce different rules from the same code, your grounding is broken — the model is generating rather than extracting. Treat extraction as a deterministic function: same input, same output. Variance is a signal of hallucination.

Data lineage mapping is the most technically demanding extraction pattern, and the one with the clearest downstream value. Most legacy systems don't process data in a single program — they pass it through a chain of COBOL programs, RPG procedures, JCL job steps, and shared copybooks. A field named CUST-BALANCE might be set in ACCT-LOAD.CBL, transformed in BALANCE-ADJ.CBL, fed through a copybook CUSTMAST.CPY used by twelve programs, and ultimately written to a report by RPT-STMT.CBL. No single developer holds that chain in their head.

A data lineage agent builds this graph systematically. It starts from a target field — say, the field that feeds the dollar amount on the customer statement — and traces backwards: what assigns this field? What reads the assigning program's output? What copybook defines the shared structure? The agent emits a graph where every edge cites the program and line number where the data moves. The result isn't a summary — it's a map you can query. "Show me everything that writes to CUST-BALANCE before the statement run" becomes answerable without a human tracing CALL statements by hand.^[12]

The failure mode to guard against: copybook expansion. COBOL programs use copybooks as shared struct definitions, and the same field name can appear in multiple copybooks with different storage layouts. A lineage agent that doesn't resolve copybook expansions before tracing field references will produce a broken graph — edges that claim a field is shared between programs when they're actually independent fields with the same name. Resolve all copybooks before any lineage analysis begins. This is not optional.

If there is one pattern that separates modernizations that succeed from ones that quietly fail for six months after go-live, it's this: generate a behavioral test suite from the legacy system before you write a single line of the new system.

The test suite is not documentation. It's a regression harness derived from observing what the legacy system actually does with real inputs. You run the extraction agent against the codebase to identify the significant behavioral branches. You instrument the legacy system to capture input/output pairs for each branch — ideally from production traffic, or from a test data set built to cover the branches the agent identified. You generate test cases that assert the observed behavior. Then you run those test cases against the legacy system to verify they're correct. The suite is green against the thing you're replacing.

Now you have a definition of correct behavior that doesn't depend on anyone's memory or any documentation that may be wrong. When the new system passes the suite, you have evidence — not faith — that it behaves equivalently. When it fails, you have a precise description of where it diverges. The business analyst reviewing the divergence is looking at a specific input and a specific output difference, not a vague "something seems off" from a user in UAT.^[9]

The teams that skip this step discover their requirements during production incidents. The deduction branch that only fires for one customer processes $4M a year. It wasn't in any spec. It wasn't in any test the new system had. It shows up three months after cutover in a payroll discrepancy.

The strangler fig migration pattern — routing new traffic to a modern service while the legacy system handles the rest — requires a clean interface definition between the two. That interface can't be guessed or invented. It has to match what the legacy program actually accepts and returns, or the routing layer becomes a translation layer that accumulates its own bugs.

Interface synthesis extracts the API contract from the legacy program's entry points: the LINKAGE SECTION in COBOL, the parameter lists in RPG procedures, the method signatures in legacy Java. The agent maps each parameter to its copybook definition or class field, preserves the original data types and lengths, and generates an OpenAPI specification or equivalent that can drive the modern service's contract. Every field in the spec traces back to a named field in the legacy source — no invented field names, no guessed types. The strangler fig router is built against this spec, not against an assumption.^[6]

This is the shortest path from legacy comprehension to active migration. Once you have a grounded interface spec, you can build the new service and route a subset of traffic to it while the legacy system handles the rest — the coexistence playbook in practice.

The tool market for legacy comprehension has expanded significantly in the past eighteen months. Every major cloud vendor has a product, IBM has a mainframe-specific offering, and a new category of code intelligence platforms has appeared. The honest assessment: most of these tools help with the comprehension problem. None of them solve it without a grounding discipline imposed by your team. The tool is a retrieval and generation layer. The grounding is your responsibility.

The reason most modernizations fail isn't the technology. It's that the system was rewritten before it was understood. Confidence filled the comprehension gap — developer confidence, consultant confidence, project manager confidence that the legacy system was simpler than it looked. It was never simpler than it looked. Thirty years of business logic, edge cases, and undocumented behavior accumulated in that COBOL because the business kept changing and the system kept being patched to match. Read first. Map the rules. Generate the tests. Then decide whether to rewrite.

The extraction patterns in this piece are not new research — they're disciplines that careful teams have applied to legacy systems for years, now executable at speed with AI comprehension agents. Gartner's projection that 40% of legacy modernization projects will incorporate AI-assisted reverse engineering by 2026 — up from under 10% in 2023 — reflects a genuine shift in what's practical.^[10] The tools are good enough. The constraint is the discipline to use them correctly: ground every claim, validate every rule, and don't mistake a fast extraction for a correct one.