Comprehension Debt
Comprehension debt is the gap between what a system does and what its owners actually understand about it. Every line of code you ship without understanding adds to it. You still own the behavior; you just can't explain it, debug it, or safely change it.
Canonical version: Comprehension Debt.
Comprehension debt is the gap between what a system does and what its owners actually understand about it. Every line of code you ship without understanding adds to it. You still own the behavior; you just can't explain it, debug it, or safely change it.
The concept is a sibling of Technical debt, but the two decay differently. Technical debt is code you understand but wish were better. Comprehension debt is code that may even be good, but that nobody on the team can reason about. A codebase can be clean, tested, and consistent, and still be a black box to its own maintainers.
Why AI made it urgent
The term surfaced in the Loop Engineering discourse of 2026 (notably in the cobusgreyling/loop-engineering repo's concepts, alongside intent debt), because autonomous coding loops are comprehension-debt factories. A loop that ships verified, test-passing code all night produces exactly the situation the definition describes: the behavior is correct, the tests are green, and nobody read the diff.
This is the honest caveat behind the productivity gains. The repo's own warning list says it plainly: comprehension debt grows faster unless you read what the loop ships. Addy Osmani's framing points the same way; build the loop like someone who intends to stay the engineer, not just the person who presses go.
The debt also compounds with scale. One unread PR is recoverable. Three months of unread agent output is a system you no longer own intellectually; you can only steer it statistically, through evals and verifiers.
How to keep it bounded
- Read what ships. Not everything, but on a sampling cadence you actually hold. Post-merge review loops exist for exactly this.
- Make the loop explain itself. Run logs, decision notes, and changelog drafts are cheap for the agent to produce and cut the cost of catching up later.
- Keep humans on the load-bearing paths. Architecture, data models, and security boundaries deserve full human comprehension; CRUD plumbing may not.
- Treat rising debugging time as the symptom. When "why does it do that?" takes longer every sprint, you are paying interest.
It overlaps heavily with Cognitive debt; comprehension debt is essentially the loop-engineering community's name for the same gap, seen from the system's side. My working distinction: cognitive debt lives in the human (an eroded mental model, outsourced thinking), comprehension debt lives in the codebase (shipped behavior nobody has read). Same disease, measured from the two ends. The loop-era twist is scale: agents ship faster than humans can comprehend, so the debt now grows by default rather than by negligence.
References
- cobusgreyling/loop-engineering, concepts (intent debt, comprehension debt, harness vs loop) — https://github.com/cobusgreyling/loop-engineering
- Addy Osmani, "Loop Engineering" — https://addyosmani.com
Related
- Technical debt
- Cognitive debt
- Community debt
- Loop Engineering
- Vibe Coding
- Agentic Engineering
- AI Verifiability
About Sébastien
I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.
I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.
If you want to follow my work, then become a member and join our community.
Ready to get to the next level?
If you're tired of information overwhelm and ready to build a reliable knowledge system:
- 📚 KM for Beginners — 10+ hours of structured video lessons
- 🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
- 💼 Knowledge Worker Kit — Complete guides + lifetime community
- 🦉 1-on-1 Coaching — Personalized guidance
- 🎯 Join Knowii — Community + ALL courses & tools
Found this valuable? Share it with someone who needs it.