Comprehension Debt
Last updated: 2026-11-044 min read
Sources checked 2026-11-04no external figures
Comprehension debt is the growing gap between the code a team ships and the mental model its people hold of it. The system’s theory hollowing out while its line count grows. AI coding accelerates it because generation no longer produces understanding as a by-product: the model writes, the human skims, and nobody builds the theory.
Contents
Where the idea comes from
The intellectual root is four decades old. In Programming as Theory Building (1985), Peter Naur argued that a program is not really its code: it is the theory in the heads of the people who built it. Why the system is shaped this way, which changes it tolerates, where the bodies are buried. Code without that theory is an artifact nobody can confidently change.
The term comprehension debt attached itself to this idea as AI-generated code went mainstream: through Jason Gorman’s widely discussed framing of LLM code as a “ticking time bomb” of understanding (September 2025), and through an essay by Addy Osmani (March 2026), which O’Reilly Radar reposted in April. The mechanism is simple: writing code was how developers built Naur’s theory. Remove the writing, keep the shipping, and the theory stops being built while the system keeps growing.
Three debts, one family – and different repayments
AI coding produces more than one kind of debt, and teams that only measure one get surprised by the others:
| Technical debt | Verification debt | Comprehension debt | |
|---|---|---|---|
| Core question | Is the code well-built? | Was this change checked against intent? | Does anyone still understand the system? |
| Unit | The codebase | The individual change | The team's mental model |
| How it announces itself | Loudly: slow builds, painful changes | Quietly: 'looked right' incidents later | Very quietly: onboarding slows, one person 'knows it' |
| AI's effect | Mixed: more copy/paste, less moved code in GitClear's 2025 data | Accelerates it: generation outruns checking | Accelerates it most: generation without understanding |
| Repayment | Refactoring | Verification per change, recorded | Humans in the decision loop; decisions recorded with reasons |
The debts compound: unverified changes (verification debt) become foundations nobody understands (comprehension debt), which makes the next verification harder still.
Why it breeds false confidence
Technical debt is at least honest: it hurts every time you touch the tangled module. Comprehension debt is invisible in the codebase: the code is clean, the tests are green, the linter is happy. What is missing exists only as an absence: the person who could say why the retry logic works this way, or what breaks if you change it. Teams discover the debt at the worst moments: during an incident, a security review, or the departure of the one person who still held the theory.
Margaret-Anne Storey’s 2026 paper generalizes this as cognitive and intent debt: understanding thins out, and the rationale, goals and constraints behind changes go missing or erode. That is where comprehension debt and verification debt share a root cause and a remedy.
What keeps understanding alive
- Written intent per change. A checkable task specification records what was meant: the raw material of theory, preserved even when a model wrote the lines.
- Review as judgment, not skimming. The human in the loop builds theory only if the review engages with intent, which is what a machine pre-check frees them to do.
- Decisions recorded with reasons. Session handoffs and evidence trails carry the “why” across time: the part of the theory that can be written down.
- Ownership despite generation. A module can be AI-written and human-owned; it cannot be safely nobody-owned.
Where Reality Graph fits
Reality Graph addresses the recordable half of comprehension debt: it records the intent, boundaries, and verification outcomes of every run in an evidence report on your own machine, so the “why” and “what was checked” survive even when no human wrote the lines. Next to that, a local index that shows you how stale it is answers the narrow structural question of what calls what, which is a starting point for a theory and not a substitute for one. The unrecordable half, humans actually engaging with the system, remains yours.
Naming this debt gives you
- A vocabulary for a risk dashboards don't show
- Proxies to watch: onboarding time, bus factor, regenerate-instead-of-modify
- A clean split from technical and verification debt
- An argument for keeping humans in the decision loop
It does not mean
- AI-written code is unmaintainable per se
- Documentation alone repays it: theory can't be fully written down
- Disposable code is always wrong: short-lived scripts differ
- There is a standard metric yet: proxies only
If these boundaries fit how your team wants to ship:
FAQ
- What is comprehension debt and how does it differ from verification debt?
- Comprehension debt is the gap between the code a team ships and the mental model its people hold of that code: system knowledge hollowing out while the codebase grows. Verification debt is about a specific change: was it checked against intent before merge? Comprehension debt is about the system over time: does anyone still hold the theory of how it works? A team can verify every change and still lose the big picture, and the two debts compound each other.
- Where does the concept come from?
- The term spread through the developer community from 2025 as AI-generated code became mainstream. One early use is Jason Gorman's Codemanship post of 30 September 2025, 'Comprehension Debt: The Ticking Time Bomb of LLM-Generated Code', which drew a long Hacker News discussion; Addy Osmani's essay of March 2026, reposted on O'Reilly Radar in April, carried it further. Its intellectual root is much older: Peter Naur's 1985 essay 'Programming as Theory Building', which argued that software is not really the code. It is the theory in the heads of the people who built it.
- Why does AI coding accelerate comprehension debt?
- Because writing code was how developers built their theory of it. When a model writes and a human skims, the code arrives without the understanding that used to come from producing it, and it arrives faster than anyone can absorb. Generation speed outruns theory-building speed, and the gap compounds with every merge.
- Is comprehension debt measurable?
- Less directly than verification debt, but proxies exist. How long onboarding takes, how often changes to a module require the one person who 'knows it', bus-factor analyses, and how frequently teams re-generate code because modifying it is harder than replacing it. Rising values on all four are the pattern to watch.
- Does documentation solve comprehension debt?
- It helps but does not substitute. Naur's point was precisely that the theory cannot be fully written down: documentation transmits facts, not the built-up judgment of why the system is shaped this way. What helps more: humans staying in the decision loop (reviewing with intent, not skimming), recorded decisions with reasons, and keeping module-level ownership even when AI writes the lines.
- Can a team just accept comprehension debt and re-generate code instead of understanding it?
- That is a real position ('disposable code'), and for short-lived scripts it can be rational. For systems that live years, the bet fails at the boundaries. Incidents need someone who understands the system now, security reviews need intent, and regeneration without understanding reproduces the old assumptions, the wrong ones included, at scale.
Keep reading
Sources
- Peter Naur – Programming as Theory Building, Microprocessing and Microprogramming 15(5), pp. 253–261 (May 1985); checked 4 November 2026
- Jason Gorman, Codemanship – Comprehension Debt: The Ticking Time Bomb of LLM-Generated Code (30 September 2025); checked 4 November 2026
- Hacker News – discussion of the Codemanship post (30 September 2025); checked 4 November 2026
- Addy Osmani – Comprehension Debt: the hidden cost of AI generated code (14 March 2026); checked 4 November 2026
- Addy Osmani on O'Reilly Radar – the same essay, reposted with the author's permission (13 April 2026); checked 4 November 2026
- Antonija Bilić Arar, LeadDev – AI coding creates two kinds of debt. You're only measuring one (18 June 2026): technical and cognitive debt; checked 4 November 2026
- Margaret-Anne Storey – From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI (arXiv 2603.22106, v1 23 March 2026, v4 6 April 2026); checked 4 November 2026
- GitClear – AI Copilot Code Quality (2025): copy/paste share rising and moved code falling from 2020 to 2024; checked 4 November 2026