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

Sign in<br>Subscribe

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...