AI Coding Tip 021 - Avoid Comprehension Debt
Stop shipping code you can't explain.
I’m a senior software engineer loving clean code, and declarative designs. S.O.L.I.D. and agile methodologies fan.
TL;DR: Merging code you don't understand creates comprehension debt that compounds until your team can no longer maintain it.
Common Mistake ❌
You ask the AI to implement a feature.
The code looks clean.
The tests are green.
You merge it.
Six weeks later, a defect appears in that module.
Nobody on your team can explain how it works.
You ask the AI again.
You merged without understanding, accumulating both functional and comprehension debt.
Problems Addressed 😔
You lose the ability to debug without the AI.
Your team can't onboard new members into AI-generated modules.
Design decisions become invisible and accumulate silently.
You mistake "tests passing" for "code understood."
Your velocity metrics look great while comprehension quietly collapses underneath.
A junior developer can now generate code faster than a senior engineer can audit it.
The quality gate you relied on disappears.
How to Do It 🛠️
Ask the AI to explain every non-trivial block before you accept it.
Close the chat and rewrite the explanation in your own words in a comment or ADR.
Ask the AI "what assumptions did you make here?" for each function it generates.
Run a 10-minute AI blackout: try to explain the module to a colleague without reopening the chat.
Add a comprehension check step in your PR template: "Can you explain this change in 3 sentences?"
Use the AI for conceptual inquiry: ask why as often as you ask how.
Identify your load-bearing decisions: the choices that, if wrong, will cost you weeks.
Keep a short
decisions.mdfile with one sentence per architectural decision the AI made on your behalf.
Benefits 🎯
Debuggability: You can fix defects without reopening the AI chat because you understand the system.
Onboarding speed: New teammates can read your decisions file and understand why the code exists.
Reduced rework: You catch flawed assumptions before they reach production.
Honest velocity: Your speed metric reflects real output, not deferred understanding.
AI supervision skill: Research shows that cognitive engagement with AI preserves learning outcomes even when you receive AI assistance.
Context 🧠
Comprehension debt is the growing gap between how much code exists in your system and how much any human genuinely understands.
Addy Osmani named and described this pattern in March 2026.
Unlike technical debt, comprehension debt breeds false confidence.
The codebase looks clean.
The tests pass.
The reckoning arrives quietly, at the worst possible moment.
A research team at Anthropic ran a randomized controlled trial with 52 software engineers learning a new library.
The group using AI completed the task in the same time as the control group, but scored 17% lower on a follow-up comprehension quiz (42% vs. 57%) (Shen and Tamkin, Anthropic, 2026).
The biggest drops were in debugging ability.
The researchers found six distinct AI interaction patterns.
Three of them involve cognitive engagement and preserve learning outcomes even when you receive full AI assistance.
The tool doesn't destroy understanding.
How you use it does.
You can also think of comprehension debt as a speed asymmetry problem.
AI generates code far faster than you can evaluate it.
When you write code, the review process is a bottleneck, but a productive one.
Reading the PR forces comprehension.
AI-generated code breaks that feedback loop.
The volume is too high.
The output is syntactically clean and superficially correct: exactly the signals that historically triggered merge confidence.
Surface correctness isn't systemic correctness.
Prompt Reference 📝
Bad Prompt 🚫
Add Redis caching to the UserRepository class.
Good Prompt 👉
Add Redis caching to the UserRepository class.
After you implement it:
1. Explain every non-trivial decision you made.
2. List the assumptions you made about cache expiration,
key naming, and invalidation strategy.
3. Identify any load-bearing decisions: choices that,
if wrong, would require a full rewrite.
4. Write one sentence per decision in decisions.md format
so my team understands why the code works this way.
Considerations ⚠️
Tests are necessary, but they aren't sufficient.
A test suite can only cover behavior you thought to specify.
Nobody writes a test for a behavior nobody imagined.
When the AI updates hundreds of tests to match new behavior, you must ask: "Were all those changes correct?"
Only comprehension can answer that question.
Tests can't.
Specs help, but they aren't a substitute for review.
A spec detailed enough to fully describe a program is more or less the program, written in a non-executable language.
Keep your AI context window short and your decisions file honest.
You document decisions, not transcripts.
Type 📝
[X] Manual
Limitations ⚠️
Comprehension checks add time to each PR.
Your team must agree to slow down a little to stay safe.
Tags 🏷️
- Knowledge Management
Level 🔋
[X] Intermediate
Related Tips 🔗
https://maximilianocontieri.com/ai-coding-tip-006-review-every-line-before-commit
https://maximilianocontieri.com/ai-coding-tip-019-tell-the-ai-why-not-just-what
Conclusion 🏁
AI makes code cheap to generate.
It doesn't make understanding cheap to skip.
Every time you merge code you can't explain, you borrow from your future self.
You will pay for comprehension sooner or later.
Pay it now, with curiosity.
More Information ℹ️
Comprehension Debt: The Hidden Cost of AI-Generated Code by Addy Osmani
How AI Impacts Skill Formation, Shen and Tamkin, Anthropic (arXiv 2601.20245)
Comprehension Debt on O'Reilly Radar
Mitigating Epistemic Debt in Generative AI-Scaffolded Programming (arXiv 2602.20206)
AI Technical Debt Compounds: Augment Code Guide
Also Known As 🎭
- Cognitive-Debt
- AI-Comprehension-Gap
- Invisible-Technical-Debt
- Epistemic-Debt
Disclaimer 📢
The views expressed here are my own.
I am a human who writes as best as possible for other humans.
I use AI proofreading tools to improve some texts.
I welcome constructive criticism and dialogue.
I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.
This article is part of the AI Coding Tip series.
