Cover Image Photo by Vitaly Gariev on Unsplash
A scoring system and team practices that make invisible debt visible before it compounds
You ship AI code you don't understand. Your team does too. That's comprehension debt—and it's accumulating faster than you think.
Part 1 explored why this happens. This article covers how to stop it: a scoring system and team practices that make invisible debt visible before it compounds.
This Only Works If...
These practices require organizational support to maximize the gain: changing metrics, accepting short-term velocity drops, creating psychological safety. In my analysis of AI adoption patterns, only 5-10% of organizations successfully implement systematic change.
Three ways to use this guide:
- High-performing org? Implement directly.
- Building change capacity? Use as the vision to advocate upward.
- Org resists all change? Focus on building change capacity first. These practices won't overcome organizational resistance.
Individual practices don't overcome organizational barriers. But within organizations that can change, these are the practices that matter.
What Actually Works
The challenge is using AI without sacrificing the understanding that makes code maintainable.
Every technique in this article serves one principle: make incomprehension visible before code ships, not after.
What You Control
Individual developers face real constraints: velocity metrics, sprint commitments, competing with peers. These practices acknowledge those constraints while building understanding where it matters most.
1. Score your comprehension. This sounds bureaucratic, but it takes five seconds and changes behavior. Before accepting AI-generated code, rate your understanding on a simple scale. A score of 5 means you could teach this to a colleague right now. A 4 means you understand the design decisions and could modify confidently. A 3 means you get the main approach but would need time on edge cases. A 2 means you know what it does but not why it's structured this way. A 1 means you have no idea how this works.
When you force yourself to assign a number, you can't pretend you understand something you don't.
Don't use this as enforcement (that creates career risk). Use it as debt tracking. Scores of 1-2 are comprehension debt you're consciously taking. Document it:
# Comprehension score: 2
# I don't fully understand the caching eviction strategy here.
# AI generated this based on "implement LRU cache" prompt.
# Future maintainer: review LRU vs LFU tradeoffs before modifying.
Over time, notice your patterns. If you consistently ship API endpoint code at score 2, you're building understanding debt in an area you touch frequently. That's data you can act on.
2. Apply understanding selectively. You can't deeply understand everything. Core infrastructure, security, and payment processing should require score 3+ before shipping. Boilerplate, test scaffolding, and configuration can ship at score 2 (you understand the pattern even if you didn't write every line). Prototypes and throwaway code can ship at score 1 (you're explicitly trading understanding for speed).
The key is conscious choice. The problem isn't comprehension debt existing, it's accumulating it unconsciously in systems that will live for years.
3. Force comprehension through writing. After accepting AI-generated code, write 2-3 sentences explaining why it's structured that way:
"This uses a token bucket rate limiter because we need burst tolerance (user can make 10 requests instantly but limited to 100/hour overall). Alternative would be sliding window (stricter but more complex to implement)."
If you can't write this explanation, you don't understand it well enough. The writing forces clarity. No teammate coordination required. This works async, at your own pace, with zero career risk.
The reality of time pressure. These practices slow you down. That's the point. Comprehension debt accumulates because we prioritize speed over understanding. The practices that prevent it require consciously choosing understanding over velocity, at least some of the time.
The pressure to ship is real. But the velocity you gain from AI is borrowed from future maintenance capacity. Teams shipping fast with heavy AI assistance often hit a wall after 6-12 months. Velocity metrics look great initially. Then every feature takes longer than estimated because teams spend half their time understanding code they shipped months earlier.
Teams adopting these practices may see initial velocity drops. But predictability improves dramatically. The choice isn't between fast with AI or slow without AI. It's between fast now and slow later, or slightly slower now and consistently fast ongoing.
When to Accept the Debt
Sometimes comprehension debt is the right trade-off. But make it a conscious trade-off, not a default. Like traditional technical debt, it's a tool. The question is: Are you taking it consciously or unconsciously?
Accept comprehension debt when:
You're prototyping. Speed matters more than understanding. You might throw this code away. Score 1-2 is fine, just don't let the prototype become production.
The code is genuinely temporary. If it has a known sunset date, comprehension debt is acceptable risk.
You're in spike mode. Learning whether an approach is viable matters more than understanding every implementation detail.
Don't accept comprehension debt when:
This is core infrastructure. Authentication, payment processing, data integrity, understand these deeply before shipping.
You're building for long-term maintenance. If this code will be modified frequently, comprehension debt compounds into impossibility.
You're the only person who knows the domain. Your departure creates a succession crisis (remember Sam's story from Part 1).
The difference between traditional technical debt and comprehension debt: Traditional technical debt is conscious ("I'm taking shortcuts in code structure"). Comprehension debt is usually unconscious ("I shipped code I don't understand"). Make it conscious. Document it. Track it. Review it quarterly: "Where did we accumulate comprehension debt? Was it worth it?"
Once you're comfortable tracking your own comprehension, the team-level gaps become visible. You'll notice when code reviews miss understanding, when estimates ignore comprehension time, when retrospectives skip the "do we understand what we shipped?" question. That's when these practices become relevant.
What You Can't Do Alone
These practices require some organizational support but work within existing constraints. You don't need executive approval to start.
1. Change code review culture. This is the highest-leverage team practice. Reviews should verify understanding, not just correctness. A reviewer should be able to say "I understand why this is structured this way," not just "LGTM." Authors should expect to explain design choices, not just show passing tests. And "I don't understand this" becomes a valid reason to block a PR, not just "this has bugs."
Start with one reviewer modeling this consistently. Cultural shifts begin with consistent individual behavior.
2. Build understanding into estimates. This is the most practical lever managers have. Don't estimate AI-assisted tasks at AI speed. Estimate at "AI + comprehension" speed. A feature that takes 3 hours with AI should be estimated as 5 hours. The extra 2 hours is for understanding, documentation, and explanation. Frame it to product as "investing in maintainability," not "going slower."
Track this over 2-3 months. Show that features estimated this way have lower post-launch maintenance costs. That's your business case.
3. Track maintenance burden by comprehension score. When a bug takes 2 days to fix because nobody understood the code, note: "This was originally shipped at comprehension score 1." After 3 months, you'll have data showing that score-1 code has 3x the maintenance cost. That's evidence for changing practices, not just appeals to principle.
4. Create psychological safety for knowledge gaps. Teams won't surface comprehension debt if it's career-risky. Never punish "I don't fully understand this." Reward surfacing gaps early, before they cause outages. Model vulnerability: "I don't understand this either, let's learn together." This is cultural, not structural. You control team culture even if you don't control company metrics.
5. Protect your team from velocity comparison. When asked "Why does your team ship slower than Team B?", have data ready:
- "Our maintenance costs are 40% lower"
- "Our feature modification time is 2x faster"
- "Our bugs-per-feature rate is half theirs"
You're not slower. You're investing differently. But you need data to make this argument.
6. Monthly comprehension retrospectives. Managers create the space; teams run it without managers present. Once a month, the team asks privately: "What code did we ship that nobody fully understands? Which gaps should we fix vs. consciously accept? Are we accumulating debt faster than we're paying it down?" This must be psychologically safe. No blame. No performance review material.
Starting Small
Start with individual awareness. Use the comprehension scale on your own work for a month or two before proposing team changes. When you have data showing patterns (where you consistently score low, which areas have higher maintenance burden), you have credibility to suggest experiments.
Pick one high-risk area, try "score 3+ required" for that area only, and track results. Let evidence drive expansion, not enthusiasm.
If your organization won't move beyond individual practice, you've still improved. Conscious tracking beats unconscious accumulation.
What You're Actually Choosing
The social contract of software development used to be simple: if you wrote it, you understood it. The act of writing guaranteed comprehension.
AI broke that guarantee. Now you can ship code you don't understand. This isn't AI's fault; it's a tool. The question is whether we adapt our practices to maintain understanding or whether we let comprehension debt accumulate until codebases become unmaintainable.
For developers who learned to code with AI assistance, this contract never existed. If you're in this position, you face a unique challenge: building understanding retroactively while continuing to produce. The practices in this article (explanation confidence scoring, delayed explanation, deliberate manual coding for core logic) aren't just about preventing debt. They're about building the foundational understanding that earlier generations developed by necessity.
Teams struggle with this. The temptation to accept everything AI suggests is strong. The velocity gains are real. Management loves the metrics. But six months later, the team can't move fast because they don't understand their own codebase.
Comprehension debt is more dangerous than traditional technical debt because it's invisible. Your tests pass. Your users are happy. Your velocity metrics look great. But your team is accumulating a maintenance bomb. When it explodes, you'll discover you've been shipping code without understanding.
The GitClear data shows the symptoms: more churn, less refactoring, more time fixing recent code. The Uplevel data shows the bug rate climbing. These aren't future predictions. This is happening now, in production systems, across the industry.
The uncomfortable truth is that AI can make us more productive, but only if we resist its most seductive feature: the ability to ship code faster than we can understand it. The 10x engineer in the AI era isn't the one who accepts every suggestion. It's the one who accepts only what they comprehend.
This means saying no to velocity. It means taking time to understand. It means treating "I don't fully understand this" as a blocking issue, not a nice-to-have. It means changing code review culture from "does it work?" to "do we understand it?"
In five years, we'll look back on this moment as critical. Either we learned to maintain understanding while using AI, or we built unmaintainable systems at unprecedented scale. The difference will be whether we valued understanding over velocity.
Your codebase is accumulating comprehension debt right now. Every AI-generated function you don't fully understand. Every pattern you copied without grasping why. Every algorithm that works but you can't explain. It compounds silently until someone needs to modify the code.
Then you'll discover the cost of shipping faster than you can comprehend.
Research Citations
Oregon State University Study (2025):
Qiao, Y., Hundhausen, C., Haque, S., & Shihab, M. I. H. (2025). Comprehension-performance gap in GenAI-assisted brownfield programming: A replication and extension. ArXiv preprint arXiv:2511.02922.
GitClear Analysis:
GitClear. (2024). Coding on Copilot: 2023 Data Suggests Downward Pressure on Code Quality.
Uplevel Research:
Uplevel. (2024). Analysis of GitHub Copilot Impact on Developer Productivity and Code Quality.
Top comments (0)