Cognitive Debt in the Age of AI Programming: Comprehension Is the Real Bottleneck

When Massive Amounts of Code Come Flooding In

In today's development landscape, swept up by the AI programming paradigm, we face an unprecedented situation: AI can produce enormous amounts of code in an extremely short time. This may seem like a leap in efficiency, but the real bottleneck quietly emerges—it's not AI's ability to generate code, but rather our human ability to comprehend it.

A Bilibili content creator shared a genuine and profound retrospective based on their web-based game project called "Stealth" (潜行). From the very beginning, AI was involved throughout the entire development process, while the creator played more of a "director" role. However, once the project advanced to a certain point, it actually spiraled out of control. This experience of losing control is exactly the starting point for this article.

When AI becomes the primary force of production, the developer's role undergoes a fundamental transformation: we shift from being the "producer" of code to the "reviewer" and "director" of code. But problems arise along with this—we devote a great deal of energy to verifying the correctness of the code, yet neglect our understanding of the code itself.

What Is "Cognitive Debt"

In the age of AI programming, a new concept has been proposed: cognitive debt (which can also be understood as an extension of technical debt).

Technical Debt is a classic concept in software engineering, proposed by Ward Cunningham in 1992. It refers to the hidden cost incurred by adopting suboptimal solutions for short-term gain, which must be repaid at additional cost in the future. Cognitive debt is its extended variant in the AI era—it's not a debt of code quality, but a debt of the developer's depth of understanding of the code. The core similarity between the two is that debt compounds over time and erupts all at once at critical project junctures (such as drastic requirement changes, the departure of core team members, or the appearance of major bugs), at a cost far exceeding the time originally saved.

How Debt Accumulates

With the help of coding paradigms like Vibe Coding, we can produce large amounts of code in a short period. Vibe Coding is a programming paradigm concept proposed by OpenAI co-founder Andrej Karpathy in early 2025. It refers to developers describing their intent in natural language and having AI generate and iterate on code, with the developer themselves writing almost no code directly, instead using "it feels right" (vibe) as the acceptance criterion. This paradigm dramatically lowers the barrier to programming, but it also introduces a systematic risk of missing code comprehension. Unlike traditional programming, Vibe Coding shifts the developer's attention from "how to write" to "what to write," but at the cost of a sharp decline in the developer's control over the implementation details of the code.

While the project is simple, this is manageable. But as code complexity rises—especially when you give a requirement with a large scope—AI instantly generates massive amounts of structurally complex code.

At this point, human comprehension begins to fall behind the rate at which code complexity grows. Due to a lack of patience, we often skip in-depth understanding of the code and only do simple verification: run the white-box tests and black-box tests, confirm the functionality works, and call it done.

When comprehension can't keep up with the rate of growth in code complexity, cognitive debt begins to accumulate steadily.

The Cost of Debt

When cognitive debt accumulates to a certain point, it brings serious consequences:

• Weakening the foundation for generating new ideas: Only by deeply understanding the code can you build upon it to drive the next creative idea forward. A developer's core value in a project is precisely to "keep pushing creativity forward."
• Forming a "fog" between the developer and the code: Because you don't understand why the AI did things a certain way, or how it was actually implemented, your thinking cannot flow and combine smoothly, ultimately leading to a complete loss of control over the project's progress.

This is exactly the root cause of the creator's project spiraling out of control—they no longer understood how the AI had designed and implemented things step by step, and thus fell into a predicament of being unable to continue participating.

Three Dimensions for Rebuilding Comprehension

How do we escape this predicament? The author proposes three core dimensions: interactive explanation, microworlds, and shared spaces.

One: Interactive Explanation and Cognitive Testing

The traditional approach is to have AI provide code comments explaining the function of each code segment. But this is far from enough. We need AI to explain implementation steps at a higher level.

Take the "Stealth" project as an example. In the early stages of scene planning, the author not only required the AI to provide explanatory documentation but also required it to provide visual effects:

• How the camera positions in the scene are arranged
• The rationale for technology choices (such as choosing Three.js)
• Door setups and lighting layouts
• The actual rendering of elements like the static ground

Three.js is a JavaScript 3D graphics library built on top of WebGL, created and open-sourced by Ricardo Cabello (mrdoob) in 2010. It abstracts the complex low-level WebGL API (shader programming, matrix transformations, rendering pipelines) into a developer-friendly object-oriented interface, making it possible to build 3D scenes, physics simulations, and interactive games in the browser. Choosing Three.js over native WebGL means striking a balance between performance control and development efficiency—but it also means developers need to understand core abstract concepts like the Scene Graph, Camera, Renderer, and Geometry, which is precisely the layer where cognitive debt tends to accumulate.

The key lies in interactivity—developers can adjust parameters within the actual rendered scene and observe their concrete effects. As the author puts it: "Intuition trumps details; great math teachers always instill concepts through interactive models."

Going further, the author introduces the concept of a "speed regulator": AI is always pursuing acceleration, but comprehension requires slowing down. By setting up comprehension test questions and spaced repetition testing, you can strengthen your brain's genuine absorption of the code and reject the "illusion of reading"—that is, mistakenly believing you understand something when in fact you don't.

Spaced Repetition is a learning method derived from psychologist Hermann Ebbinghaus's research on the forgetting curve. In 1885, Ebbinghaus discovered that memory decays exponentially over time, but reviewing just before you're about to forget can significantly extend memory retention. Spaced repetition systems design review schedules accordingly, so that each review occurs exactly at the critical point of memory decay, thereby achieving maximum memory efficiency with minimal cognitive investment. Tools like Anki have widely applied this method in fields such as language learning and medical exam preparation. Bringing spaced repetition into code comprehension means treating software engineering learning like foreign language acquisition, emphasizing the cognitive superiority of Active Recall over passive reading.

One detail worth mentioning: these targeted tests are also generated by AI, and in the process of generating tests, the AI also engages in reverse thinking about the code, which is itself an added value.

Two: Building Microworlds

The concept of the "microworld" originates from the pedagogical idea of "Mathland".

"Mathland" was proposed by computer scientist and educator Seymour Papert in his 1980 book Mindstorms, rooted in constructionist learning theory. Papert believed that children learn best in an environment they can explore and build in, and that abstract concepts should be internalized through concrete, manipulable models rather than mere symbolic memorization. He also invented the programming language Logo, which let children understand geometry by controlling a "turtle" moving across the screen. This idea profoundly influenced the design philosophy of modern STEM education and interactive learning tools, and it directly inspired the logic behind the "microworld" methodology in this article: replacing abstract code explanations with interactive, simplified models.

A microworld refers to a more intuitive simulated environment or temporary UI that developers build to help understand abstract concepts. It's like teaching a child to understand parabolic motion—you wouldn't make them memorize the Wikipedia definition. Instead, you'd build a mathematical model: apply a downward force to an object, let it move along a parabolic trajectory, and present it intuitively through visualization.

In the "Stealth" project, the author had the AI play the role of an "infrastructure builder," writing dedicated, disposable visualization tools or debugging timelines, achieving step-by-step comprehension:

1. Use simple geometric shapes to replace characters and build the scene
2. Add character movement, demonstrating interaction through the scene
3. Introduce NPCs, showing the motion relationship between characters and physics
4. Add walls, implement collision detection, and build a physics world
5. Bind real physics relationships to the characters
6. Add control logic
7. Add more realistic scenes

A typical detail: to make the game character's orientation "observable," the AI helped add an arrow indicator to help the developer better understand how the character throws and how they attack. The author emphasizes:

Writing code isn't just for shipping; a better goal is to build a human mental model.

The benefit of this step-by-step implementation is that goals are clear and easy to verify. Once the physics tests for simple geometric shapes pass, you then bind the real character in, at which point the logic of collision detection is already clear and controllable.

Key Takeaways