← All writing

AI

Comprehension Debt: The AI Code Bill Nobody Sees

Mani G 3 min read

Developer at a laptop facing a tall stack of code blocks that fades into fog and question marks, with a growing bill beside it

Picture this. An agent writes a pull request in four minutes. The tests are green, the diff is tidy, the reviewer clicks approve. Then someone asks how the retry logic works, and the whole team goes quiet. That silence has a name now: comprehension debt. It's the phrase doing the rounds on dev X this week, and I think it's the most honest term the AI coding crowd has come up with so far.

What comprehension debt actually means

Addy Osmani gave the cleanest definition in a March 2026 essay. Comprehension debt is "the growing gap between how much code exists in your system and how much of it any human being genuinely understands."

Technical debt lives in the code. You can point at the ugly module and say "that one." Comprehension debt lives in people's heads, or more precisely, in the holes in them. A recent arXiv paper on the topic says it "resides in the collective cognition of development teams rather than in the codebase itself." That's the bit that bugs me. The code can be clean, readable and well tested, and still nobody knows why it has the shape it has.

Osmani's sharpest point: technical debt announces itself with slow builds and tangled dependencies. Comprehension debt "breeds false confidence." Everything looks fine right up until the bill arrives, usually at the worst possible moment.

A quick example

Say you ask an agent to add rate limiting to your API. It writes middleware, a Redis counter, tests and docs. You skim it, the tests pass, you merge.

Three months later, users in one region start getting blocked at random. Now you're debugging a sliding-window algorithm you never chose, with a key format you never read, while Slack is on fire. You're paying interest on a loan you didn't know you took out.

Writing it by hand might have cost an afternoon. Understanding it during an outage costs a lot more.

The numbers are not great

Anthropic ran a randomized trial with 52 mostly junior engineers learning Trio, a Python async library none of them had used. The group with an AI assistant finished about two minutes faster, a difference that wasn't statistically significant. On the quiz afterwards, they averaged 50% against 67% for the people who coded by hand. The biggest gap was on debugging questions. That's exactly the skill you need to catch an agent's mistakes.

The same study has the good news too. People who used the assistant to ask questions and get explanations kept far more than people who just said "make it work." The tool isn't the villain. Passive use is.

The arXiv paper, built on 621 reflective diaries from 207 students over eight weeks, found four ways the debt piles up, including "AI-as-black-box code acceptance" and "verification-bypass." It also found one way out: students who used AI as a comprehension scaffold, some of them rewriting the generated code before committing it.

What I'm going to try

Nothing fancy:

  • Keep agent changes small enough to actually read.
  • Before merging, explain the change out loud, happy path and failure path. If I can't, it doesn't go in.
  • Ask the agent "why this approach?" and not only "do this."

Osmani has a line I keep coming back to: "Making code cheap to generate doesn't make understanding cheap to skip."

Sources: Addy Osmani, Comprehension Debt, Anthropic, How AI assistance impacts the formation of coding skills, Comprehension Debt in GenAI-Assisted Software Engineering Projects (arXiv).

So here's my question for you: how much of the code you merged this month could you explain without opening the chat history?