Comprehension Debt Is a Debt
A Field Guide entry in “AI-Native Ways of Working.”
None of the code I ship is code I wrote. I'm not an engineer. The agents write every line, and my job is to point the work in the right direction and decide whether what comes back is any good. Most days that's the best trade I've ever made.
Then there are the other days. A tool an agent built can sit finished for a week before I have a reason to open it, and when I finally do, two questions land at once. Can this actually do what I think it can? And did I ever really know what it was supposed to do? The work was done, or done-looking, and I had no account of it until I reached for it.
It shows up in conversation too. Someone asks how my setup is running, whether the tests pass, and I notice I can't say. For all I know it's fine; I just can't tell you. I'm building things I don't have the vocabulary for yet, on systems I own and can't speak to.
That gap is what this essay is about. I've been calling it comprehension debt. The name isn't mine alone — Addy Osmani wrote about comprehension debt earlier this year: the gap between how much code exists in a system and how much of it any human actually understands. That's the engineer's version of the problem. The one I've been living is wider.
Comprehension debt is the gap between what your systems actually are and what you actually know about them. And I mean all of it: which features exist and how finished they are, what still needs testing before it's done, whether what you asked for got built or is half-built, how any of it works underneath. Then the layer that hides best: whether you even know what you're supposed to know about your own system, and how deep. What you know gets measured by what you can honestly say when someone asks. Most days I'd put it more simply: I don't know what's going on anymore, or what I'm supposed to be doing, or where we are.
A borrowed map
Software already has a loan like this, and a decent map of it. Ward Cunningham called shortcuts in code technical debt in the early nineties. Martin Fowler later sorted that debt along two axes, the technical-debt quadrant: deliberate or inadvertent, prudent or reckless. The grid separates debt you chose from debt that just happened to you.
My own pile sorts the same four ways, and Fowler's map is the fastest way I've found to read it.
Deliberate and prudent: I let the work run ahead on purpose, because a deadline is worth it, or because I'm testing an idea and reading every line would defeat the point.
Deliberate and reckless: I know I've lost the thread and could stop to catch up, and I keep dispatching anyway. No deadline is making me. It just feels better to start than to stop.
Inadvertent and prudent: I understood the work the day it shipped. Then I looked elsewhere for weeks and the understanding drained out of me. Nobody was careless. I just know now what I should have written down then.
Inadvertent and reckless: the pile I made out of not knowing better, work I never understood because I didn't know enough to know what I was missing.
Two things about agent speed make this harder than it was for Fowler's engineers. The first: I slide between these cells without noticing. Monday's deliberate, prudent call is inadvertent debt by Friday, because I meant to go back and never did. The second is a region his grid has no box for. The engineers he wrote about could open the code and look at it. A lot of mine I can't, because I've forgotten it's there: the unknown unknowns, work I started and lost track of, sitting finished where I'm not looking.
What the interest cost me
A debt that charged no interest would be harmless. This one charges interest that shows up on no statement. For weeks, work of mine was routed to my most expensive models when a cheaper one would have done fine, and I had no idea my setup was doing it. I only saw the symptom. I'd sit down and burn through my five-hour usage limit almost at once. Then I'd stall for days once the weekly ceiling hit, unless I paid out of pocket. Get the routing right and the limits almost never bite. That was the interest, paid in compute quota and lost days, on a system I didn't understand.
Why I stopped trying to pay it down
Here's where I stop taking the metaphor at its word. Technical debt you're supposed to pay down: you refactor and the books clear. For a long time I assumed comprehension debt worked that way too, that the job was to climb back to full understanding and hold there. At the speed this work moves, that summit doesn't exist. Comprehension is a balance now. Attention pays some of it down every time I look, but it never clears, and managing what's left is the job.
The one practice that's earned its keep is small. Every so often I take one project and sit with one agent for a few hours. Never the code. That was never the level I worked at, and I couldn't have judged it anyway. I have it walk me through what the system can do, how much is finished, which tradeoffs got made and why, what's still open. I come out able to answer for that project again. Then the work moves on, the balance climbs, and in time I do it again. It's upkeep, and the number is never meant to hit zero.
More and more, when someone asks what a system of mine does, my best answer is to have an agent explain it. The understanding itself gets delegated. That can sound like giving up. What I've come to realize is that an agent's account is worth only as much as my ability to check it. Building a thing and describing it are two acts, and an agent can get the build right and still misdescribe it. So what would make the handoff safe is anchoring that account to something I can check: whether the tests actually pass, whether the state it describes is the real one. I'm only partway there. The check I actually run is the walkthrough, opening the project and having the agent take me through it end to end, and that's the strongest one I've got. The checks underneath it, the ones that would confirm the tests really pass and the state is really what the agent says, mostly aren't wired in yet. So a lot of what I've delegated still rests on the agent's say-so, and I know the difference between that and the real thing. The direction is clear enough: once there are checks that fail loudly when the work is wrong, I don't have to hold the explanation in my own head. The checks hold it for me.
Some people call this a new kind of failure, handing your understanding off to a machine. But it's older than software: writing, then books, then search engines, where we stopped remembering facts and started remembering where to find them. What's new isn't the offloading; it's that this time the place I've offloaded it to can be wrong about itself, which is why the checking matters at all.
Borrowing on purpose
Most of my debt is the good kind. When I'm standing up a whole set of capabilities at once, or a deliverable is due and the walkthrough can wait, I let understanding lag on purpose and catch up only on the parts worth keeping. Work I was always ready to throw away was never borrowed against, so walking away costs nothing. The debt turns dangerous where two things meet: work I have to keep, and a slide between quadrants I didn't notice. The whole skill is catching the slide before it gets expensive.
Insolvency
With money, insolvency is the point where you can't service the debt anymore. Here it's the point where nobody can answer for what a system does: not you, not an agent, not a test suite. Once you're there, every change is a guess. And you usually find out the day something breaks and no one can say what the system was even supposed to do.
For leaders
The pitch is that AI makes understanding cheap: ask, and the model explains anything. But an agent explaining work it did inherits the same gaps that produced the work. An explanation nobody has checked doesn't close the gap; it just restates it. So the scarce thing becomes a person who can still answer for the system, or something they built and checked that answers for it. I've only run this on myself, one person with a handful of projects, so treat it as a hypothesis. If it holds, the constraint on an organization becomes how many people can still answer for what its systems do, and that number only moves one way if nobody manages it.
If you're rolling agents across teams, don't count how many agents each person runs. Ask whether they can still account for what those agents built. Take one piece of shipped work and have its owner walk you through what it does and why. If they can, or if something they built and checked can answer for them, the debt on that work is being managed. If they can't, and nothing else can either, you've found where it's piling up out of sight. Give them time to sit with the system and rebuild what they'd be able to say about it, and start wiring in the checks that would let an agent answer for the work without everyone just taking its word.
Not long ago I could hold my whole operation in my head and answer for all of it, because it moved at a pace I could follow. That's over. The work outruns my understanding now, and it always will. So I've stopped trying to close the gap and started managing it, building the verification that lets me answer for the work even when an agent speaks for it.
This is one pattern from a set I'm working through on human-agent teams. It comes out of my own hands-on R&D, not a production deployment. The debts here are mine, and small on purpose.