Quick Answer
Comprehension debt is the gap between the code in your repository and the code anyone on your team can explain. AI agents widen it because they write code faster than people read it. Unlike technical debt, it can hide under clean, passing code, and you pay it when something breaks and nobody knows where to look. Pay it down with a 20-minute weekly routine: map what changed, read one main flow end to end, check the most-connected files, and update a one-page note.
What Is Comprehension Debt?
Addy Osmani calls comprehension debt "the hidden cost to human intelligence and memory resulting from excessive reliance on AI" in his essay of March 2026, which O'Reilly Radar republished in April. In practice, it is the distance between how much code your system contains and how much of it any person actually understands.
The term is older than his essay. Jason Gorman wrote about comprehension debt in LLM-generated code in September 2025, and researchers have started to study it: a 2026 paper follows it through 621 diaries kept by 207 students on AI-assisted projects. Osmani treats it as the same thing as cognitive debt, a term used by Margaret-Anne Storey.
How Is It Different From Technical Debt?
Technical debt is a property of the code: a shortcut you will have to undo. Comprehension debt is a property of the team: code that may be perfectly fine, but that nobody can explain. You can have one without the other. A tidy, well-tested module the agent wrote last month can carry a lot of comprehension debt if nobody read it.
| Technical debt | Comprehension debt | |
|---|---|---|
| What it is | Shortcuts in the code | Code nobody on the team understands |
| Where it lives | In the repository | Between the repository and the people who maintain it |
| Can clean code carry it? | No | Yes |
| How you notice | Changes get slow and workarounds pile up | Nobody can explain a module, and fixes break things nobody knew were connected |
| How you pay it down | Refactor | Read, map and write down |
| What AI changes | More duplicated and copied code | More code than anyone reads |
Why Does AI-Written Code Build It Faster?
An agent writes a feature in minutes. Reading it carefully takes longer than writing the prompt did, so the reading is what gets skipped. Three sources point the same way:
- In a randomized trial by Anthropic, 52 mostly junior engineers learned a new library. Those using AI scored 50% on a comprehension quiz, against 67% for those coding by hand, and they were not significantly faster.
- In the 2025 Stack Overflow Developer Survey, the biggest frustration with AI, named by 66% of developers, was answers that are close to right but not quite. 45.2% said debugging AI-generated code takes more time, and 16.3% said it is hard to understand how or why the code works.
- GitClear's analysis of 623 million code changes found duplicated code blocks up 81% from 2023 to 2026, while moved code, a sign of refactoring, fell from 21% of changed lines in 2022 to 3.8% in 2026.
More code, less refactoring and shallower reading add up to a codebase that grows faster than anyone's picture of it.
What Are the Symptoms?
- "Ask the agent" is the only map. Nobody can say where a feature lives without opening a chat.
- Fixes land in surprising places. A change in one file breaks a page nobody thought was connected.
- Reviews approve without questions. Pull requests merge with no comments because the diff was too long to read.
- The same helper exists three times. Each session wrote its own version because nobody knew the first one existed.
- One file does everything. A file grows past 500 lines, or a function past 50, because each session added to whatever was already open. VibeDoctor flags these as god files, god modules and overly complex functions.
- Small changes take days. A new teammate, or you after two weeks away, has to rediscover how a flow works before touching it.
- The agent re-reads everything. Every new session starts by exploring the repository again, because nothing written down tells it where to look.
How Do You Measure Comprehension Debt?
There is no standard metric yet, so use proxies you can check in an afternoon:
- The explain-back test. Pick three modules at random. Can someone on the team explain what each does, where it starts and what data it touches, in two minutes, without opening the code? Count the misses.
- Review depth. Look at the last 20 merged pull requests. How many merged with no human comment at all?
- Surprise rate. For each bug fixed this month, did the fix land in the file you first expected? Count the ones that did not.
- Time to "where is it?". Ask "where do we check if a user can see this record?" and time how long the answer takes.
Write the numbers down. The trend matters more than the first reading: if the misses grow while the codebase grows, the debt is compounding.
A 20-Minute Weekly Routine
Four five-minute steps, once a week, on the parts of the codebase that changed. Each step has a free way and a VibeDoctor way.
| Step | Free way | VibeDoctor way |
|---|---|---|
| 1. Map what changed (5 min) | git log --since="1 week ago" --stat lists the files each commit touched | The report's "What changed since last scan" card shows what got better or worse; for the functions you changed, vibedoctor_graph with impact shows what depends on them |
| 2. Read one main flow (5 min) | Ask your agent to trace one flow, such as checkout, and read every file it names | VibeDoctor Vibe Story walks through each part of the app in plain English, step by step, naming the function behind each step |
| 3. Check the most-connected files (5 min) | For JavaScript and TypeScript, madge or dependency-cruiser draw the import graph, so you can see which files everything else depends on | VibeDoctor X-Ray maps modules, files, functions and the dependencies between them, and updates with every scan |
| 4. Write it down (5 min) | Update a one-page ARCHITECTURE.md, or the top of CLAUDE.md or AGENTS.md | The same note, kept short because vibedoctor_ask answers "where is this handled?" |
Step 4 is the one people skip, and the one that pays back fastest. A page that says where each flow starts and which files matter is read by every new teammate, and by your agent at the start of every session.
Where VibeDoctor Fits
None of these tools replace reading. They tell you which few files to read first.
- VibeDoctor Vibe Story explains each part of your app in plain English, flow by flow. The free alternative is asking your agent to trace a flow, then reading the files it names.
- VibeDoctor X-Ray is a four-level explorer of modules, files, functions and the dependencies between them. Your agent can query it through
vibedoctor_graphfor context, blast radius and traces before it edits. The free alternatives are madge or dependency-cruiser for the import graph, and GitHub's code navigation for definitions and references. vibedoctor_askanswers questions about the codebase's structure from inside the agent. The free alternative is search, plus your agent reading the files it finds.
To try them from Claude Code or Codex, paste this into the agent:
connect to vibedoctor using https://vibedoctor.io/mcp/startNot a developer? Connect your GitHub repository on vibedoctor.io for a free scan. VibeDoctor X-Ray maps the whole app, and the first chapter of VibeDoctor Vibe Story is free.
If you inherited the codebase, start by mapping what the AI built. To stop new debt at the source, make your agent check its own code before it says done.
FAQ
Who coined the term comprehension debt?
The earliest use we found is Jason Gorman's, in a September 2025 post about LLM-generated code. Addy Osmani wrote about it in March 2026, and O'Reilly Radar republished his essay in April 2026. The phrase may be older than either.
Is comprehension debt the same as technical debt?
No. Technical debt is a shortcut in the code that you will have to undo. Comprehension debt is code nobody on the team understands, and it can sit under clean code that passes every test.
Can AI help pay down comprehension debt?
Yes, if you use it to explain rather than to delegate. In Anthropic's trial, AI assistance lowered comprehension scores, except for people who used it for explanations and conceptual questions. Ask your agent to walk you through a flow, then check its answer against the code.
How do I know if my codebase has comprehension debt?
Pick three modules and ask someone to explain each one in two minutes without opening the code. If most attempts fail, or every answer starts with asking the agent, you have it. Repeat the test each month and track the misses.
Does comprehension debt matter for a solo founder?
Yes. You in three months are a new teammate. If an agent wrote most of the app and nobody read it, the debt comes due with the first serious bug, exactly when you need to know where to look.