Comprehension Debt: The Hidden Cost of AI-Generated Code
"You're not a developer anymore. You're a reviewer of code you don't understand."
That line from The Serious CTO named something I’d been feeling but couldn’t articulate. With AI, the volume of code we ship has completely decoupled from the amount of code any human actually understands.
I call this comprehension debt — the gap between the code in our systems and the knowledge in our teams’ heads. And I believe it’s the most important kind of debt our industry has accumulated in the past two years.
It’s not technical debt
Ward Cunningham’s original “technical debt” was a conscious trade-off. Comprehension debt is different.
It isn’t deliberate.
It isn’t local.
And it doesn’t show up on any dashboard.
What the dashboards actually measure
DORA, Flow, and even the new AI Impact metrics all measure motion — speed, volume, acceptance rates, deployment frequency. None of them measure whether anyone on the team can still explain the code they shipped last quarter.
The standard answers fall short
More code review, more linters, more tests, and “future AI will fix it” don’t solve comprehension debt. They mostly create the illusion of safety.
What it looks like in practice
Fields nobody can explain, controllers with dead branches, 2am incidents where the on-call engineer can read the stack trace but can’t narrate the logic. Individually minor. Collectively, the new shape of legacy code — built at unprecedented speed.
What should we do instead?
I don’t have perfect answers yet, but I know the solution isn’t “more of the same.” We need to actively maintain comprehension as a first-class team property.
What do you think?
Have you seen comprehension debt in your own teams? What (if anything) are you doing about it?