DEV Community
Follow
Comprehension debt: what AI-written code actually costs
"Comprehension debt," coined by Jason Gorman in 2025 and popularized by Addy Osmani in 2026, describes the growing gap between the amount of code in a system and how much of it any human genuinely understands. This debt arises because AI agents can produce code much faster than humans can comprehend it, breaking the seventy-year assumption that code implies human understanding. Unlike technical debt, which is a property of the code itself, comprehension debt is a property of the team's relationship with the code. A perfectly clean, well-tested module can still be a liability if no one understands it, inverting the usual concern from bad code that works to good code that works until it breaks.This debt has been invisible because modern toolchains measure metrics like coverage and velocity, but not human understanding. Code review, the closest proxy, is a mere sampling event, and under AI-native throughput, reviews become shorter and less indicative of genuine comprehension. The "bus factor" heuristic also fails, as agent-authored code can have a fractional or non-existent bus factor, meaning no one truly understands it.Comprehension debt accrues invisible carrying costs but incurs brutal interest payments during incidents, future changes, team departures, and onboarding new engineers. These moments force teams to buy back understanding they never acquired at a premium. Measuring understanding should focus on observable signals in git history, such as substantive review comments, recent human authorship, and the number of distinct humans who have genuinely interacted with a file.The discipline around these measurements is crucial: they must be deterministic, decomposable, disputable, and decaying, reflecting that understanding fades over time. Critically, verification must be done by someone other than the original author, to prevent gaming the system.Teams can begin managing comprehension debt immediately by assigning a human author-of-record for AI-written code, banning silent approvals for agent-generated pull requests, and openly discussing which parts of the system are poorly understood. Treating named blind spots as backlog items can also help. While manual efforts are limited, tools like Fathohm can map comprehension debt across an entire codebase, providing a comprehensive, dynamic view. Ultimately, as AI continues to write code, choosing to actively manage comprehension debt will determine whether that code remains understood.