Stop shipping code you can't explain.

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.

You built 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.md file 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 used to make you feel safe to merge.

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.