Originally published at fathohm.dev. The term "comprehension debt" is Jason Gorman's, from September 2025, carried by Addy Osmani in March 2026 — this piece is about measuring it.
There's a module in your codebase that shipped last month. It works. It has
tests. It passed review. And if it breaks at 2am, nobody on your team can
explain what it does.
Ask "who understands this?" about any given file in an AI-native codebase
and the honest answer, increasingly often, is no one — not because your
engineers got worse, but because the code stopped passing through their
heads on its way into production.
For seventy years, code getting written implied that somebody understood it. The implication was so reliable we never thought of it as an assumption:
writing code was the act of understanding a problem precisely enough to
express it. However bad the code, however absent the docs, there was at
minimum one person — the author, at the moment of authorship — who knew what
it did and why. Every practice we have for keeping teams oriented in a
codebase quietly leans on that floor: review assumes the author can defend
the change, onboarding assumes someone can explain the system, debugging
assumes a colleague to ask.
AI agents broke the implication. Code getting written and code getting
understood are now separate events, and only one of them is scaling. An
agent can produce in an afternoon what a team used to write in a month —
and the afternoon does not come with a month's worth of understanding
attached. The floor of "at least the author knows" is gone: for
agent-authored code, the author isn't on your team. It isn't anyone.
The gap between what a codebase does and what the humans responsible for it
understand needs a name, because things without names don't get managed. It
has one, and it has had one for a while. Jason Gorman named it comprehension We depart from both definitions in exactly the same one place, and it is the
reason this essay keeps going. Faster than they can understand it; genuinely understands — those are claims about states of mind, and minds are not
The obvious objection is that we already have a word for accumulated
codebase problems. But technical debt, as Ward Cunningham coined it, is a
property of the code — shortcuts embodied in the artifact itself, visible
in the artifact itself. You can point at tech debt in a diff.
Comprehension debt is a property of the team. The same file can be zero
debt on one team and a total blind spot on another, with not one character
different — because the debt isn't in the file, it's in the relationship
between the file and the humans accountable for it. That's why the
tech-debt playbook doesn't apply: you cannot refactor your way out of
comprehension debt. A perfect, clean, well-tested module that nobody
understands is still a liability — arguably a worse one, because nothing
about it looks wrong.
It also inverts the usual direction of concern. Tech debt worries about bad
code that works. Comprehension debt worries about good code that works —
right up until the moment it doesn't, and the team discovers the
understanding they assumed they had was never acquired by anyone.
Nothing in the modern toolchain measures understanding. We measure
coverage, complexity, velocity, deploy frequency, incident counts — every
property of the code and the process, and no property of the humans'
grasp of it.
The closest thing we had was code review, and review was never a
measurement — it was a sampling event. It checked comprehension exactly
once, at merge time, in one person, and we extrapolated "the team
understands this" from "one person approved it once." That extrapolation
was always generous. Under AI-native throughput it collapses: when the
diffs triple in size and quadruple in frequency, reviews get shorter, not
deeper. An approval with no comments on a four-hundred-line agent-written
change is not evidence of understanding. It's evidence of throughput.
Meanwhile the oldest team-risk heuristic we have quietly hit a new floor.
Bus factor — how many people can disappear before nobody understands a
system — used to be bounded below by one, because someone wrote the thing.
Agent-authored code breaks that floor. Somebody prompted it, so the count is
not zero; but a person who prompted a file and read the diff is not on the bus
the way an author is, and often nobody else is on it at all. The honest unit
turns out to be fractional rather than whole — which is uncomfortable, and is
the point. A heuristic that only counts whole people cannot see the state most
AI-native code is actually in.
Like financial debt, comprehension debt is cheap to carry and brutal to
service. The carrying cost is invisible: the code works, the dashboards are
green, velocity looks great. The interest comes due at specific moments:
None of this argues against AI-written code. The leverage is real and
teams that refuse it will lose to teams that don't. It argues that the
leverage has a cost that no current instrument shows, and costs that
nothing shows don't get managed — they get discovered.
The fair objection: understanding is a state of a human mind, and states of
minds don't show up in git.
Correct — so don't. Measure the record instead, which is what every serious
metric in engineering already does. The observable signals are real: whether
a human substantively reviewed a change (a comment trail, not a bare
approval), how recently a human meaningfully wrote in a file, how many
distinct humans have had real contact with it. None of those ask what anyone
knows. All of them are in your git history already.
The ground truth is checkable too, with one constraint that turns out to be
the whole game: the check cannot be self-administered. Asking someone to
explain what a file does on failure is a real test. Asking them to grade
their own answer is a survey, and a survey attached to a number people care
about is just a slider they can move. The answer has to be read by someone
who did not write it.
What matters more than the choice of signals is the discipline around
them:
You can start managing comprehension debt tomorrow with no new tools:
What you can't do by hand is see the whole surface at once, watch it move,
or keep yourself honest about decay — the same reason nobody tracks test
coverage in a spreadsheet.
That's the part we built. Fathohm maps comprehension debt across a codebase
— deterministically, decomposably, disputably — at
fathohm.dev. The code will keep getting written either way. Whether it keeps getting
understood is now a choice.