Cognitive Debt
Definition
Cognitive debt is the accumulated gap between what a codebase does and what the developer(s) can reason about. Analogous to technical debt (code complexity that slows future work), cognitive debt specifically refers to the human understanding deficit — code exists that no one fully comprehends.
How Coding Agents Create Cognitive Debt
From Simon Willison and Mario Zechner:
- Speed mismatch: Agents can generate 20,000 lines of code in hours. Humans took weeks to write that much — a pace calibrated to their ability to understand it.
- Compound error mechanism: Each individual mistake (“booboo”) is small. With sequential human development, there’s a natural rate limit on mistake introduction. With agents, mistakes accumulate at machine speed, forming what Zechner calls “a monster of a codebase.”
- Removed from the loop: “You have zero fucking idea what’s going on because you delegated all your agency to your agents. You let them run free, and they are merchants of complexity.”
The Bottleneck Problem
The human as bottleneck was a feature, not a bug. The bottleneck paced code production at human comprehension speed. Removing it without a replacement discipline creates runaway complexity.
The new bottleneck is human understanding capacity and review time — but this bottleneck is invisible and doesn’t enforce itself automatically.
Mitigations
- Harness engineering: Encode quality into the environment — tests, linters, automated checks enforce standards even when agent writes code (Harness Engineering)
- Daily code limits: Set explicit limits on agent-generated code per day calibrated to your actual review capacity
- Write architecture by hand: Reserve core design decisions (APIs, data models, system structure) for human authorship
- Aspiration discipline: Resist the speed temptation; ask whether code is actually needed before generating it
Related Pages
Vault Notes
- Flow Agent Systems Research — Notes on RL reasoning, agent teamwork, and coding agent limitations at scale