In 1985, Peter Naur wrote that a program dies when the team that possesses its theory is dissolved: the idea of why the code is the way it is. With coding agents, a program can start dying without anyone leaving.
This piece argues an uncomfortable thesis: the risk of coding with agents is not only code that fails, but code that works and that nobody on the team can explain. A specification written before the code pays off part of that debt, not all of it. The rest is only paid with a rule: a change does not go in until someone on the team can explain it, not just approve it.
A debt that gives no warning
Addy Osmani described it in March 2026 as comprehension debt: the growing gap between how much code exists in your system and how much of it any human being genuinely understands. One line of his sums it up: making code cheap to generate does not make understanding cheap to skip.
The difference from ordinary technical debt is that this one sends no signals. No test fails, no review metric moves. It is found late, when a production error forces someone to debug a module that nobody really wrote.
| Technical debt | Comprehension debt | |
|---|---|---|
| What it is | Shortcuts in the code that will have to be redone | Code that nobody on the team can explain |
| How it shows | Changes that cost more and more | It does not show: it works and passes the tests |
| When it appears | Gradually, day to day | Suddenly, when that code is debugged or changed |
| What makes it grow | Rushing and shortcuts | Generating faster than anyone reads |
Comparison by onext based on Addy Osmani's article (2026)
What a controlled study says
In January 2026, Judy Hanwen Shen and Alex Tamkin published an Anthropic experiment with 52 engineers, mostly junior, who were learning a new library. One group worked with AI assistance; the other, by hand. Afterwards, everyone took a comprehension quiz.
It needs careful reading. The authors themselves warn that the sample is small and that comprehension was measured right after the task; they do not know whether that predicts how someone learns in the long run. It is not a figure for how much comprehension debt teams carry: nobody has measured that. What it does suggest is where it shows first, in debugging, which is exactly when the debt is collected. What this means for people starting out is covered in junior developers with AI: learning to review.
How much of it the spec pays off
With Spec-Driven Development (SDD), the change is described in writing before the agent writes code: what it must do, why and how it is checked. That pays off part of the debt. When someone has to touch that code a year from now, they will know what was intended, as we explain in SDD: controlled code.
It does not pay all of it, and that is worth saying. Osmani points out that turning a spec into code involves an enormous number of implicit decisions that no spec fully captures: two engineers with the same spec build systems that behave differently. Naur saw it more than forty years ago: program text and its documentation are not enough to carry some of the most important design ideas. Those ideas live in people.
The spec says what the change was meant to do. Only someone who has understood it can say why the code does it this way and what breaks if it is touched.
The other part: explain, not just approve
Approving a review and understanding a change are not the same thing. With agents, review tends to check that the change does what was asked and that the tests pass, which is necessary but not enough. What the review process does and does not catch is covered in reviewing AI-generated code.
The rule we propose is simple to state: a change does not go in until someone on the team can explain it in their own words, what it does and why it does it that way. If nobody can, the change is split, rewritten or completed with what is missing. It is the same logic as where you sign off in a cycle with agents: a person decides where there is risk.
Risk This rule only works if saying "I don't understand this code" is normal on the team. If admitting it feels like a personal failure, people will approve what they do not understand and the debt will keep growing in silence.
Two pieces give the explanation something to stand on. The decisions that cannot be reversed without cost, written down with their context, as we cover in architecture decisions. And a test safety net that catches errors before the agent speeds things up, in before the agent, the safety net. In legacy code, the starting point is to specify first the part the agent is going to touch: specifying legacy code before AI agents.
Three questions for your team this week
- Of the last big change that went in with an agent's help, who could explain it without opening the code?
- If it fails in production tomorrow, who debugs it and how long would it take them to understand what it does?
- Has anyone said "I don't understand this change" in a review this month? If nobody has, is it because everything is understood?
Where onext fits
In AI-Accelerated Development we build, with your team, the context the AI works in and the process you work with. Both stay with you. A person decides where there is risk. The first step is a free diagnostic, and if the diagnostic shows no difference, there is no Quick-start.
Frequently asked questions
What is comprehension debt?
Addy Osmani defines it as the growing gap between how much code exists in your system and how much of it any human being genuinely understands. It is code that works and passes the tests, but that nobody on the team can explain.
How is it different from technical debt?
Technical debt usually shows: changes that cost more and more, or tangled dependencies. Comprehension debt gives no warning. It surfaces the day that code has to be changed or debugged and nobody knows why it does what it does.
Why does it grow faster with AI agents?
Because generating code has become cheap and understanding it has not. Osmani puts it this way: making code cheap to generate does not make understanding cheap to skip. An agent produces changes faster than a person can read them carefully.
Is there data showing that AI reduces code comprehension?
There is an Anthropic study with 52 engineers, mostly junior: the group that learned a library with AI assistance scored 50% on a comprehension quiz, against 67% for the group without AI, and the largest gap was in debugging. The authors warn that the sample is small and that comprehension was measured right after the task. It does not say how widespread the problem is across teams.
Does a specification written before the code solve the problem?
It pays part of it: it records what the change was meant to do and why. It does not pay all of it. Osmani points out that turning a spec into code involves an enormous number of implicit decisions that no spec fully captures, and Naur wrote in 1985 that program text and its documentation are not enough to carry some of the most important design ideas.
What rule is worth adding to code review?
That a change does not go in until someone on the team can explain it, not just approve it. And that saying "I don't understand this code" is normal on the team, not a confession.
Sources
- Addy Osmani, "Comprehension debt", 14 March 2026; republished on O'Reilly Radar as "Comprehension Debt: The Hidden Cost of AI-Generated Code", 13 April 2026.
- Peter Naur, "Programming as Theory Building", 1985 (copy of the full text).
- Judy Hanwen Shen and Alex Tamkin, "How AI assistance impacts the formation of coding skills", Anthropic, 29 January 2026 (full paper: arXiv 2601.20245).
- The comparison between the two debts, the explain-before-approving rule and the three questions are onext's own elaboration.
Bernat López is founder and CEO of onext, an AI boutique. He helps development and product teams work with AI with method —specification before building, a person who decides where there is risk and Spec-Driven Development— and applies to his own company what he proposes: onext runs on its own agentic system.
LinkedIn →