Comprehension debt

The code passes every test, ships clean, and nobody on the team can tell you how it works.

That is not a quality problem. The tests are green, it runs in production, the dashboard looks fine. It is a different kind of debt, and most teams are not tracking it.

Call it comprehension debt. AI writes faster than anyone can read and absorb, so the code keeps shipping while the understanding falls behind. Two lines that used to move together come apart: what the team has shipped, and what the team actually holds in its head.

The debt is invisible exactly where you are looking. Change failure rate looks healthy. Velocity looks up. None of your delivery metrics have a column for “could anyone here explain this”. It is the quiet version of a problem you already half know about: when generation outpaces review, review does not stop, it goes ceremonial. People approve faster than they can read, because the alternative is becoming the bottleneck. The tick still gets applied. The understanding it was meant to certify never happened.

Then someone on your team has to change that code six months on. Nobody remembers why it is shaped the way it is. Whoever merged it was trusting the agent, not reading it. Now a small fix takes a day, because first you have to understand what you already shipped.

This is not the same as deliberately trusting code you did not read. That can be a sound choice, if you have built the tests and the review to stand behind it. Comprehension debt is the involuntary version: nobody chose it, and nobody could explain the code even if they had to.

The speed is real. Most teams genuinely do move faster once the agents go on, and that lift is worth having. What nobody is measuring is the second line: whether the team still understands what it shipped. Let the two get far enough apart and the next change is no longer a change, it is an excavation.