{"slug": "comprehension-debt-what-ai-written-code-actually-costs", "title": "Comprehension debt: what AI-written code actually costs", "summary": "A developer's essay introduces 'comprehension debt,' a term coined by Jason Gorman, to describe the gap between what AI-generated code does and what human teams understand about it. The piece argues that as AI agents produce code faster than humans can comprehend, the traditional assumption that code authors understand their work no longer holds, creating a new form of technical liability that cannot be refactored away.", "body_md": "*Originally published at fathohm.dev.\nThe term \"comprehension debt\" is Jason Gorman's, from September 2025, carried by\nAddy Osmani in March 2026 — this piece is about measuring it.*\n\nThere's a module in your codebase that shipped last month. It works. It has\n\ntests. It passed review. And if it breaks at 2am, nobody on your team can\n\nexplain what it does.\n\nAsk \"who understands this?\" about any given file in an AI-native codebase\n\nand the honest answer, increasingly often, is *no one* — not because your\n\nengineers got worse, but because the code stopped passing through their\n\nheads on its way into production.\n\nFor seventy years, code getting written implied that somebody understood\n\nit. The implication was so reliable we never thought of it as an assumption:\n\nwriting code *was* the act of understanding a problem precisely enough to\n\nexpress it. However bad the code, however absent the docs, there was at\n\nminimum one person — the author, at the moment of authorship — who knew what\n\nit did and why. Every practice we have for keeping teams oriented in a\n\ncodebase quietly leans on that floor: review assumes the author can defend\n\nthe change, onboarding assumes someone can explain the system, debugging\n\nassumes a colleague to ask.\n\nAI agents broke the implication. Code getting written and code getting\n\nunderstood are now separate events, and only one of them is scaling. An\n\nagent can produce in an afternoon what a team used to write in a month —\n\nand the afternoon does not come with a month's worth of understanding\n\nattached. The floor of \"at least the author knows\" is gone: for\n\nagent-authored code, the author isn't on your team. It isn't anyone.\n\nThe gap between what a codebase does and what the humans responsible for it\n\nunderstand needs a name, because things without names don't get managed. It\n\nhas one, and it has had one for a while. [Jason Gorman named it comprehension](https://codemanship.wordpress.com/2025/09/30/comprehension-debt-the-ticking-time-bomb-of-llm-generated-code/)\n\nWe depart from both definitions in exactly the same one place, and it is the\n\nreason this essay keeps going. *Faster than they can understand it*; *genuinely\nunderstands* — those are claims about states of mind, and minds are not\n\nThe obvious objection is that we already have a word for accumulated\n\ncodebase problems. But technical debt, as Ward Cunningham coined it, is a\n\nproperty of the *code* — shortcuts embodied in the artifact itself, visible\n\nin the artifact itself. You can point at tech debt in a diff.\n\nComprehension debt is a property of the *team*. The same file can be zero\n\ndebt on one team and a total blind spot on another, with not one character\n\ndifferent — because the debt isn't in the file, it's in the relationship\n\nbetween the file and the humans accountable for it. That's why the\n\ntech-debt playbook doesn't apply: you cannot refactor your way out of\n\ncomprehension debt. A perfect, clean, well-tested module that nobody\n\nunderstands is still a liability — arguably a worse one, because nothing\n\nabout it looks wrong.\n\nIt also inverts the usual direction of concern. Tech debt worries about bad\n\ncode that works. Comprehension debt worries about *good* code that works —\n\nright up until the moment it doesn't, and the team discovers the\n\nunderstanding they assumed they had was never acquired by anyone.\n\nNothing in the modern toolchain measures understanding. We measure\n\ncoverage, complexity, velocity, deploy frequency, incident counts — every\n\nproperty of the code and the process, and no property of the humans'\n\ngrasp of it.\n\nThe closest thing we had was code review, and review was never a\n\nmeasurement — it was a sampling event. It checked comprehension exactly\n\nonce, at merge time, in one person, and we extrapolated \"the team\n\nunderstands this\" from \"one person approved it once.\" That extrapolation\n\nwas always generous. Under AI-native throughput it collapses: when the\n\ndiffs triple in size and quadruple in frequency, reviews get shorter, not\n\ndeeper. An approval with no comments on a four-hundred-line agent-written\n\nchange is not evidence of understanding. It's evidence of throughput.\n\nMeanwhile the oldest team-risk heuristic we have quietly hit a new floor.\n\nBus factor — how many people can disappear before nobody understands a\n\nsystem — used to be bounded below by one, because someone wrote the thing.\n\nAgent-authored code breaks that floor. Somebody prompted it, so the count is\n\nnot zero; but a person who prompted a file and read the diff is not on the bus\n\nthe way an author is, and often nobody else is on it at all. The honest unit\n\nturns out to be fractional rather than whole — which is uncomfortable, and is\n\nthe point. A heuristic that only counts whole people cannot see the state most\n\nAI-native code is actually in.\n\nLike financial debt, comprehension debt is cheap to carry and brutal to\n\nservice. The carrying cost is invisible: the code works, the dashboards are\n\ngreen, velocity looks great. The interest comes due at specific moments:\n\nNone of this argues against AI-written code. The leverage is real and\n\nteams that refuse it will lose to teams that don't. It argues that the\n\nleverage has a cost that no current instrument shows, and costs that\n\nnothing shows don't get managed — they get discovered.\n\nThe fair objection: understanding is a state of a human mind, and states of\n\nminds don't show up in git.\n\nCorrect — so don't. Measure the record instead, which is what every serious\n\nmetric in engineering already does. The observable signals are real: whether\n\na human substantively reviewed a change (a comment trail, not a bare\n\napproval), how recently a human meaningfully wrote in a file, how many\n\ndistinct humans have had real contact with it. None of those ask what anyone\n\nknows. All of them are in your git history already.\n\nThe ground truth is checkable too, with one constraint that turns out to be\n\nthe whole game: the check cannot be self-administered. Asking someone to\n\nexplain what a file does on failure is a real test. Asking them to grade\n\ntheir own answer is a survey, and a survey attached to a number people care\n\nabout is just a slider they can move. The answer has to be read by someone\n\nwho did not write it.\n\nWhat matters more than the choice of signals is the discipline around\n\nthem:\n\nYou can start managing comprehension debt tomorrow with no new tools:\n\nWhat you can't do by hand is see the whole surface at once, watch it move,\n\nor keep yourself honest about decay — the same reason nobody tracks test\n\ncoverage in a spreadsheet.\n\nThat's the part we built. Fathohm maps comprehension debt across a codebase\n\n— deterministically, decomposably, disputably — at\n\n[fathohm.dev](https://fathohm.dev).\n\nThe code will keep getting written either way. Whether it keeps getting\n\nunderstood is now a choice.", "url": "https://wpnews.pro/news/comprehension-debt-what-ai-written-code-actually-costs", "canonical_source": "https://dev.to/amit_shrivastava_e813c728/comprehension-debt-what-ai-written-code-actually-costs-2m02", "published_at": "2026-08-18 15:19:53+00:00", "updated_at": "2026-08-18 15:44:04.915610+00:00", "lang": "en", "topics": ["artificial-intelligence", "developer-tools", "ai-ethics"], "entities": ["Jason Gorman", "Addy Osmani", "Ward Cunningham"], "alternates": {"html": "https://wpnews.pro/news/comprehension-debt-what-ai-written-code-actually-costs", "markdown": "https://wpnews.pro/news/comprehension-debt-what-ai-written-code-actually-costs.md", "text": "https://wpnews.pro/news/comprehension-debt-what-ai-written-code-actually-costs.txt", "jsonld": "https://wpnews.pro/news/comprehension-debt-what-ai-written-code-actually-costs.jsonld"}}