Addy Osmani is right that AI widens the gap between code that exists and code anyone understands. He is wrong that the answer is to understand more. The answer is to make understanding cheap to regenerate. Debt you can refinance at zero percent is not really debt.
Date: June 2026 | Riffs on: Addy Osmani, Comprehension Debt
The Argument I Agree With
Addy’s framing is clean. Comprehension debt is the growing gap between how much code exists in a system and how much any human genuinely understands. Unlike technical debt, it hides. The code is tidy, the tests are green, the PR merges, and understanding quietly leaks out of the building while every dashboard stays in the green. A junior can now generate code faster than a senior can critically audit it, which inverts the review bottleneck that used to force comprehension as a side effect of shipping. Tests are necessary and not sufficient, because they cannot catch the problems nobody thought to specify. All true.
I have felt this in my own work. I have around 350K lines of production code across my projects, and I can feel the seam between the parts I understand deeply and the parts I merely approved. The first kind I can extend, debug, and refactor at 2am with confidence. The second kind I avoid at 2am. So I am not here to argue the problem away. The problem is real. I just think the standard prescription quietly loses the race it sets up.
Where I Get Off The Bus
Addy’s fix is discipline: be explicit about behavior before you write, treat verification as a structural constraint, hold a system-level mental model, and refuse to confuse “tests pass” with “I understand this.” Every line of that is correct advice. All of it is also un-scalable, because the throughput asymmetry does not go away when you try harder.
If the complaint is “code arrives faster than I can understand it,” then “understand more of it” is a footrace against a counterparty that just got ten times faster and will get faster again next quarter. You cannot out-discipline a generator running at machine speed. And comprehension-as-hoard, the model where you read code once, carry it in your head, and defend the hoard, was already failing before any of this. It is why we have bus-factor anxiety, tribal knowledge, and the one engineer who cannot take a holiday. AI did not invent the leak. It turned a slow drip into a burst pipe.
Reframe: Comprehension Is A Flow, Not A Stock
Here is the move. Stop treating comprehension as a stock you accumulate and guard. Treat it as a flow you can summon on demand.
The question is no longer “do I understand every line of this right now,” because you do not, and increasingly you cannot. The question is “when I next need to understand this, how expensive is it to regenerate that understanding from a cold start?” If re-comprehension is cheap, the debt carries almost no interest. You can let large stretches of the system sit un-held in anyone’s head, because the cost to re-derive understanding on the day you actually need it is measured in minutes, not days.
That is what refinancing debt means. You do not pay down the principal. You drop the interest rate to something you can service forever. So the engineering goal shifts from “understand the code” to “build the instruments that make re-comprehension cheap.” There are four of them, and the fourth is new.
The Four Instruments
1. Types as the executable spec
A well-typed boundary collapses the space of what a piece of code could possibly be doing. I can read a function signature with no implementation and already know most of what matters: what it consumes, what it can return, and which failure modes are even representable. Types are the part of comprehension that never decays, because the compiler refuses to let them drift from the code. This is why I lean on type-driven development and on errors as values: they make the cheapest layer of understanding permanent and machine-checked.
2. Tests as behavioral documentation
Addy is right that tests do not catch unspecified bugs. But that framing undersells what they do for re-comprehension. A good test suite is the fastest readable answer to “what is this supposed to do.” When I return to code I no longer remember writing, the tests are the spec I read first, and they are a spec that cannot lie, because if it were stale it would be red. Coverage is a comprehension asset, not just a correctness one.
3. Observability as runtime truth
Types and tests tell you what should happen. Observability tells you what does. Traces, structured logs, and metrics are how I re-comprehend a live system without reading its source at all. This is the same shift behind stewardship over authorship: when you cannot review every line, safety and understanding both move from the code into the system around the code. I re-derive how a production path behaves by reading its telemetry, then drop into the source only where the telemetry surprises me.
4. The agent as an on-demand explainer
This is the instrument that flips the economics. The same model that generated the code faster than I could read it will also explain it faster than I could puzzle it out. “Explain why this approach was chosen over the two obvious alternatives.” “Trace exactly what happens when this argument is null.” “What invariant does this block quietly depend on?” That is re-comprehension on tap, and it is the direct answer to the throughput asymmetry: comprehension supply can now scale at the same speed as code supply.
There is a real catch. An explainer is only trustworthy on a substrate it can verify against. An LLM narrating untyped, untested, unobserved code is guessing fluently and you have no way to catch it. The first three instruments are exactly what make the fourth honest. Types, tests, and traces are the ground truth the explainer is checked against. Without them you do not have an explainer, you have a confident storyteller.
The Honest Limit
Refinancing is neither free nor universal. There are two places where you still pay full principal, in cash, with your own head.
The first is architecture and invariants. The load-bearing decisions, where a boundary sits, which states are made illegal, what the system promises never to do, are comprehension no instrument regenerates for you. A model will explain what the boundary is. It will not reliably tell you the boundary is in the wrong place. That judgment you hold yourself, and it is the same line I draw in autonomous loops: the human owns the part with no scoring function.
The second is that the substrate has to actually exist. Refinancing assumes you built the types, the tests, and the telemetry. If you skipped all three and shipped the generated code raw, you do not have refinanceable debt. You have a payday loan, and the interest is exactly the slow atrophy Addy warns about. The instruments are not optional polish. They are the thing that converts the debt from predatory to serviceable.
So What Changes On Monday
Stop spending your scarce attention trying to hold the whole system in your head, and start spending it building the four instruments on the parts that matter most. Type the boundaries. Treat the test suite as the readable spec it secretly is. Wire the observability before you need it. And get fluent at using the agent as a comprehension engine, not just a code engine, on a substrate solid enough to keep it honest. Reserve the irreplaceable, un-refinanceable comprehension, architecture and invariants, for yourself.
You will still owe comprehension debt. Everyone running AI at this throughput does. The difference between the teams that drown and the teams that compound is not how much they understand at any given moment. It is the interest rate they are paying on what they do not.
One Sentence
Do not try to understand everything the machine writes. Build the system that lets you re-understand any of it in minutes, then let the rest go.
Related
- Code Stewardship Over Authorship – Reliability as a system property when you cannot review every line
- The Struggle Is the Product – The learning cost of skipping comprehension, and when that cost is worth paying
- Type-Driven Development – The permanent, machine-checked layer of understanding
- FP Increases LLM Signal – Errors as values give the explainer complete signal
- The Verification Ladder – The substrate that makes the agent-explainer honest
- Conversational Code Review – Re-comprehending large diffs through ticket, diff, and impact
- Autonomous Loops Need a Scoring Function – The comprehension you cannot refinance
