Comprehension debt: what AI-written code actually costs — Fathohm<br>Sign inGet your Map →GalleryThe dark indexHow it worksComprehension debtSign in

Essay<br>Comprehension debt: what AI-written code actually costs<br>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.<br>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.<br>The decoupling<br>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.<br>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.<br>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.”<br>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.<br>Why “tech debt” doesn't cover it<br>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.<br>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.<br>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.<br>Why it's been invisible<br>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.<br>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.<br>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...