Your codebase is growing faster than your team can understand it. Not because anyone is writing bad code — because AI is writing more code than humans can absorb. The gap between what exists in your repository and what any engineer genuinely understands is widening every sprint. Addy Osmani calls this comprehension debt, and it might be the most dangerous form of technical debt your team is accumulating right now.
Unlike traditional technical debt, comprehension debt is invisible. The code compiles. The tests pass. The PR looks clean. But nobody on the team actually understands what it does or why it was written that way. And when something breaks at 2 AM, that gap between code volume and team understanding becomes very expensive, very fast.
Why AI makes this worse, not better
AI coding assistants broke the feedback loop that used to keep comprehension in check. When developers wrote every line by hand, understanding was a byproduct of the writing process. You understood your code because you thought through every decision while typing it.
AI-generated code removes that forcing function. A developer prompts an agent, gets back 200 lines of working code, skims it, and merges. The code is syntactically clean, often well-formatted, and superficially correct — precisely the signals that historically triggered merge confidence. But the developer absorbed maybe 30% of it.
Scale that across a team of ten engineers, each merging AI-generated code multiple times per day, and you have a codebase that is growing at five to seven times the rate anyone can absorb. An Anthropic study found that developers using AI assistance scored 17% lower on comprehension quizzes about their own code, with the largest drops in debugging ability.
The false confidence trap
Technical debt announces itself. Builds get slower. Dependencies tangle. That one module makes everyone groan. You feel it accumulating because it creates friction.
Comprehension debt does the opposite — it breeds false confidence. The codebase looks healthier than ever. Test coverage is up. The linter is happy. PRs ship faster. Every metric you track suggests things are going well. But comprehension is quietly hollowing out underneath, and you will not discover that until something goes wrong.
The moment arrives when a production incident requires understanding three modules that interact in a non-obvious way. Nobody on the team wrote those modules from scratch. The AI generated them over different sprints, and the connective logic between them lives in no one's head. What should be a thirty-minute investigation turns into a four-hour archaeology session.
The real cost is compounding
Comprehension debt compounds in ways that traditional technical debt does not. Every new feature built on top of code nobody understands deepens the gap. Refactoring becomes dangerous because nobody is sure what the existing code actually relies on. Debugging gets slower because the mental model needed to trace a problem does not exist.
Worse, onboarding slows to a crawl. New engineers used to ramp up by reading the codebase. When the codebase is three times larger than it would have been without AI, and the original intent behind most of it lives only in the prompts that generated it — prompts nobody saved — the onboarding surface area explodes.
Teams start to notice a strange pattern: shipping velocity stays high, but incident recovery time increases. Features land fast, but bug fixes take longer. The team is writing more code than ever and understanding less of it than ever.
Measuring what you cannot see
The first step to managing comprehension debt is making it visible. Traditional engineering metrics do not capture it because they measure output, not understanding. Lines of code, story points completed, PR throughput — all of these can go up while comprehension goes down.
Some signals that comprehension debt is accumulating:
- Incident investigation time is increasing even though the team is more experienced and the tooling is better.
- Knowledge bus factor is falling. Fewer people can confidently explain how any given module works. The ratio of "I think I know" to "I know" is shifting.
- Code review is superficial. Reviewers approve AI-generated PRs based on test results rather than understanding. The review is a rubber stamp, not a knowledge transfer.
- Debugging uses more AI. Developers ask AI to explain code that AI wrote — a sign that the team has lost the thread.
- Architectural decisions drift. New code introduces patterns that conflict with existing patterns because nobody has the full picture.
Fighting back without slowing down
The answer is not to stop using AI coding tools. The productivity gains are real and teams that reject them will fall behind. The answer is to build systems that force comprehension back into the workflow.
Narrated AI actions, not silent merges. When AI generates or modifies code, the team should see what changed and why in plain language — not buried in a diff, but narrated in the space where the team coordinates. This turns invisible changes into visible events that build shared understanding.
Smaller scope, tighter ownership. Comprehension debt is worse when nobody owns anything specific. Clear ownership boundaries — this person understands this module — limit how far the debt can spread. Smaller modules with clear interfaces are easier to comprehend than monolithic ones, even when AI writes both.
Architecture-aware task assignment. When you assign work based on who needs to understand what, you turn regular development into a comprehension-building activity. Rotating people through modules — instead of letting AI handle everything while the team watches — maintains the human understanding layer.
Decision provenance, not just code provenance. Git tracks what changed and who changed it. But the "why" — the decision that led to this approach — vanishes when AI generates code from a prompt. Teams need a system that captures the reasoning alongside the result. The conversation that shaped the code matters as much as the code itself.
Project management is the comprehension layer
Here is the uncomfortable truth: the tool best positioned to fight comprehension debt is not a linter, a documentation generator, or a code review bot. It is your project management system — if it is designed for this era.
Project management is where intent lives. Why was this feature prioritized? What problem was it solving? Who decided on this approach? When the conversation that produced a task is preserved alongside the task itself, comprehension has an anchor. Six months from now, when someone needs to understand a module, the reasoning is there — not lost in a Slack thread or a prompt nobody saved.
The PM tools built before AI assumed the hard part was tracking work. In the AI era, the hard part is tracking understanding. Activity feeds that narrate what changed. Ownership models that map people to the code they need to comprehend. Conversations that capture why a decision was made, not just that it was made.
Teams that treat project management as their comprehension layer — the system that keeps human understanding in sync with AI-generated output — will navigate this era without accumulating invisible debt. Teams that only track velocity will ship faster and faster until the day they hit a wall they cannot debug.
The teams that win will be the ones that understand
AI is not going to slow down. Code generation will get faster, agents will get more autonomous, and the volume of AI-written code in your repository will grow. The question is whether your team's understanding grows with it or falls further behind.
Comprehension debt is the defining challenge of AI-augmented engineering. Not because AI writes bad code — it often writes good code. But because good code that nobody understands is a time bomb. The explosion is just slower.
The teams that treat understanding as a first-class engineering metric — as important as velocity, as visible as test coverage, as tracked as uptime — will build the things that last. Everyone else will build faster and understand less, until the debt comes due.