There's a new kind of risk accumulating in some software projects. And we're sorry to say, it's not going to be showing up in sprint velocity, test coverage, or your delivery partner's status report.
It's called comprehension debt.
Comprehension debt is the gap between what a system does and what people actually understand about it.
The concept has been building momentum in engineering circles of late, with Google's Addy Osmani, researchers at MIT and Anthropic, and a growing chorus of practitioners all converging on the same uncomfortable observation: as AI coding tools generate more and more of a codebase, the gap between what exists in the system and what any human genuinely understands is quietly widening.
Unlike traditional technical debt, where someone chose a shortcut and roughly knows where it lives and what the tradeoff was, the core fear with comprehension debt is false confidence. The codebase looks clean. The tests pass. The metrics look great. All our normal checks and balances are in order.
The fear then is that the reckoning will arrive later.
And Murphy's law says that will be at the worst possible moment.
Why comprehension debt matters beyond developers
If you're commissioning a significant piece of software, a platform rebuild, a new digital product, a complex integration, comprehension debt is something you need to be thinking about too. If you are responsible for a $500K–$2M software investment, this risk sits with you, not just your developers.
Here's why. Every codebase carries an invisible layer of understanding: the reasons behind architectural decisions, the trade-offs that were weighed, the edge cases that were considered and deliberately handled. When that understanding lives in the heads of the people who built it, the system can evolve intelligently. When it doesn't, you get a system that works today but resists change tomorrow.
AI-assisted development accelerates this dynamic in a way we haven't seen before. A developer using AI tools can now generate code faster than even a senior engineer can critically review it. The output can be syntactically clean, well-formatted, superficially correct, precisely the same signals that historically triggered confidence. But the argument goes that surface correctness isn't the same as systemic understanding.
The velocity looks fantastic right up until someone needs to modify something six or twelve months later and discovers that nobody can explain why it was built that way.
For us, this is a very real part of our dialogue, and our approaches. By and large we build, support and enhance software products for people who measure ROI over the long term. It is not unusual for us to be around long after the partner-side build teams have moved on. Understanding both how and why things work the way they do is part of what we optimise for in our organisational and team structures. What we are curious or concerned about then, is what happens when this dynamic fundamentally shifts, how and where is that comprehension debt going to show up.
Why current metrics fail to detect comprehension debt
How we measure "good" hasn't changed. It also isn't signalling when something is going astray. This is a core part of what makes comprehension debt particularly tricky for anyone overseeing a digital investment.
Velocity metrics look immaculate. Code coverage is green. PR counts are up. The delivery cadence feels great.
But none of those things tell you whether the team actually understands the system they're building. And the incentive structures in most organisations optimise for what gets measured. What gets measured no longer captures what matters most - whether the people responsible for your system can reason about it at an architectural level.
An Anthropic study earlier this year put some numbers around this. In a controlled trial with 52 software engineers, participants who used AI assistance completed tasks in roughly the same time as a control group, but scored significantly lower on comprehension afterwards. The largest drops were in debugging. The researchers found that passive delegation (essentially asking the AI to "just make it work") impaired understanding far more than using AI to ask questions and explore trade-offs.
The potential of these tools is insanely exciting. At the same time our collective wisdom and lived experience hasn't had anything like enough time to catch up.
Why tests and specs don’t solve comprehension debt
The instinct to lean harder on automated testing and detailed specifications is understandable. Write more tests. Write better specs. Let machines check machines.
And we definitely think this helps. But it will have a hard ceiling.
Because you can't write a test for behaviour you haven't thought to specify. And we often don't think of those things if we haven't got loads of time to work through the edge cases as we prepare to build and test with SMEs. That's the class of failure that slips through when understanding is thin, not because the test suite was poorly written, but because nobody thought to look there.
Detailed specs have a similar limitation. Any spec thorough enough to fully describe a non-trivial system starts to become more or less the program itself, just written in a language that can't be executed. And it still doesn't capture the hundreds of implicit decisions, data structures, error handling, performance trade-offs that emerge during implementation.
Requirements also emerge through building. Edge cases reveal themselves through use. We know these things to be true. Using AI doesn't change this, it just adds a new layer of decisions made without human enough deliberation.
Comprehension debt vs technical debt
Comprehension debt isn't always a bad thing. Like traditional technical debt, it can be a legitimate tool. You might deliberately accept thin understanding in a prototype, a spike, or a piece of code with a known sunset date. And damn, but these things can be fun & rewarding to create, the speed and ease is absolutely part of the joy.
But it should also be a conscious trade-off. If speed matters more than depth in this context, that's fine. You might ultimately throw the code away anyway.
The problem is when it accumulates unconsciously. When nobody on the team realises they've shipped core infrastructure they can't fully explain. When the prototype quietly becomes production. When the "temporary" integration is still running two years later and the person who built it has moved on.
Traditional technical debt is usually conscious, someone chose a shortcut in code structure and roughly knows the cost. Comprehension debt is usually unconscious. That's what makes it dangerous. Managing risks you don't know you're carrying, that's scary-real.
The difference matters enormously if you're overseeing a digital investment. The question to ask your delivery partner isn't "how fast are you shipping?" It's "how much of what you're shipping do you actually understand? And where have you deliberately chosen not to, versus where has it just happened?" As of today, not a single partner has thought to ask us this, and that makes us pretty uneasy.
How to manage comprehension debt in AI-driven development
The engineering community is working through this in real time, and some practical patterns seem to be emerging. For anyone responsible for a significant digital investment, and for the teams building the software, the principles translate directly.
Make understanding a delivery constraint, not an afterthought. The most effective teams are treating comprehension as something that gets built into the work, not bolted on at the end. That means being explicit about what a change is supposed to do before it's written, and verifying that the humans involved can explain in their own words, why that code is structured the way it is.
Apply understanding selectively. You can't deeply understand everything, and you shouldn't try. The discipline is in knowing where depth matters. Core infrastructure, security logic, payment processing, and anything your business depends on long-term, these need genuine comprehension before they ship. Boilerplate, test scaffolding, and configuration can absolutely tolerate thinner understanding. Prototypes and throwaway code can move fast with minimal comprehension, as long as everyone knows that's the deal. The key is conscious choice about where the debt sits.
Use AI to think, not just to produce. The research consistently shows that developers who use AI to explore trade-offs and ask questions retain far more understanding than those who use it purely for delegation. The difference between "write this for me" and "help me think through the options" is enormous. Teams that treat AI as a thinking partner rather than a code factory, will end up with systems they can actually maintain.
Build understanding time into estimates. This is one of the most practical levers available. Don't estimate AI-assisted tasks at AI speed. Estimate at "AI plus comprehension" speed. For example, a feature that takes three hours to generate should still be estimated at five. That extra two hours is for understanding, testing, documenting, and explanation. Teams that do this may see initial velocity dips, but predictability should improve and the future maintenance burden six months later should absolutely be measurably lower. We're trying to frame this as investing in maintainability … not going slower.
Protect the people who hold the mental model. As AI output goes up, the engineer who truly understands the system becomes more valuable, not less. The ability to look at a change and immediately know which behaviours are load-bearing. To remember why an architectural decision was made under pressure eight months ago. To tell the difference between a refactor that's safe and one that's quietly shifting something users depend on. That knowledge is the scarce resource the whole system depends on, and it's exactly the kind of knowledge that will get hollowed out if comprehension isn't actively maintained.
Make comprehension visible through review. Something we haven't introduced yet but are keen to try are regular "comprehension reviews", not code reviews focused on correctness, but sessions where someone other than the author reads through AI-heavy work and adds the "why" comments. Anything nobody can explain should be flagged for rework.
Why comprehension debt is a business risk
At MadeCurious, AI is a core technology. It's exciting, it's transformative, but we are fully expecting it to hit our world, our work and our ways of working in all sorts of ways. We're both learning, growing and innovating but also consciously slowing down to critically consider what we already know to be true and where we see it coming under pressure in the world ahead. We've been doing software delivery for over two decades, we've seen (created and addressed) all sorts of flavours of technical debt… including the kind where understanding evaporates and systems become impossible to evolve.
Comprehension debt is the same problem wearing new clothes, accelerated by new tools.
We still believe that the real differentiator in software delivery isn't the speed at which code gets written. It's the quality of thinking that happens before, during, and after. Curious minds asking the right questions. Deep enough understanding of the problem and the system to make good trade-offs under pressure. And being accountable for what gets shipped, not just that it ships.
AI can absolutely amplify our capability. But understanding, real, human understanding of what a system does and why, remains the thing that makes complex software work over time. Not just at launch.
Comprehension debt is a growing risk in AI-driven software development. Managing it requires deliberate thinking, not just faster delivery. We're confident that making code cheap to produce doesn't make understanding cheap to skip. The comprehension work is the real work and we all need to be focusing on ways to keep that work front and centre.
