Don't just vibe code — understand what you're building before cognitive debt kills your creativity
Geoffrey Litt distinguishes two reasons developers need to understand code in the AI era. The obvious one is 'understand to verify' — checking whether agent output is correct. But this role is shrinking as agents get better at self-verification. The deeper, more durable reason is 'understand to participate': rich mental models are the substrate for creative leaps. When you can fluently recombine concepts in your head without querying an agent, you can think faster and more originally.
The central risk Litt names is cognitive debt — the accumulated erosion of understanding that happens during vibe coding. Like technical debt, it compounds silently until you suddenly realize you have no idea what's going on in your own project and can no longer meaningfully contribute ideas. The 50,000-line AI-generated PR is the forcing function that makes this concrete.
Litt proposes three practical countermeasures. First, an 'explain diff' skill: after any significant AI-generated change, produce a structured explainer doc with background context, intuition before details, interactive figures, and literate prose-annotated diffs. Second, a comprehension quiz gate: before sending code to teammates for review, pass a five-question medium-difficulty quiz generated by the agent about what it wrote — this acts as a speed regulator, ensuring you move at the pace of understanding, not just shipping. Third, agent-built micro worlds: use agents to build ephemeral debugger UIs with scrubbable timelines of internal state, so you can *inhabit* your codebase the way Seymour Papert argued children learn math by living in mathland.
A further structural suggestion is shared spaces — multiplayer collaborative documents where humans and agents work together in the open rather than in siloed one-on-one chats. Notion's recent launches of HTML blocks and coding-agent integrations are cited as early infrastructure for this. The bottom line is optimistic: with the right mindset and tooling, AI can enable developers to understand complex systems *more* deeply than before — putting people further into loops, not out of them.
Geoffrey Litt argues that as AI agents write more code, the real risk isn't bad code — it's developers losing the conceptual understanding needed to have the next idea. He introduces 'cognitive debt' and proposes concrete practices to stay in the loop: explain-diff docs, comprehension quizzes, and agent-built micro worlds for inhabiting your own codebase.
The quiz acts as a speed regulator: everything AI speeds up, but the quiz ensures you are moving at the speed of understanding, not just correctness.
With AI and the right mindset, we can actually understand systems better than ever before — putting ourselves more deeply in loops rather than taking ourselves out of loops.
It is still important for people to understand how code works.
Agents are landing 50,000-line PRs and it is getting harder to keep up.
Over time, the role of humans in correctness checking is decreasing as agents get better at verification.
When you have rich conceptual structures in your head that you can fluently recombine really fast without going out to ask some agent or some human how it works, that gives you the ability to fluidly take creative leaps.
Notion launched HTML blocks in Notion pages this morning, allowing interactive simulations inside Notion pages.
Researcher Andy Matuschak uses interactive spaced-repetition quizzes embedded in essays that keep emailing you to ensure you remember the content.
If you just have an agent fix a bug, you don't get peripheral vision of the system; if you live in a micro world, you do.
Agents can write code to help us understand code where the point isn't building software to ship — it's building little micro worlds.
Notion launched last week the ability to bring coding agents including Claude and Cursor into Notion, allowing teams to build code inside a shared collaborative space.
Alan Kay, co-inventor of the modern GUI, wrote an essay 50 years ago titled 'A Personal Computer for Children of All Ages' envisioning kids modifying video game code as they play to learn physics.
You're vibe coding, things are going well, and then at some point you realize you have no idea what's going on and basically can't participate anymore — you've built up too much cognitive debt.
The dominant mental model of why humans must understand code is 'understand to verify' — correctness checking via thumbs-up/thumbs-down decisions on agent output.
The deeper reason to understand code is 'understanding to participate' — your understanding of what's going on is the foundation for having the next idea and being an active creative participant in a project.
Cognitive debt — an analogy to technical debt popularized by scholar Margaret Story and blogged about by Simon Willis — describes how degraded understanding accumulates and eventually prevents participation.
Seymour Papert's concept of 'living in mathland' — creating an environment where learners gain intuitive understanding by inhabiting it, analogous to learning French by living in France — can be applied to understanding code via agent-built micro worlds.
Shared spaces — multiplayer chat threads between multiple humans and agents in a collaborative document — enable collective understanding rather than siloed one-on-one agent conversations.
Use an 'explain diff' skill that produces a code explainer doc structured as: background context, intuition before details, interactive figures, and literate code diffs with prose explanations in the right order.
Do not send code to others on your team to review unless you can pass a five-question medium-difficulty quiz generated by the agent about what the agent wrote.
Have an agent build an ephemeral debugger UI that visualizes the internal state of your program step-by-step on a scrubbable timeline, so you can inhabit a micro world and develop an intuitive feel for how the code works.
“books don't work”
Shared with Earmark · earmark-ai.com