We need more than a metaphor: here are testable diagnostics for comprehension debt

Comprehension Debt emerges! We need levers to move it

If in the last seven months you’ve passed within five hundred miles of any software team, including but not limited to exposures such as catching sight of the coastline of California from a whale watching tour, or stopping for more than two minutes at a rest stop while driving down the 5, you’ve probably had exposure to the idea of comprehension debt.

Comprehension debt proposes, basically, that people in software are building stuff at a pace that outstrips their knowledge of what they’re building. Addy Osmani wrote about it in March, citing researchers like Storey describing “cognitive debt” in February (picking up a 2025 study^[1]), then O'Reilly ran it, and within a few months it was everywhere including in a followup from Storey, a name for the widening gap between how much code exists and how much any human actually understands. Perhaps most impactfully, before all of that, Anthropic released a study on “How AI assistance impacts the formation of coding skills” which many people have taken as confirmation of this phenomenon (operationalizing it as: folks show worse recall for novel coding concepts on a quiz specifically after they fully delegated to AI, vs participants who used AI more to build comprehension. Worth noting the very small sample size of this study, making it more of a case study than a reliable source for % estimates).

Comprehension debt is a good name! It spread because it's really dragging an uncomfortable feeling about agentic development into the spotlight. We learn what we practice and what we spend more time on, and manual work can be one path to that. When you stop manually writing code and automate and offload generation of it, many causal choices, relationships and trade-offs about the system being built are no longer forced to pass through your individual mind.

However, however. We also have a ton of strategies available to us for learning and building comprehension through mental models, even when we offload, and even when we didn’t create the thing we’re learning about. In fact, as a learning scientist, I might argue that we mostly learn theories about features in the world we ourselves did not build, so it would be really strange if our minds didn’t have ways to do this. We have so many ways to build comprehension of systems we didn’t build ourselves, and a ton of those ways can even be given more power and credibility in our workplaces. In fact, even Storey’s popular cognitive debt piece which has been shared around as an example of doom, actually highlights as recommendations the high-level learning enabled by agentic tools, and social practices. I think we’re just at the beginning.

We can take both hope and strategy from the existing structure of our minds and their incredible ability to learn. We are all born into a world we mostly don’t understand, and few of us invent from scratch the technology that we contribute to. A few tantalizing, illustrative snippets from this culture & technology paper I enjoyed: “human collectives can develop technologies that no single individual could discover on their own” / “Humans have engineered many clever solutions for distributing cognition” / “Some innovations reduce cognitive load by creating information bottlenecks that restrict the information that an operator must process.” / “One way to coordinate is through innovations that make it easier to know what others are doing. Some of these innovations involve documentation.” / “we suggest that the path to using complex technologies runs through successful cognitive distribution.”

In a world where we need to take advantage of agentic work but also build comprehension where and when we need it, how can we? I’ve argued that injecting active learning back into your day, with efficient metacognition building strategies, is such a way to build back your theory and still get to work with AI. In fact, I think even imperfect AI tools, in our messy orgs now, present a lot of opportunities to experiment with this. My Learning-Opportunities skill is a demonstration of how easy it is to actually create an understanding shift through efficient behavioral experiments (and check out its citations for some deeper research about illusions of fluency vs metacognition! Bonus, I have a talk about protecting learning in the agentic era, if your org needs to hear it reach out). Aidan Harding recently took my learning-opps inspiration forward to think about further learning inside agentic workflows.

So it’s possible to work agentically and care about your comprehension. But we all know that this ideal set of learning activities isn’t happening inside our organizations all the time.

So another big question I have is: what can we learn about what’s making comprehension debt more likely? What’s blocking technical workers from theory-building as they work with these new tools?

As I’ve interviewed developers about their learning, I’ve been thinking that just sticking with the metaphor of comprehension debt slides in a really interesting set of unquestioned assumptions. Almost all the commentary I’ve seen is describing the main driver of comprehension debt as a judgment problem. People are caught up in the fluency effect of generating output, and are therefore convinced it’s always right. We just need to convince them that the AI code is more fallible, and to be sensible people, and to care about code quality. The angrier versions of this frame it like everyone who is using AI to code is a total moron who never questions the agent.

But that's not how we think about human behavior, and shifting it, in the behavioral sciences. Behavioral science demands that we think carefully about the reasons that exist in a moment of a decision and a choice, that make a certain set of strategies seem like the right thing to do for a person. Plus on the face of it I’m simply not convinced that we never question agentic output is what developers are telling us. In Sonar's State of Code Developer survey from January, 96% of developers said they don't fully trust that AI-generated code is correct, but only 48% of them check it before committing. This stat is old now relative to the pace of AI adoption, but based on my continual interviews and conversations with development teams…still matches what they’re telling me.

If anything, technical people in the summer of 2026 have more absurd experiences of the agent being wrong under their belts. In my work, I have been pilot testing a scale on how much developers trust the quality of AI output that their orgs are getting and how reliable they think it is that people can get to that outcome, and the majority think results are still highly variable (whether or not AI is seen as the cause of that variability versus the org itself and the structure of the data and information space in the org, is a further source of variability. I love measuring attributions!). As I’ve interviewed developers in my consulting engagements and in my exploratory interviews while developing the learning-opportunities skill, it’s been very rare indeed that I talk to someone who doesn’t seem to understand and spontaneously bring up the risk that generated code can pull you into getting far ahead of your own understanding as it builds the wrong thing.

When I look at this kind of landscape, I think: one thing we can learn from this is that distrust in "correctness" alone so far doesn't seem to predict a different pattern in committing agentic code, at least from a sheer quantity and velocity pov. Increasing distrust therefore might not be an adequate lever to pull to get fewer of the behaviors we think are leading to comprehension debt. Which is interesting, because it doesn’t really match the story that the entire cause of comprehension debt is “developers trust AI output too much.”

Simply knowing about “Comprehension debt” doesn’t really tell us what to do here because it may describe what you see, but it doesn’t tell you the cause. It's a symptom. Underneath symptoms are organizational conditions that make slow, careful, understanding-building work harder to justify, make it less safe to admit you need active learning, and most likely, push developers to ignore their own distrust signals or choose against them in various contexts, or make larger verification strategies fail. Unlike just staying at the level of the symptom, measuring those conditions and what they produce in an environment can diagnose which intervention will be more likely to move that outcome.

For paid subscribers after the cut, I’m releasing a measure of one of the conditions that I think really brings clarity to a driver of comprehension debt. I’ve named it Overproduction Pressure, and I’ve been experimenting with how to measure it practically for teams. Stick with me through some methodological rigor and the defensibility details that will help you wield this measure more accurately, then at the end, you’ll get the whole measure plus an additional measure I think most people are missing, looking at how AI is changing developers’ decisions about what tasks to take on. Let's go!