Feeling lost in your codebase? 5 tips to tackle AI-induced cognitive debt
TL;DR
AI shifts the bottleneck from writing code to understanding it — Jo Van Eyck says teams using coding agents can move incredibly fast at first, then “crash and burn” if their mental model of the codebase and product doesn’t keep up.
Cognitive debt is the gap between the code and your mental model of it — he ties the term to Adi Omani at Google, the paper “Your Brain on ChatGPT,” and an Anthropic study showing that pure AI delegation and autopilot use correlate with worse learning outcomes.
The core operating rule is to separate design decisions from execution — Van Eyck uses a “paint by numbers” metaphor: he defines OpenAPI specs, routes, inputs, outputs, and architectural patterns himself, then lets the agent fill in the implementation.
PR review should test understanding, not just code quality — even if a change is clean and well-tested, he’ll dig when someone ships something like optimistic locking for the first time and ask whether they can actually explain why it works.
One-shot vibe coding is fine for toy projects, not professional software — his advice is to build incrementally from a walking skeleton, slice by slice, because regenerating whole apps makes comprehension debt worse, not better.
Diagrams and ADRs become survival tools when code is cheap — he relies on C4 for static structure, event storming for runtime behavior, and Architecture Decision Records generated from meeting transcripts to preserve why big choices were made.
The Breakdown
The New Failure Mode: Fast Starts, Hard Crashes
Van Eyck opens with the big shift AI coding agents create: writing code is no longer the bottleneck, understanding it is. He’s seeing a widening gap between teams that can maintain a solid mental model and go “at amazing speeds,” and teams that start fast, then “crash and burn” because they never built that understanding.
What “Cognitive Debt” Actually Means
He admits the term is still a little fuzzy, but lands on a practical definition: comprehension debt is the gap between what the code is doing and your mental model of what it should be doing. He points to Adi Omani from Google, the paper “Your Brain on ChatGPT,” and an Anthropic study showing that if you’re mostly delegating or doing iterative AI debugging on autopilot, you’re probably not learning enough to keep up.
The Red Flags: “It Works, Ship It” and Architecture Amnesia
The first warning sign is the reflex to ship code just because it works, without reading or understanding it. The second is what he calls “architecture amnesia”: code can look idiomatic, fit the codebase perfectly, and have great test coverage, but if the engineer can’t explain why it’s structured that way, that’s still a serious problem.
Rule #1: Separate Decisions From Execution
This is his main heuristic. He says he barely writes code by hand anymore — he specs and lets the model generate — but he stays in control by defining the design upfront, like a “paint by numbers” picture he draws himself. In a REST backend, that means manually specifying the OpenAPI contract, routes, inputs, outputs, and verified patterns for controllers, entities, aggregates, and database contexts before asking the agent to implement.
Rule #2: Put Comprehension Into PR Review
A clean pull request isn’t enough; he actively “pulls for understanding.” If someone on his team implements something deeply technical like optimistic locking or optimistic concurrency for the first time, he asks questions to confirm they understand it — and if the answer is basically “I don’t know, lol,” that saved AI time needs to be reinvested into learning.
Rule #3: Build in Slices, and Use AI to Create Learning Moments
For junior engineers especially, he recommends deliberate learning loops rather than passive generation. He highlights Dr. Cat Hicks’ “learning opportunities” skill, which pauses after architecturally significant work and turns the moment into a mini exam; he says if he were junior, he’d install it on day one. He also warns hard against one-shotting entire PRDs and regenerating whole apps: fine for vibe coding, not for serious software.
Live in Diagrams, Not Just Source Files
His next rule is blunt: you have to start “living, breathing, reading, writing diagrams.” He uses C4 diagrams for static system understanding — especially context and component diagrams — and recommends regenerating them whenever code changes so you can notice when arrows and dependencies shift. For dynamic, event-driven systems, he leans on event storming and DDD-style command/aggregate/event flows to understand runtime behavior that won’t be obvious from reading methods.
ADRs: Capture the Why, Not Just the What
His final tool is Architecture Decision Records: short docs that record a meaningful technical decision, the alternatives considered, and why the team chose one path. He used to spend up to two hours writing ADRs after a one-hour architecture meeting; now, using Anthropic’s skill creator plus meeting transcripts or notes, he can generate them in about 20 minutes. The payoff is huge: critical decisions become first-class artifacts in the codebase or wiki instead of disappearing into chat history nobody will ever revisit.