Comprehension Debt: The Hidden Cost AI Tools Won't Show You

Addy Osmani, engineering lead at Google, recently named something that every developer using AI tools has felt but couldn't articulate: comprehension debt.

It's the gap between the code you ship and the code you understand. Technical debt is code that needs to be rewritten. Comprehension debt is code that works fine but lives in your codebase like a black box. You accepted it. You shipped it. You can't explain it.

And unlike technical debt, nobody tracks it. There's no linter for understanding. No CI check that fails when you don't know why your own code works.

How it accumulates

Every AI coding tool optimises for the same thing: get code into the editor faster. Cursor autocompletes. Claude Code generates entire files. Copilot fills in the blanks. The implicit promise is that faster output means faster progress.

But progress and output are not the same thing. Every function you accept without understanding is a deposit into your comprehension debt account. Every architectural decision the model made on your behalf is a liability you'll pay interest on when something breaks at 2am and you have to debug code you never actually wrote.

GitClear's analysis of 150 million lines of code found that AI-assisted codebases have significantly higher churn rates. Code gets written, then quickly rewritten or deleted. That's not speed. That's comprehension debt compounding. You ship it, you don't understand it, and then you or someone else has to rewrite it because nobody knows what it was supposed to do.

Why it matters more than you think

Comprehension debt doesn't just slow you down. It erodes something harder to measure: your growth as an engineer.

Nabeel Vandayar, a Senior Software Engineer at Microsoft, put it better than I could:

“The modern agentic workflow leaves more artefacts for agents than developers. Software development without personal development is building with hopes and prayers.”

He described the same anxiety I hear from developers everywhere. The feeling that AI tools are making them faster while simultaneously making their skills atrophy. They're shipping more code than ever but understanding less of it.

“It will help developers see their knowledge grow rather than atrophy in a world where much of the tasks that used to teach us lessons are being outsourced.”

That word keeps coming up. Atrophy. Developers aren't worried about being replaced by AI. They're worried about quietly becoming worse at their craft while looking more productive on paper.

The knowledge you lose doesn't come back for free

Nabeel raised something I hadn't fully considered: the idea of portable knowledge. An evolving understanding of software engineering that you take with you from project to project, team to team, and company to company.

“The idea of an evolving knowledge graph that you take with you from project to project, team to team and beyond is something that really interests me.”

When you let comprehension debt accumulate, that portable knowledge never forms. You finish a project and move on with nothing but a git history. The patterns, the architectural reasoning, the debugging instincts that should have been forged in the work never materialise because the AI did the thinking and you did the accepting.

Osmani's framing is precise: comprehension debt isn't about being against AI tools. It's about recognising that using them without a deliberate learning practice means you're trading long-term capability for short-term velocity. And that trade gets worse over time, not better.

Why I'm building Pear

I'm a self-taught developer. Four years ago I wrote my first line of code. Today I ship production Go services, manage infrastructure, and run five parallel Claude Code agents to build software solo. AI tools made that possible.

But I also know exactly how it feels to accept code you don't understand. To ship a service and not be able to explain half of how it works. To realise that the speed you gained came at the cost of the understanding that would have made you a better engineer.

That's why I built Pear. It sits in your terminal alongside your AI coding tools. It watches your diffs, reads your codebase, and teaches you the concepts behind the code you just shipped. Not in a separate course. Not in a tutorial you'll never finish. Right there, in context, at the moment when the knowledge is most relevant.

Pear doesn't write code. It doesn't autocomplete. It does the one thing no AI coding tool is designed to do: it makes sure you actually understand what you built.

Comprehension debt is real. It compounds. And right now, nothing in the developer toolchain is designed to pay it down.

Pear is.