A bug came in on something I'd written. My name on the commit, my PR, merged and running for months.

I opened the file and had no idea how it worked.

Not a vague memory that needed refreshing. Genuinely blank. I'd reviewed that code, I'd tested it, I'd argued about it in a PR comment. And I could not have explained the control flow to somebody standing behind me.

There's a name for it now

Addy Osmani called this comprehension debt in early 2026, and the definition is uncomfortable because it's exact: the gap between how fast a system changes and how well the team understands it.

It's not new. Inherited code has always been like this. What's new is the rate.

Stack Overflow's 2026 survey found 76% of developers using AI coding tools had generated code they didn't fully understand, at least some of the time. Not beginners. Experienced people. And roughly 41% of new code is now AI-generated.

The mechanism is obvious once you say it out loud. Writing code produces understanding as a side effect, because you made every decision that produced it. Reading generated code produces the feeling of understanding, which is a different thing and much cheaper to obtain.

There's a measurement on this that I found hard to argue with. A 2026 study comparing comprehension quiz scores put AI-assisted developers at 50% against 67% for a hand-coding control group. Same code shipped. Different understanding of it.

The signals all stay green

This is what makes it different from normal technical debt, and why nobody catches it early.

Messy code looks messy. You can see it in a review, point at it, file a ticket.

Comprehension debt has no artifact. CI passes, velocity looks fine, sprint commitments land. The code is often genuinely good. There's nothing to point at, because the thing that's missing isn't in the repository at all. It's in the heads of the people who shipped it.

You find out during an incident, which is the worst possible moment to discover that nobody can explain the thing that's broken.

One 2026 write-up puts a sharper edge on it: 88% of developers reported at least one negative impact of AI on technical debt, and 53% said AI had generated code that looked correct but was unreliable. It passed review. It passed tests. It was confidently wrong.

The symptom I'd actually watch for

Forget the surveys for a second. The tell is behavioural, and it's easy to spot in yourself.

It's when people start avoiding parts of the system. Not out of laziness, but because they've lost confidence in their ability to predict what a change will do.

You know the ones. The module everyone routes around. The service where the fix is always a wrapper rather than an edit. The file where the PR description says "minimal change to avoid touching X."

Sourcegraph's framing of legacy is the best I've read on this: a three-year-old service nobody understands or wants to touch is legacy, while a twenty-year-old program with tests and documented behaviour isn't. Age has nothing to do with it. Comprehension does.

Which means you can now write legacy code this quarter.

What actually helped

I don't think the answer is to use AI tools less. That advice doesn't survive contact with a deadline and I'd be lying if I said I followed it.

What's helped is having a fast way to rebuild understanding rather than relying on remembering.

When I opened that file again, the question wasn't "what does this do." I could read it. The question was what calls it, what it calls, what happens if I change this branch, and whether anything else in the org depends on the shape of what it returns. Those are structural questions, and structure is exactly what you lose when you didn't write something by hand.

This is the layer Vorr AI covers. It builds a relationship graph across repositories rather than treating code as files to search, so tracing callers and callees, or finding every reference to a symbol across the whole organisation, is a lookup rather than an archaeology session. Every answer comes back with the repository, file and line, which matters more than it sounds when you're rebuilding a mental model, because you end up reading the actual code rather than a summary of it.

It doesn't give you the understanding. It removes most of the cost of getting it back, which turned out to be the reason I was avoiding the file.

The Martin Fowler field report on this makes a point I keep coming back to: generative AI is most useful for the comprehension half of the work, meaning reverse engineering, summarising modules and drafting characterisation tests, and least useful when asked to produce final production code. That's roughly the opposite of how most of us are using it.

Small things I've started doing

Write the PR description before I ask for the code, not after. If I can't say what it should do in three sentences, I don't understand the problem yet and I'm about to outsource that too.

Trace one path by hand through anything I generated. Not all of it. One request path, end to end, reading the actual code.

Note the bit I don't understand. A comment saying "unclear why this retries twice, worked when tested" is more honest than nothing and more useful to the next person than a confident summary.

Treat avoidance as a signal. If I'm working around a file rather than in it, that's the debt, and it's cheaper to pay on a Tuesday than during an incident.

The bug turned out to be a two-line fix, once I understood the code again. Understanding it again took the whole morning.

Author note

Manjunaathaa, Associate DevOps Development Engineer at Frigga Cloud, working on Vorr AI.

I'm early enough in this to have never really worked without AI tools, which I think makes me exactly the person this affects most. I don't have a baseline to compare against. The habit of building a mental model as a side effect of typing is one I never fully formed.

That's not an argument against the tools. It's just something I've had to notice and deliberately work around, and I'd rather say so than pretend the understanding arrives on its own.

LinkedIn.

I Shipped It. Six Months Later I Couldn't Explain It.