# 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]]