Every engineer has met a cursed codebase. The file nobody edits without a small prayer. The function with a comment that says "DO NOT TOUCH" and no explanation of why. The module that works, mysteriously, and would apparently stop working if you looked at it too hard.
Japan has these too. The difference is age and scale. A lot of the systems quietly running this country — banks, insurers, government, manufacturing — were built in an era when the people who wrote them expected to maintain them until retirement. Some of those people have now retired. The systems have not.
I've spent about two decades as an engineer here, and my time has been split between two worlds. A lot of it has been new development — the kind of project where you get to make the mess yourself. But I've also worked inside the old systems, and the two feel nothing alike. Building something new is engineering. Working in a decades-old system is closer to archaeology: you're not writing software so much as excavating it, one layer at a time, trying to reconstruct the intentions of people you'll never meet.
The strata
Open an old Japanese enterprise system and you can read its history like sediment.
The bottom layer is the original build, often startlingly clean, because one team designed it under one coherent idea. Above that sits a decade of "just add a flag here" changes, each reasonable on its own, none of them aware of the others. Near the surface you find the recent panic layer: the workarounds added when something broke in production and had to be fixed by morning.
The comments are their own excavation. They're in Japanese, which is fine, except the variable names are in romaji — Japanese words spelled in the Latin alphabet — so you get things like torihiki_flg (transaction flag) sitting next to a comment explaining a business rule that the company stopped following in 2011. The rule is gone. The flag is load-bearing. Nobody knows why, and the person who did know is not answering email, because they left. I have lost real days to flags like that.
There's a phrase Japanese chefs use for a sauce that's been topped up and reused for generations: 秘伝のタレ (hiden no tare), the "secret sauce." It's meant as praise — depth you can't fake or rebuild from scratch. Legacy code is the accidental version of the same thing. Twenty years of additions, and no living person understands the whole flavor.
Why the digs run deeper here
Cursed legacy is universal. But a few things make the Japanese version particularly deep.
The big one is structure. A large share of enterprise systems here were built not by in-house engineers but by SIers — systems integrators — often through several layers of subcontracting. The company that owns the system, the company that designed it, and the company that maintains it today can be three different companies, across a gap of many years. The people who made the decisions and the people who now live with them were never in the same room. Knowledge that would have been tribal on an in-house team instead evaporated across contract boundaries.
The other thing is that Japan runs a lot of industries where "we'll rewrite it eventually" was never really on the table. Core banking, public infrastructure, long-lived manufacturing lines — these were built to run for decades, and they have. Stability was the whole point. The cost of that stability is that the code got old in place.
The cliff the government named
This got serious enough that the state gave it a name.
In September 2018, Japan's Ministry of Economy, Trade and Industry (METI) published a report that coined a phrase now familiar to everyone in the industry here: 2025年の崖, "the 2025 digital cliff." The argument was blunt for a government document. If Japanese companies didn't modernize their aging systems, the report warned, the country could lose as much as ¥12 trillion a year — very roughly $80 billion — between 2025 and 2030, from the sheer drag of maintaining the past.
The supporting numbers were just as pointed. By 2025, it projected, around 60% of Japanese firms' core systems would be 21 years or older. It warned of a shortfall of roughly 430,000 IT workers. And it described the legacy problem in three words that any archaeologist would recognize: 複雑化・老朽化・ブラックボックス化 — complex, aged, black-boxed. Its most quotable claim was that companies risk spending over 90% of their IT budgets just keeping the old thing alive, with nothing left for anything new.
Here's the part I find worth sitting with: that deadline has passed. We are now on the far side of the cliff the report named. Some organizations climbed down carefully. Many are still standing at the edge, patching, because the systems in question are the ones you cannot turn off to renovate. You don't get to close the bank to remodel the vault.
How you actually excavate
The archaeology framing isn't just a metaphor for how it feels. It's also, genuinely, how you should approach the work.
Read before you run. The instinct on a new codebase is to run it and poke at the behavior. On something this old, behavior lies — half of what it does is compensating for a problem that no longer exists. Read first. Treat the code as a document about the past, not a description of the present.
Distrust the strata. When you find something baffling, resist the urge to assume the original author was an idiot. The odd choice usually made sense against a constraint you can't see anymore — a hardware limit, a vanished business rule, a bug in a dependency three versions back. The weird code is an artifact. It records a condition, not a mistake.
Dig for the "why," and then write it down. The single most valuable thing you can add to a system like this isn't a refactor. It's a note explaining why something is the way it is, so the next person to dig here starts one layer further down than you did. Most of the pain in legacy work is knowledge that was never recorded. You can't fix the whole thing, but you can stop the erosion.
There's a new tool on the dig, and it's the first genuinely new one in a while. Feeding a bewildering old function to an AI model and asking "what does this actually do, and why might it have been written this way?" turns out to be a decent excavation technique. It won't recover the lost business context — no model knows why your company abandoned a rule in 2011 — but it's very good at reading a wall of torihiki_flg logic and handing you a hypothesis to test. Think of it as a sharper trowel. It digs faster; it still can't tell you what the layers mean. That part's on you.
The part that stays with you
The strange reward of this work is that it teaches you to read software as human behavior. Every ugly patch was somebody's Tuesday-night deadline. Every dead flag was a rule someone once cared about enough to encode. You start to see the codebase less as a machine and more as a place people passed through, each of them leaving the problem slightly more habitable than they found it, and slightly harder to understand.
Japan's cliff has a date on it. But the truth underneath the policy report is one every engineer eventually meets: the past doesn't get cleaned up. It gets inherited. The job is just to leave a better map for whoever digs here next.
Sources
Facts on the METI "2025 digital cliff" report (in Japanese):
TL;DR
- Maintaining old Japanese enterprise systems is less like engineering and more like archaeology: you excavate intent from people you'll never meet.
- The layers run deep here because of the SIer/subcontracting structure (builder, owner, and maintainer are often different companies) and industries built to run for decades.
- In 2018, Japan's METI named "the 2025 digital cliff": up to ¥12 trillion/year in losses (2025–2030), ~60% of core systems 21+ years old by 2025, a ~430,000 IT-worker shortfall, and legacy that's "complex, aged, black-boxed."
- That deadline is now behind us. Many systems still sit at the edge, because you can't switch them off to renovate.
- How to dig: read before you run, treat weird code as an artifact (not a mistake), and record the "why." AI is a good new trowel, not a replacement archaeologist.
Top comments (0)