Comprehension debt is measurable.
Every engineering team measures whether its code works. Almost none measure whether anyone can still fix it. Here is a way to measure it, and why we're publishing the method openly.
The Acadable team · · 6 min read
It is 2 a.m. and customers are being charged twice. The fix will turn out to be one line. Finding that line takes three days, because the engineer who wrote the retry logic left in the spring, and most of it was generated by an AI assistant anyway. The review that approved it took two minutes. Every dashboard the team owns said everything was fine.
This failure has a name now: comprehension debt: the gap between how much software a company runs and how much of it anyone genuinely understands. What it doesn't have yet is a number.
What we measure, and what we can't see
Engineering teams measure a great deal. Test coverage tells us how much of the code is checked by machines. The DORA metrics tell us how often we ship and how quickly we recover. Velocity, cycle time and review time fill the rest of the dashboard.
None of them can see understanding. A codebase can have high test coverage, elite deployment frequency and a review on every change, and still contain whole modules no current employee can explain. Industry writers have pointed out that today's team metrics are blind to this, and even engineering-analytics vendors concede there is no single metric for it.
That blindness used to matter less, because writing code was how engineers learned it. In 1985 Peter Naur argued that a program's real substance isn't its text but the theory in its programmers' heads, a theory that formed as a side effect of building. AI has removed the side effect.
The evidence is already in
In an Anthropic randomised trial published in January 2026, junior engineers who coded with AI scored 50% on a comprehension quiz, against 67% for those who coded by hand, and the widest gap was in debugging. The engineers who used AI to explain, not only to write, kept their understanding high.
Meanwhile AI writes a growing share of what ships: about 27% of merged code in early 2026 across more than 500 organisations, by one industry estimate, up from 22% a quarter earlier. Developers already spend most of their time (about 58%, in one field study) understanding code rather than writing it. And software depends on very few people: in a study of 133 popular open-source projects, 65% would stall if two or fewer key people left.
More code, written by tools, understood by fewer people, who leave.
Understanding leaves evidence
Comprehension seems unmeasurable: private, fuzzy, locked in people's heads. But understanding leaves evidence when you ask for it. An engineer who can say what their change does when the bank times out, or why the retry waits thirty seconds instead of three, has shown something no test can. So has the engineer who fixed the last outage in that module, or whose review caught a real problem.
Some evidence is weaker than it looks. Authorship used to be a decent proxy for understanding; in the AI era it isn't. Having written code, or prompted it into existence, proves little on its own. And all of it fades: what you understood about a module in March is less reliable in October, especially if the module has changed.
A number for it: comprehension coverage
So we propose a metric with the same shape as test coverage.
Comprehension coverage is the share of a team's critical modules that at least two current people have recently proven they understand.
Each person earns an understanding score from 0 to 100 on each module, from evidence. Explaining back your own change scores highest; completing a lesson, passing a refresh check, fixing an incident or giving a real review score less; writing code with no check scores almost nothing. A score of 60 or more counts as understanding. Scores decay with a half-life (90 days to start), and each successful refresh makes the next one come later, the way spaced repetition works for memory.
A module is healthy with two or more people, at risk with one, and red with none. Coverage is the share of critical modules that are healthy. It gives a CTO one number for the board, and a manager a map of precisely where the company is exposed. The full definitions, parameters and reporting rules are in the specification.
What it can't be allowed to become
A number about people invites misuse. If comprehension scores become a performance metric, engineers will game them (reasonably enough), and the measure will stop meaning anything. So the specification makes privacy a requirement, not a feature: individual scores are visible only to the individual, teams see module colours and counts, and the measure must not be used in performance reviews. The unit of concern is the module, not the person.
It also has limits worth stating. Two short questions can't capture deep understanding; many small signals over months, checked against what actually happens in incidents, can come closer. The specification asks every implementation to calibrate: healthy modules should get fixed faster than red ones, and if they don't, the weights are wrong.
Why we're publishing it openly
DORA's four metrics became the shared language of software delivery partly because they were defined in the open, so anyone could compute and compare them. Understanding deserves the same. We would rather the industry argue about a public definition than trust a private score, ours included.
So version 0.1 of the Comprehension Coverage specification is published today as a draft for comment. Depth, our product, implements it. Anyone else is free to.
Where to start
You don't need a tool to begin. Pick your most critical module and ask one question: how many people who work here now could fix this at 2 a.m.? If the answer is one, you have found your first red zone.