What is comprehension debt?

What is comprehension debt?

Comprehension debt is the code in a system that nobody on the team can explain, because it changed faster than anyone read and learned it. Some developers call it cognitive debt. It often builds up when coding agents generate changes faster than people review them. It comes due when someone must work out what the code does before changing it.

A 2025 preprint led by MIT Media Lab researchers uses the phrase cognitive debt in a different sense. Its authors compared people who wrote essays with an AI assistant, with a search engine, or with no tool. They use the phrase for a condition in which repeated reliance on the assistant replaces the mental effort of independent thinking. That cognitive debt is a cost to one person's thinking. Comprehension debt is a gap between a codebase and the team that maintains it.

Code can work and read cleanly and still carry comprehension debt, so passing tests do not reveal it. In code review, a reviewer who reads a change closely becomes one more person who can explain it. A quick approval adds nobody.

How does comprehension debt build up?

Understanding of code enters a team when someone writes the code or reads it closely. It is lost when people forget the details or leave the team, and when the code changes after they learned it. The debt builds up in these steps:

1. An author writes a change and chooses what each line does, so one person understands it.
2. A reviewer reads the change. A close reading passes that understanding to a second person, and a quick approval does not.
3. The change merges, and later changes build on it and edit it.
4. Each later edit that nobody reads closely makes what the team learned earlier less accurate.
5. The author forgets the details, moves to other work, or leaves the team.
6. A developer who has to change the code finds nobody who can explain it, and reads it from the start.

The debt grows whenever code changes faster than people read it. A review bottleneck pushes reviewers toward quick approvals. Long diffs make it worse, because pull request size sets how closely a reviewer can read a change.

What is an example of comprehension debt?

Here is an illustrative example. Acme Co. sells furniture online. For 3 months, coding agents have written most changes to its checkout code, and reviewers approved them after quick reads. Then the debt comes due:

1. The developer who built checkout moves to another team, and nobody else has read src/checkout/ closely.
2. A developer at Acme asks a coding agent to "Let customers edit their delivery address during checkout." The change merges after a 5-minute review.
3. A customer reports a failure. The address saved, but the cart emptied.
4. The developer opens saveSession, the one function that writes the session, and finds it replaces the whole session.
5. Nobody, including the developer, can say which callers rely on that, and the commit messages describe each diff, not its reason.
6. The developer spends 2 days reading the 9 callers of saveSession before changing anything.
7. The developer adds a comment that callers must pass the whole session, and the team names an owner for checkout.

The address change passed only the address:

// src/checkout/address.js
await saveSession(session.id, { address: newAddress });

saveSession stored that object as the whole session and dropped the cart. The fix took 20 minutes. The 2 days of reading were the interest on comprehension debt, in code that had nothing to clean up.

This example is simplified. A real checkout would also call payment code that nobody can explain.

What changes when a coding agent writes the code?

When a coding agent writes the code, the name on a change no longer points to someone who understands it. git blame usually shows the developer who ran the agent, and that developer chose none of the lines. A close review is the first time any person learns the change.

The agent does not carry the reasons for a change into later sessions either. Each session usually starts without the conversation of the one before it, so the agent reads the files again. What remains is the code and, if the team saves it, the session history that records the request behind each change.

Agents also raise the amount of code each person has to read. Long, repetitive AI slop takes longer to read closely, so more of it merges after a skim. In vibe coding, nobody reads the code by design, so all of it starts as comprehension debt.

One adjustment is to have the developer who ran the agent explain the change in their own words before review. Reviewers who review a pull request from an agent can ask which existing behavior it relies on, e.g. that saveSession replaces the whole session.

What are the limits of comprehension debt as an idea?

Comprehension debt names a real cost, but the term has limits:

• Nobody can count it directly. Understanding lives in people, not in files, so any count of it is a proxy.
• Unread code is not always a cost. Code nobody changes or debugs charges no interest, and teams use libraries through their interfaces and tests without reading them.
• Understanding does not show that code works. A team can understand code that is wrong, and reading shows what code says, not what it does when it runs. Teams can verify code without reading it, by running its workflows and keeping the evidence.
• Documents are not understanding. A document passes on what its writer learned only to people who read it, and it goes out of date when the code changes.
• The cognitive debt study is about writing. It measured people writing essays, not teams maintaining code, so its results are not evidence about codebases.

How is comprehension debt different from technical debt?

Technical debt is a cost built into the code's structure. Martin Fowler ties it to cruft, which he defines as deficiencies in internal quality that make a system harder to modify and extend. Comprehension debt is a gap in what the team knows about the code. Clean code carries comprehension debt when nobody has read it, and messy code that one developer knows well carries technical debt but little comprehension debt. Cognitive debt, in either sense, differs from technical debt because it sits in people, not in code.

Technical and comprehension debt overlap. Tangled code takes longer to learn, and refactoring it safely needs someone who understands it or a test that records what it does now. Verification debt is another gap, the code whose behavior nobody has checked by running or testing it. A team can understand a change it never ran, or run a change it never read.

FAQs

What is cognitive debt?

Cognitive debt is a cost to a person's own thinking that builds up when an AI assistant does work the person would otherwise think through. A study of essay writing uses the phrase in this sense. Some developers also use cognitive debt as another name for comprehension debt.

How do you measure comprehension debt?

Comprehension debt has no standard measure, because understanding lives in people rather than in files. Teams count proxies instead, e.g. the files that no current team member has edited or reviewed closely. A direct check is to ask whether anyone on the team can explain a module before a change to it starts.

Can documentation pay down comprehension debt?

Documentation pays down comprehension debt when a person writes it after reading the code, e.g. a comment on the rule a function relies on. A summary that a coding agent generates and nobody reads adds unread text instead.

What should a team do when nobody understands a module?

When nobody understands a module, a team can name an owner, trace one workflow through the code, and write down what each part does before changing it. Refactoring comes after that, once someone understands the code or a test records what it does now. Until someone can explain the module, each change to it costs extra time.