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