Comprehension debt: what AI-written code actually costs

Originally published at fathohm.dev . The term "comprehension debt" is Jason Gorman's, from September 2025, carried by Addy Osmani in March 2026 — this piece is about measuring it. There's a module in your codebase that shipped last month. It works. It has tests. It passed review. And if it breaks at 2am, nobody on your team can explain what it does. Ask "who understands this?" about any given file in an AI-native codebase and the honest answer, increasingly often, is no one — not because your engineers got worse, but because the code stopped passing through their heads on its way into production. The decoupling For seventy years, code getting written implied that somebody understood it. The implication was so reliable we never thought of it as an assumption: writing code was the act of understanding a problem precisely enough to express it. However bad the code, however absent the docs, there was at minimum one person — the author, at the moment of authorship — who knew what it did and why. Every practice we have for keeping teams oriented in a codebase quietly leans on that floor: review assumes the author can defend the change, onboarding assumes someone can explain the system, debugging assumes a colleague to ask. AI agents broke the implication. Code getting written and code getting understood are now separate events, and only one of them is scaling. An agent can produce in an afternoon what a team used to write in a month — and the afternoon does not come with a month's worth of understanding attached. The floor of "at least the author knows" is gone: for agent-authored code, the author isn't on your team. It isn't anyone. The gap between what a codebase does and what the humans responsible for it understand needs a name, because things without names don't get managed. It has one, and it has had one for a while. Jason Gorman named it comprehension debt in September 2025 — what happens "when teams produce code faster than they can understand it" — and Addy Osma