Comprehension debt is the gap between code that works and code people can explain. It includes missing understanding of a system’s architecture, assumptions, and interactions. Unlike technical debt, it may exist in well-structured, tested code; it grows when teams leave, systems outgrow one person’s mental model, or AI generates more code than people absorb. section 1.0 section 1.1
Recognize and reduce comprehension debt by changing the work from code production to deliberate understanding:
- Choose engineer mode: ask AI to explain the system instead of asking it to build a feature you cannot yet explain. section 1.3.2
- Reverse-engineer in layers, beginning with purpose and moving through components, schema, interfaces, request flow, internals, and safe modification. section 1.5
- Demand concrete artifacts: a one-sentence explanation, API-route list, browser-to-database trace, readable schema diagram, and alternative approaches with trade-offs. section 1.5
- Verify confident AI claims and challenge assumptions; catching nonsense becomes practice for architectural judgment. section 1.6
The 2 AM production alert
A legacy service works, but its original team has left and nobody remembers why it behaves as it does. Instead of requesting a patch immediately, ask for one sentence describing the system, trace the failing request from browser to database, list the relevant routes, and redraw the schema. The resulting map turns an opaque fix into an informed change. section 1.1 section 1.5
Table 1.1 Technical debt versus comprehension debt
|
|
Technical
Debt
|
Comprehension
Debt
|
|
What it is
|
Code you know is messy
|
Code that
works but nobody understands
|
|
How it happens
|
Conscious
trade-off to hit a deadline
|
Team
leaves, AI generates it, system outgrows one person's mental model
|
|
How you find it
|
You know
where it is
|
You don't
even know what you don't understand
|
|
The fix
|
Refactor
|
There is no
fix without rebuilding the understanding
|
Compare technical debt with comprehension debt by cause, discoverability, and remedy: known messes can be refactored, while misunderstood working code first requires rebuilding understanding. section 1.1
