I found myself reading a blog post from Cubic.dev this evening that hit uncomfortably close to home. The article was shared by Rich Seroter with a question that’s been on my mind a lot lately: “Are we piling up ‘comprehension debt’ into our repos as we stuff in code that wasn’t written by humans?”
We have a mountain of documentation that gets generated for all our new features. We’re working with various indexing ideas including tools like NotebookLM. But I keep coming back to the same uncomfortable truth: nothing will ever replace being able to stare at code and understand how bits move through a system.
The Speed Trap
The problem isn’t that AI generates bad code. Often it generates perfectly functional, even elegant code. The problem is velocity.
Jason Gorman at Codemanship describes this well in his piece on comprehension debt: “Comprehension debt occurs when teams produce code faster than they can understand it.” This is the ticking time bomb we’re building.
I run into this occassionally now. Something won’t be working like I want, and my AI fleet is struggling to figure it out. When I dig into the code I find entire components that I wasn’t aware we weren’t using. I once found an entire chunk of middleware. It does some great stuff, to be honest. But it was lurking out there like Planet X.
Why Documentation Isn’t Enough
My immediate reaction after that incident was to analyze my context markdown and agent configurations. I wanted better documentation, better prompts, better systems.
But that’s treating the symptom, not the disease.
A HuggingFace blog post puts it this way: “Comprehension debt is when you build systems more sophisticated than your skill level can maintain.” They describe teams spending days debugging code they never truly understood in the first place.
No amount of markdown files or AI-generated documentation changes the fundamental problem. You can have perfect commit messages, comprehensive READMEs, and detailed architectural decision records. But when something breaks at 2 AM, you need to understand how the system actually works at a fundamental level.
The Trade-off Nobody Wants to Talk About
LeadDev reports that developers get stuck manually debugging code they never truly understood in the first place, with some teams spending days fixing what should have been hour-long problems.
Meanwhile, Google’s 2024 DORA report found that a 25% increase in AI usage quickens code reviews and benefits documentation, but results in a 7.2% decrease in delivery stability. These numbers are similar in the 2025 report as well.
We’re trading understanding for speed. Sometimes that’s the right trade. But we should be honest about what we’re trading.
Beyond the Code Itself
The comprehension gap extends beyond the code logic to the dependencies we pull in.
Brian Fox at Sonatype describes what he calls the LLM dependency trap. AI tools recommend packages based on frequency in training data, not security status or maintenance history. They’ll suggest deprecated packages with known vulnerabilities because those packages appear often in the code they learned from.
Worse, attackers are adapting. They’re releasing malicious packages specifically designed to match common LLM hallucination patterns. They’re gaming the prompts, knowing that developers trust AI recommendations without verification.
This is comprehension debt at a different layer. We don’t understand the code we generate, and we don’t understand the dependencies that code pulls in. Fox describes organizations “increasingly choosing not to notice” what enters their codebase.
When an AI agent adds a dependency, do you check its security advisories? Its maintenance status? Whether it’s even the right package for the job? Or do you trust that the AI wouldn’t recommend something problematic?
Too often, that’s what I do. And that’s the trap.
What I’m Learning
I’m not giving up AI coding tools. They’re too valuable. But I am thinking about how I use them.
When an AI agent generates a complex feature, I’m forcing myself to do a comprehension pass before considering it done. Not a code review where I check for bugs. A comprehension pass where I trace through the logic until I understand why it works.
This is slower. It feels inefficient when the code already works. But the alternative is creating a system I can’t maintain.
The teams handling this well seem to follow a pattern from O’Reilly’s research on AI-resistant technical debt: quick design reviews even for AI-generated code, refactoring when coupling or duplication starts to creep in, and taking a deliberate pass at naming.
It’s not about preventing AI from generating code. It’s about maintaining the ability to understand and modify that code later. Maybe one day this won’t be required. But that day is still a fair ways out.
The Real Problem
The Cubic.dev article nails the core issue: we need to understand how systems work, not just how to generate them.
Rich Seroter’s framing of this as “comprehension debt” is perfect. Like technical debt, comprehension debt compounds. The more code you don’t understand, the harder it becomes to understand any of it. The system grows more sophisticated while your mental model falls further behind.
I don’t have a perfect solution. I’m still figuring this out. But I know that treating documentation as a substitute for comprehension is something I’m working hard to improve.
Maybe the goal isn’t to document our way out of this problem. Maybe it’s to slow down enough that we can understand what we’re building while we’re building it.
Even if the AI could do it faster.