You Don't Understand Your Own Codebase Anymore
A senior engineer asked their AI coding assistant to explain a function the AI had written two sprints ago. The assistant produced a confident four-sentence explanation. The engineer read it, nodded, and accepted it — with no idea whether it was accurate. They merged the PR. The feature shipped.
This is happening on every team using AI-assisted development right now.
What Comprehension Debt Actually Is
Technical debt has artifacts. A TODO comment, a patched abstraction, a table with columns nobody remembers the purpose of. You can audit for it. You can open a PR and watch it accumulate. Teams complain about it in retros and add it to the backlog.
Comprehension debt is invisible. It lives in the gap between what your codebase does and what your team actually understands about why it does it. No artifact. No ticket. No visible signal of accumulation — until the system fails and nobody can trace the failure.
Margaret Storey, a computer science professor at the University of Victoria, described this in her February 2026 research on cognitive debt: the accumulated cost of development choices that compromise a team's ability to reason about their own system. Her observation was direct — AI-assisted development is compounding this faster than any previous productivity tool, because it removes the mechanism that forced understanding: the act of writing code yourself.
How the Mechanism Works
When you type a function, you decide every token. What to name the variable. How to structure the conditional. Whether to extract that loop or keep it inline. Those micro-decisions are not just implementation — they're the process by which you build a mental model of what the code does and why it's structured that way.
Accepting an AI suggestion skips this entirely. The code lands in your codebase correct, passing tests, mergeable — and never having passed through the mind of the person who shipped it.
The danger is subtle because it doesn't look like a problem immediately. The code works. The tests pass. Velocity looks fine.
Then something breaks at 2 AM.
An incident unfolds across a service that three engineers have touched but none of them owns. Nobody can trace the data flow from first principles. The AI assistant offers a probable explanation. The team acts on it. Sometimes they fix the right thing. Sometimes they spend six hours on the wrong problem, because nobody understood what the right problem was.
Three Places It Shows Up
Incident response is the most visible symptom. But comprehension debt surfaces in two other places before it ever reaches a 2 AM page.
Onboarding. A new engineer joining a team with high comprehension debt gets code reviews from reviewers who don't fully understand what they're reviewing. They receive documentation that describes what the code does, not why the tradeoffs were made. They learn to treat the codebase as a navigational challenge rather than a system to be reasoned about. The debt propagates into every new hire.
Architecture decisions. When the team doesn't understand why the system is designed the way it is, they can't make sound calls about where to push it next. Two paths are available — copy the pattern or break it — and both extend the problem. Decisions compound without the understanding to inform them, and nobody notices until something expensive goes wrong.
Why More Documentation Makes It Worse
The instinct when teams spot comprehension debt is to mandate more documentation. More comments, more architecture decision records, more internal wikis. This is the wrong response — not because documentation is bad, but because documentation generated without understanding adds another layer of the same problem.
An AI assistant that writes code and then writes the docstring for that code hasn't added comprehension to the team. It's added the appearance of comprehension. The engineer reading the docstring faces the same problem as the engineer who generated it: they're reading an explanation they didn't produce and can't independently verify.
There's a more fundamental problem. Documentation generated without understanding is a second layer of the same liability. You now have code nobody understands and explanations nobody wrote. The stack of artifacts is taller. The comprehension is the same.
The right diagnosis: this isn't a documentation problem. It's a feedback-loop problem. The friction of writing code — slow, specific, requiring decisions — was where understanding formed. Remove the friction and you remove the formation.
What Actually Reduces It
Three practices reduce comprehension debt without giving up the productivity of AI tools.
Comprehension-gated review. Before a reviewer approves a PR, they should be able to answer one question: "Could I rewrite this from scratch if I needed to?" Not "does this look correct" — that's pattern-matching. The question is whether they understand the code well enough to have written it differently. If they can't answer yes, the PR shouldn't merge.
Slow-path mandates for critical code. The most business-critical paths in your system need an explicit policy: no AI-generated code without a written explanation in the PR body of why the implementation is structured the way it is. Not a summary — a specific explanation of the tradeoffs. If the engineer can't write it, they don't understand it. The AI can help draft it, but the reviewing engineer has to verify it, which requires the engagement that builds comprehension.
Regular rotation into unfamiliar code. Teams that move engineers across service boundaries regularly maintain higher comprehension floors. Engineers who've been forced to understand code they didn't write are substantially more useful during incidents. The rotation is uncomfortable. That discomfort is the point.
The cognitive load of carrying unresolved mental loops while switching contexts — a phenomenon described in the adjacent post on attention residue — applies here too. An engineer who "understands" a codebase but has several unresolved implementation questions is carrying exactly the background activation that degrades both focus and confidence under pressure.
The Velocity Illusion
Comprehension debt is invisible on the metrics that teams track. Story points per sprint looks fine. Deployment frequency is up. Time-to-first-PR for new hires is down.
These metrics measure throughput. They don't measure understanding.
The teams that compound their advantage over the next few years aren't the ones shipping fastest. They're the ones who figured out how to keep understanding in sync with velocity — which requires deliberately maintaining friction in certain places, even when that friction slows down an individual PR.
AI tools are good at what they do. What they don't do is transfer comprehension. That part remains the responsibility of the humans who shipped the code.
One question worth asking your team this week: how many engineers can explain, right now, why the three most business-critical functions in your codebase are structured the way they are?
If the answer is fewer than two, the debt is already there. The question is only how much you've accumulated.
Cover photo by Alberlan Barros via Pexels.