Essay

Comprehension debt: what AI-written code actually costs

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.

The decoupling

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 debt in September 2025 — what happens “when teams produce code faster than they can understand it” — and Addy Osmani carried it to a much wider audience in March 2026, defining it as “the growing gap between how much code exists in your system and how much of it any human being genuinely understands.”

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 observable. A definition you cannot check is a phrase, not an instrument, and a phrase will not survive its first argument with a skeptical staff engineer. So everything below is about the version you can actually check: not whether anyone understands a file, but whether anyone has recently written, reviewed, or explained it. That is a weaker claim on purpose. It is also the only one we can show our work for.

Why “tech debt” doesn't cover it

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.

Why it's been invisible

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.

The interest payments

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:

• The incident. Debugging is comprehension paydown at the worst possible price — acquired under pressure, at 2am, with customers waiting. Every incident in un-understood code is the team buying back, at a premium, understanding it never acquired at merge time.
• The next change. You cannot meaningfully review a diff against a baseline you don't understand. Un-understood code degrades the review of everything that touches it — which is how comprehension debt compounds: blind spots make the code around them harder to safely change, which gets delegated to the agent, which deepens the blind spot.
• The departure. When someone leaves, teams have always lost understanding. Now they lose the last human who had any — and exit interviews don't capture what nobody realized only one person knew.
• The onboarding. New engineers learn codebases from people who understand them. An AI-native codebase can reach the state where there is no one to learn from — the corpus grew faster than any human's model of it.

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.

Can you actually measure understanding?

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.

Here is the narrower half of that, running: the share of a repository no human has written or prompted in 180 days, from git alone, with the clock pinned and the command to re-run it yourself. It is not comprehension debt — git keeps no review record, so it can say who has stopped touching code and not who understands it. It is the part of the record git does keep.

git clone --filter=blob:none https://github.com/react/react.git
npx fathohm read react --now 2026-08-12T00:00:00Z

The same measurement across the 100 most-starred repositories on GitHub, and what it says when you read across them: the distribution has almost nothing in the middle, and how old a repository is predicts its share far better than how popular it is.

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:

• Deterministic. A comprehension score that comes out of a model's vibes is unfalsifiable, and unfalsifiable metrics get ignored. The same history must always produce the same number.
• Decomposable. Every score must break into the factors that produced it. A number that can't explain itself won't be trusted, and a trust metric that isn't trusted is nothing.
• Disputable. The methodology should be public, and where the measurement rests on a judgement about people, that judgement has to be correctable by them. Fathohm gets this half right today: identity corrections — this address and that handle are the same person — are stored as events rather than edits, so a correction is part of the record instead of a change to it. Correcting an authorship label itself is not built yet. Wrong-but-inspectable beats unmeasured; wrong-and-uncorrectable is the version to be nervous about.
• Decaying. Understanding fades. Whatever you knew about a module a year ago, you know less now — the metric has to say so, which means comprehension is re-earned, not banked.
• Verified by someone else. Any proxy will eventually be gamed — review-theater to farm review-depth is the obvious move the moment a score matters (Goodhart guarantees it). The anti-gaming mechanism is periodically asking a real human a real question about the code. But the asking is only half of it: a check scored by the person taking it is the easiest thing on this list to game, and the only one where gaming it requires no effort at all. Verification counts when a teammate who did not write the answer reads it.

Comprehension debt, cognitive debt, and what a record can measure

The naming is worth being precise about, because the terms are close and the credit is not ours to hand out. Jason Gorman coined comprehension debt on 30 September 2025; Addy Osmani carried it to a much wider audience in March 2026. Those two roles are not interchangeable and the order matters: Gorman published first, Osmani is how most people met the phrase.

Cognitive debt is a different term with its own life, and at the moment a louder one — it draws the bigger threads and the bigger numbers. It is aimed at roughly the same worry, and its name points at the same unobservable place: a cognitive load is a state of a person. That is not a criticism of the phrase. It is the reason we could not build an instrument on it.

Because the same objection lands on both definitions, including the one this page takes its name from. “Faster than they can understand it” and “genuinely understands” are descriptions of what is in an engineer’s head, and no record contains that. Nobody has surveyed your team, and a survey would not settle it either. A definition that cannot be checked is a phrase — useful for naming the problem, useless for measuring it.

So Fathohm measures the record instead, and says so in the same breath as the number: who has written a file, who has reviewed it and how deeply, and who has explained it back, all inside a window. That is a weaker claim than either definition makes, on purpose. It is also checkable line by line, which is the only version of this that survives an argument with the engineer whose file it is describing.

What to do about it (with or without tooling)

You can start managing comprehension debt tomorrow with no new tools:

1. Give agent-written code a human author-of-record — someone who accepts “I can explain this” as part of merging it, and knows they're accepting it.
2. Ban the silent approval for agent PRs. If the review has no substantive comment, the team's comprehension of that code is exactly what it was before the review: zero.
3. Ask the question out loud. In the next planning meeting: “which parts of our system does nobody here understand?” The silence after is the debt making itself audible.
4. Treat named blind spots as backlog items — an hour with the worst one, on purpose, is incident response bought at daytime prices.

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.

The code will keep getting written either way. Whether it keeps getting understood is now a choice.