Chapter 12: Review

There is a cost to merging what you don't understand, and two loosely defined terms are competing to name it. Use them, and be ready to say what you mean.

Comprehension debt

The gap between how much code exists and how much of it anyone understands. Like money borrowed, it costs nothing today, and you pay later, in the time it takes to work out the code before you can safely change it.

Agents remove the friction that used to build understanding as a side effect. The code can be clean, tested and passing and still be something nobody on the team could change safely. No tool in your pipeline measures this.

Say it to your agent

“Before you add anything to src/billing/, write a one-page map of how it works today, from reading the code. Mark anything you couldn't explain. Those marked parts are where I need to catch up before we go further.”

The workshop

Name a word, or describe what you mean in everyday language.