Guardrails in practiceยท

Comprehension debt

The gap between how much code is in your system and how much of it anyone on the team actually understands.

There is code in your product no one has read.

There's a term for that now. It's called comprehension debt: the gap between how much code is in your system and how much of it anyone on the team actually understands.

When AI writes code that nobody understands, the debt goes up.

Just like technical debt, it's something software engineers, team leaders and CTOs need to be aware of, because of what it produces:

  • A bug in production and nobody knows where to start looking.
  • A small change that takes a week because someone has to learn that part of the code first.
  • A declining understanding of your core systems.

What keeps it down:

  • Someone reads every change before it merges and can explain it to a colleague.
  • Changes small enough that reading them properly is realistic.
  • Treating "I don't know, the AI wrote it" as a reason not to merge.

If there's a part of your system nobody can explain, that's where I'd start.

First posted on LinkedIn on 19 October 2026.

More in Guardrails in practiceAll articles