Decoding Legacy Systems No One Understands with LLMs: A New Approach to the “Black Box” Problem

Every large Japanese enterprise has at least one system like this. It runs the business. It has run the business for thirty years. It works. And there is no longer a single person in the building who can tell you, with confidence, what it does.

The documentation describes a version replaced in 2009. The engineers who wrote it have retired. The SIer who maintained it has rotated its staff four times. What remains is behaviour — observable, load-bearing, unexplained.

Three sentences we hear in the first meeting — composite paraphrases of a recurring conversation, not quotations from any single client:

That last one is the real problem. Before a modernisation project can be scoped, someone has to read the system — and reading it has historically meant paying a team of engineers a year to do archaeology. This article is about why that discovery phase is now a different kind of problem, what an LLM can and cannot do to it, and the methodology that separates a useful documentation exercise from a confidently wrong one.

This is part of our ongoing series on deploying enterprise AI under real-world constraints in Japan. The previous post argued for small on-premise models where data cannot move. This is the opposite case: a task where you want the largest model you can legally point at the problem.

01  The Constraint Is Comprehension, Not Code

The framing that has dominated this conversation for eight years is METI’s 2018 DX Report and its 「2025年の崖」 — the warning that unaddressed legacy systems could cost the Japanese economy up to ¥12 trillion a year from 2025 onward. The figure is widely quoted and, at this point, widely stale.

The more useful question is what happened after the deadline passed, and there is a current answer. METI convened a レガシーシステムモダン化委員会 (Legacy System Modernisation Committee), whose 総括レポート was published on 28 May 2025. It carries a market survey of roughly 4,000 user and vendor companies — 799 responses, fielded 17 December 2024 to 14 February 2025 — and reports that 61% of user companies still hold legacy systems, rising to 74% among large enterprises. The picture is not a cliff anyone fell off; it is a plateau nobody has climbed.

Two details in that report matter more than the headline percentage.

First, its definition of a legacy system does not turn on age at all. It names five factors, and one of them is ブラックボックス化 — specifications and design documents not maintained, migration and rebuild obstructed, maintenance become 属人的 (dependent on specific individuals). The problem this article is about is not an unfortunate side effect of old systems; in the government’s own taxonomy it is one of the defining properties of the category.

Second, the same report explicitly calls on vendors to develop 生成AIによるレガシーコード解析 — generative-AI legacy code analysis — on the express grounds that labour-intensive migration approaches will soon reach their limit as the IT workforce shrinks. The approach this article describes is not a vendor’s clever idea; it is the direction the policy documents are pointing.

Underneath the percentages sits a knowledge-transfer problem with a hard clock on it. The engineers fluent in COBOL, PL/I, and the in-house job control that glues these systems together are reaching retirement age now. The difficulty is not a shortage of capable engineers — plenty of skilled people work productively in these technologies, and the languages themselves are learnable. The difficulty is that what these systems demand is largely undocumented and organisation-specific: forty years of accumulated decisions, exceptions, and workarounds that exist in no manual and are transferable mainly by working alongside the people who hold them. Neither hiring nor training shortcuts that, because there is no external curriculum for one company’s undocumented batch schedule. METI’s report names the same mechanism, listing the ageing and departure of engineers alongside the absence of design documentation. Every retirement that happens without a structured handover takes comprehension with it.

So the binding constraint is not that the code is old. Old code that is understood is merely a maintenance cost. The binding constraint is that comprehension is decaying faster than the code is being replaced, and every year of delay makes the next attempt more expensive than the last.

02  Why This Is Genuinely an LLM Problem

We are on record arguing against reaching for an LLM by default. This is the case where it is the right instrument, for a specific reason.

Legacy comprehension is not a code-generation task. It is a reading comprehension task over a large, messy, low-signal corpus in a dead dialect — 200,000 lines of COBOL, forty years of stored procedures, JCL, batch schedules, and comments in Japanese written by people who assumed the reader shared their context. Static analysis handles the mechanical part well: it can build a call graph and trace a variable. What it cannot do is answer the question the client actually has — “what business rule is this implementing, and why?“

That needs a model that can hold a large amount of unfamiliar context at once, tolerate inconsistency, and read Japanese comments alongside English identifiers. It is precisely the shape of task frontier LLMs became good at, which is why the economics changed here before the tooling did.

The second shift is agentic. Earlier attempts required the codebase be cleaned and normalised before analysis — its own multi-year project, and the reason most of these efforts died at the proposal stage. An agentic system navigates a messy repository the way an engineer does: follow a call, open the referenced copybook, check the job schedule, come back. It works on the code as it actually exists.

One caveat governs everything below. In finance and the public sector, this code usually cannot be sent to an overseas API — but it is worth being precise about why, because the reasons are not interchangeable and clients notice when a vendor blurs them.

Source code is not personal information, and APPI does not restrict it as such. The binding constraints on the code itself are almost always contractual and policy-based: client NDAs, subcontracting and re-delegation terms, sector security guidelines, and internal rules that prohibit source leaving the corporate network. APPI becomes relevant at a different point — when personal data is actually present in what you transmit, which in practice it often is: personal data embedded in configuration, test fixtures, log samples, seed data, or production-derived extracts travelling alongside the code. Those are separate obligations, with separate owners inside the client, and treating them as one thing tends to produce a review that fails on the detail you glossed over. Either way, the architecture must support private deployment (VPC-hosted frontier models, or on-premise open-weight models) as the default, not the exception.

03  The Hero Case: The Settlement Batch Nobody Will Touch

The example that follows is an illustrative composite — the recurring shape of these systems, assembled to make the methodology concrete. It is not a description of a specific client engagement, and the quantities are indicative rather than measured.

Take a nightly batch job of a few tens of thousands of lines that reconciles transactions and writes to the ledger. It has run without incident for two decades. It may encode several hundred business rules, of which only a fraction are documented. Some implement regulation that has since changed; some implement a workaround for a hardware limitation that no longer exists. Nobody can tell which is which.

Nobody will touch it either, because the downside of a wrong change is a regulatory incident and the upside is a slightly cleaner codebase. So it sits there and the organisation routes around it — which is exactly how a black box becomes load-bearing.

The goal is not to migrate it on day one. It is to make it legible: to produce, in weeks rather than quarters, a documented inventory of what it does, what depends on it, and which rules are still live — so the migration decision can be made on evidence instead of fear.

04  Architecture: Extraction, Then Verification

The pipeline is deliberately unglamorous, and it has one non-negotiable property: nothing generated by the model is treated as fact until something other than the model has confirmed it.

Four things matter more than they look:

Static analysis runs first, not instead. The call graph, dependency map, and dead-code detection come from deterministic tooling. That is the skeleton the model reasons over, and also the check on it — if the LLM describes a data flow the call graph does not contain, that is a caught hallucination rather than a shipped one.

Output is structured, not prose. The model emits a rule inventory with fields — rule ID, source location, plain-language description, inputs, outputs, confidence, open questions — not a narrative document. Structured output can be diffed, reviewed row by row, and tracked to closure. A forty-page generated document cannot be verified by anyone, which is why it never is.

Confidence is a first-class field. Low-confidence rules route to human review first. This inverts the usual failure mode, where reviewer attention is spread evenly across output that is 95% trivially correct and 5% quietly wrong.

The human checkpoint is architectural. A domain expert — often a semi-retired engineer brought back for exactly this — signs off on the inventory. It is the highest-value use of a retiring expert’s remaining time: not writing documentation from scratch, which is slow and which they will not do, but correcting a draft, which is fast and which they will.

05  Methodology: How We Reverse-Engineer Safely

Scope by blast radius, not by size. Start with the subsystem whose failure would be most expensive, because that is where comprehension is worth the most — not with the easiest module, which is the instinct and which produces a successful pilot that proves nothing.

Behaviour-diff against production behaviour is the only proof that counts. Generated documentation is a hypothesis. The test is to run the legacy system and the candidate replacement against the same inputs and diff the outputs field by field.

Those inputs have to be production-derived rather than synthetic, because synthetic cases only exercise the behaviour someone already knew to write down — which is precisely not where the risk is. In a regulated environment, production-derived does not mean production data copied into a test rig. It means an extract handled under the client’s own data-handling rules: masked or anonymised wherever personal data is present, scoped to the fields the diff actually needs, access-restricted to the migration team, retained for a defined window, logged, and used under explicit authorisation from whoever owns that data internally. Where no extract can be approved at all, the harness runs inside the production boundary — the candidate implementation shadows live traffic in place, and only the diff results leave. We do not migrate anything for which we cannot build this harness under those controls. That rule has ended engagements, and it should.

Strangler fig, never big bang. Route one function at a time to the new implementation with the legacy path still live and comparing in shadow mode. The old system stays authoritative until the new one has matched it on real traffic for a meaningful period. Slower to demo, dramatically cheaper to be wrong in.

Documentation is the deliverable, even if migration never happens. A verified rule inventory has standalone value: it makes the system maintainable, de-risks the next audit, and means the next retirement is not another permanent loss.

06  Honest Limits — Where This Does Not Apply

The failure mode of this technology is specific, and it is worth naming precisely: an LLM reading unfamiliar code produces fluent, plausible, confidently wrong explanations. It will describe what code of that shape usually does. When a routine contains a twenty-year-old undocumented workaround — which is the exact thing you are paying to discover — the model’s prior actively works against you. It is at its least reliable precisely where it is most needed.

Concretely, this approach does not carry its weight when:

▪ You cannot build a behaviour-diff harness. No production traffic to replay, no test environment, no way to compare. Without a verification path you have generated plausible fiction about a system that runs your business. Stop.

▪ The system is small enough to read. If a maintainer is still employed and a small team could read the thing end to end in a matter of weeks, doing exactly that is cheaper and more reliable than building a pipeline around it. Where that threshold falls depends on the language, the density of the code, and how much of the original team remains — we size it per system rather than against a line count.

▪ The real dependency is a person, not the code. If the critical knowledge is operational — which exception is safe to ignore at month-end — it is not in the source, and no amount of code comprehension recovers it. That is a tacit-knowledge capture problem, and a different engagement.

▪ The code cannot leave the network and the on-prem hardware is not there. Comprehension quality is more model-dependent here than in most tasks. A small local model produces a worse inventory, and pretending otherwise is how a compliance constraint becomes a quality problem nobody admits to.

▪ Regulatory sign-off requires human-authored evidence. In some contexts AI-generated documentation cannot be the artefact of record regardless of its accuracy. It can still accelerate the humans who write it — but scope it as acceleration, not as the deliverable.

07  Summary

▪ Japan’s legacy problem has moved past its headline deadline without being solved: METI’s May 2025 committee report finds 61% of user companies still holding legacy systems, and 74% of large enterprises.

▪ The binding constraint is comprehension, not code age — ブラックボックス化 is one of the defining factors in METI’s own definition of a legacy system, and the same report calls for generative-AI legacy code analysis by name.

▪ The knowledge at risk is undocumented and organisation-specific, so retirement without a structured handover removes it permanently. This is a handover problem, not a shortage of capable engineers.

▪ Legacy comprehension is a genuine LLM task — large-context reading over a messy corpus in a dead dialect — and agentic systems can now navigate the code as it exists rather than requiring it be cleaned first.

▪ The architecture that works puts static analysis first, emits a structured rule inventory rather than prose, treats confidence as a first-class field, and puts a domain expert’s sign-off in the path.

▪ Nothing migrates without a behaviour-diff harness built on production-derived inputs under the client’s data-handling controls, and migration proceeds strangler-fig with the legacy path live in shadow.

▪ The honest limit: an LLM reading unfamiliar code is confidently wrong exactly where the undocumented workarounds are. Verification is not a phase of this method — it is the method.