We’re Writing Code Faster Than We Can Understand It

Like most software engineers, I have been watching the AI boom change my job with a mixture of excitement and horror. There was a moment, late in 2025, where AI coding tools went from giving me a relatively small productivity boost to allowing me to work a lot faster than before: 2x, 3x and (in the right circumstances) even 10x improvements.

This has not been to the detriment of quality. In fact, my hunch is that code quality is probably higher than before, if you use the tools correctly. But it does come with a different cost: understanding.

Comprehension debt

Increasingly, the most common form of technical debt I feel in this new world is comprehension debt: the gap between how quickly code is produced and how well it is actually understood. I first heard this phrase in an excellent video by The Gray Cat, but it’s a feeling I have been grappling with for a while.

Partly, it’s a collaborative problem; other people are producing code faster, and it’s harder to keep a handle on their changes. But it’s also a problem with the code I am merging myself. Despite taking the time to read every line of AI-generated code that I submit, my knowledge of it rarely feels as deep as it was in the pre-AI world, where I had hand-coded everything myself.

Something we used to get, almost for free, via the process of working out a hand-coded solution, is now something we need to be disciplined about — especially as it’s increasingly possible for AI to one-shot certain categories of task.

In particular, the problem reveals itself when there’s an issue with my code: maybe there’s a bug, or someone has a question about how to build on top of it. In the era of handwritten code, I would very often know exactly where the bug was hiding or exactly the trade-offs that the new developer would need to make. Now, I am more likely to be caught off guard. And yet the obvious solution — going back to writing everything by hand — doesn’t feel viable when it means sacrificing so much productivity.

I’m still working out how best to approach this constraint, but below, I share three strategies that I’m currently having success with.

How to tackle it

Strategy 1: Plan more than you think you need to

Many developers reach for planning when they’re working on something more complex. But, even for simple features, it has the added benefit of forcing you to slow down and understand more deeply what you’re instructing the AI to do. I use the Superpowers brainstorming skill, which forces you to slow down and weigh up different approaches to the solution. This can feel unnecessary, as sometimes I’ll be confident that the AI could one-shot a perfectly viable solution without the back-and-forth, but — in those cases — the benefit is more for my understanding.

Strategy 2: Ask questions about the implementation

Another approach I’m experimenting with, beyond just reading the code, is to ask the AI questions about what it’s done. If there’s anything that looks fine, but maybe it’s in a part of the system I’m less aware of, I ask it to explain that section. While learning by doing is still the superior path to deep understanding, asking questions feels like a reasonable middle ground. We can move quickly with AI, but slow down just enough to help our understanding keep pace with our output.

Strategy 3: Make diagrams

Finally, the cost of producing complex diagrams has gone down a lot, and these are great aids to understanding. For example, we use the Mermaid library to add diagrams to our markdown files. Pre-AI, in many cases, it would take too long to justify the work of creating diagrams for all but the biggest features and systems. Now, however, they can be created and updated much more easily, and they’re a great shortcut for developers to understand a system or feature. In particular, I find UML state and sequence diagrams useful for elucidating more complex flows.

Conclusion

In a relatively short space of time, something we used to take for granted as a natural part of writing a solution is no longer guaranteed. This is a new class of technical debt, and teams that embrace AI tooling without deliberately slowing down enough to understand are likely to pay for it later in slower debugging, weaker decisions and fragile systems.

Of course, understanding everything isn’t possible — and it never was. But there’s a sweet spot where we’re moving quickly and also taking enough to ensure we’re keeping up.

We’ve spent years optimising how fast we can write code. Now we need to think carefully about how well we understand it.