Picture a standup. A PM asks what happens when a customer uploads a file over the size limit. Three engineers look at each other, and the one who shipped the upload change last week opens the code to check.
They built it with Claude's help: they described what they wanted, checked what came back, the tests passed and it shipped. A week later, none of them can say for sure how it behaves.
That's comprehension debt: the gap between what your team ships and what it understands.
What is comprehension debt?
Technical debt is a shortcut you know about. An engineer chose a quick fix, and they can point to where it lives in the code.
Comprehension debt is behaviour your team shipped but can't explain right now. It's not that the code is complicated. It's that the team never went through it closely in the first place.
You can find technical debt by reading the code. Comprehension debt is harder to spot, because reading the code closely is the step that got skipped.
Why AI-assisted coding makes it grow
When engineers wrote every line by hand, reviewing a change meant following their thinking: which edge cases they'd covered and which they hadn't.
With AI tools, changes get bigger and come faster. A review is more likely to check that the tests pass and the code looks reasonable, which is a quality check, not understanding.
The DORA 2024 report measured part of this: more AI adoption goes with less stable delivery, meaning more code shipped and more rework. My reading of it, which is an opinion and not a study, is that teams now ship faster than they can follow what they shipped.
Specs used to come first. Now they come after
It used to work like this: a PM wrote a spec, engineers built from it, and the spec became the reference. It went out of date over time, but at least it described what the team planned to build.
Now a lot of work doesn't start with a spec. An engineer describes the change to Claude, ChatGPT or Codex, refines what comes back and ships it. The plan shifts between the first prompt and the release, so the ticket describes what the team hoped for, not what went out.
That means the only reliable description of what shipped is one read from the code, after each release.
How to manage comprehension debt
- Write down the why yourselves. Decisions and trade-offs live in people's heads, so they have to be written down by people.
- Get the what from the code. A plain description of how each feature works, updated with every release, that a PM, support or sales can read.
- Check it as a team. When the description is wrong, your team corrects it, so it keeps getting better.
Specsight does the second part. It reads your code, describes every feature in plain words and updates that description every time you ship. It can miss or misread something, which is why your team can correct any part of it. That's what I call product observability.
AI tools aren't going to slow down. The teams shipping fastest need this most, because they're the least able to rebuild the picture from the code when a customer asks.
See it on Specsight's own product in the demo project. No account required. To see your own product, get started.
