Cognitive debt

Canonical version: Cognitive debt.

Cognitive debt is the cost of not understanding how your own code works. It's distinct from Technical debt: technical debt is about code quality (messy code that works but is hard to maintain), while cognitive debt is about comprehension gaps (clean code that you can't confidently reason about because you didn't write or review it).

The concept becomes critical in Agentic Engineering. When AI agents write code, developers risk losing comprehension of their own systems. If the core of an application becomes a black box, you can no longer confidently plan around it, debug it, or extend it. Simon Willison frames this risk clearly: cognitive debt impairs development velocity because reasoning about code you don't understand is slow and error-prone.

Cognitive debt compounds. Each piece of unreviewed agent-generated code adds to the gap. Over time, the developer's mental model of the system diverges from reality, mirroring the same dynamic as Context Drift but in the human's understanding rather than the AI's context. The loop-engineering community names the system-side of this same gap Comprehension Debt: the code nobody has read, accumulating while the loops run.

Mitigation strategies include:

• Code review: actually read what the agent produced, don't just check that tests pass
• Linear walkthroughs: have the agent explain code step by step (see AI-assisted code comprehension)
• Interactive explanations: build visual/animated demonstrations of algorithms to develop intuition
• Agentic TDD: test-driven workflows force engagement with behavior, even if you skip implementation details

The balance is pragmatic. You don't need to understand every line. But you need to understand enough to reason about the system's behavior, constraints, and failure modes. The moment you can't explain why something works, you've taken on cognitive debt.

The Understanding Bottleneck

Andrej Karpathy articulated the same insight as a load-bearing principle at Sequoia AI Ascent 2026: "You can outsource your thinking, but you can't outsource your understanding." Cognitive debt is what accumulates when you ignore that principle. The agent can do the work; only the human can hold the model of why the work matters and whether it's correct. In the Software 3.0 era this is not a quaint humanist plea but a structural constraint: someone in the loop must remain the director, otherwise the system silently drifts into states no human can recover from.

References

• https://simonwillison.net/guides/agentic-engineering-patterns/interactive-explanations/

Related

• Technical debt
• Cognitive load
• Agentic Engineering
• AI-assisted code comprehension
• Agentic TDD
• Context Drift
• Code is cheap, quality is not
• Simon Willison
• Andrej Karpathy
• Vibe Coding
• Software 3.0
• Obsidian Starter Kit - Foundation - AI Augmentation Philosophy - The OSK doc that frames cognitive debt as the core risk of AI-augmented PKM
• Obsidian Starter Kit - Tutorial - Managing AI sessions - Operational guidance to keep cognitive debt from compounding in OSK sessions
• Comprehension Debt
• Loop Engineering

About Sébastien

I'm Sébastien Dubois, and I'm on a mission to help knowledge workers escape information overload. After 20+ years in IT and seeing too many brilliant minds drowning in digital chaos, I've decided to help people build systems that actually work. Through the Knowii Community, my courses, products & services and my Website/Newsletter, I share practical and battle-tested systems.

I write about Knowledge Work, Personal Knowledge Management, Note-taking, Lifelong Learning, Personal Organization, Productivity, and more. I also craft lovely digital products and tools.

If you want to follow my work, then become a member and join our community.

Ready to get to the next level?

If you're tired of information overwhelm and ready to build a reliable knowledge system:

• 📚 KM for Beginners — 10+ hours of structured video lessons
• 🚀 Obsidian Starter Kit — Ready-made vault with 40+ templates
• 💼 Knowledge Worker Kit — Complete guides + lifetime community
• 🦉 1-on-1 Coaching — Personalized guidance
• 🎯 Join Knowii — Community + ALL courses & tools