The gap has a name
You used an agent to fix a bug, or to add a feature. The tests passed, you merged. You can say what changed. Someone asks why this approach, or what else it touches, and you feel the picture thin out.
I run into this in my own work. So do people I work with who have been shipping for years. The name for it is comprehension debt: how much code sits in the system versus how much of it you hold in your head. You pay later, in time, because the picture was thin when the change went in.
Technical debt I know how to talk about. You cut a corner, you know where it lives, you can plan to pay it down. This one is quieter. The PR looks fine. Nothing in it tells you that next month you’ll struggle to explain the thing you shipped.
I used to get the picture for free
Remember when you had to fix a bug, or add a feature, and the first thing you did was go through the codebase? You sat with the architecture, the abstractions, how the pieces fit. Then you thought of a solution. Slow, but you came out knowing the system.
I still go through the code. I spend less time on it, and I don’t leave with the same solid picture. Claude Code and Cursor write the change, the tests go green, I merge. The tools let you do that. That’s the problem.
I understand the ticket. I can see what the agent changed. The feeling I get is that I don’t hold the root, or I couldn’t stand behind this fix if someone pushed on it. I’d need to sit with it first.
I still need the same picture. Who calls this, what it does, how we deploy it, what it depends on. I can ask Claude to dump that into tables. Connecting the dots is still on me. I don’t make a call off a generated table. I sit with it. That pays off later, on a bridge, or when I have to feed an agent a picture that is true.
The rooms where you have to speak
That picture is what I need when people decide. I’m on an outage call and someone asks if we can fail over, or if this path even hits the box that’s down. Next week it’s planning or grooming, and we cut scope. Or an architecture discussion, and someone proposes a new service. Wherever the important call gets made, people are talking, and I need the system in my head.
I can hand the problem to an agent. The best model I use has a context window of a million tokens. It still won’t get on that outage call and speak instead of me. Those rooms need a person who holds the system.
You look at a senior engineer and you see the code quality, or that they can pass a system design interview. That’s part of it. A lot of the job is comprehension. They hold a solid picture of the system in their head, and they can make a decision from that knowledge, fast.
I try not to go faster than I can hold
I can go faster. I try not to go faster than I can hold. I won’t speed up a change at the cost of comprehension, and you shouldn’t either.
The idea is tempting. Hand the problem to a model, take the patch, move on. I use the same tools. I still sit with the code long enough to leave with a picture I can defend. That’s the part I keep, and the part I’d tell another engineer to keep.