opinion

Code Comprehension in the Age of AI

To keep AI-generated code understandable, make only changes you can explain and maintain a short map of the system's architecture.

Until recently, understanding code was a byproduct of writing it. To implement a feature, however small, you first had to understand what you were trying to do, then work out how to do it, write the code, make mistakes, and fix them. That was only ever true for the parts you wrote yourself. The rest of the system was someone else’s code, and it always had been. But for my own parts, I spent so much time thinking through how a feature should work and how it fit into the existing code that, by the time I was done, I understood it very well. When a bug came in, I knew where to look before I opened the editor. That’s how well I knew the code I worked on.

With AI coding assistants, that is no longer true. You can describe a feature, get a working implementation in minutes, run the tests, and merge it. But you didn’t write it, and you didn’t have to think it through, so the understanding never formed. If someone asks you a month later why the retry has jitter, or what happens when the cache and the database disagree, the honest answer is “I’d have to look.” You’d have had to look either way. The difference is whether looking means refreshing a model you once had, or building one from nothing. We have always had to deal with code we don’t understand, but it used to be other people’s code. Now it’s our own, at least by name.

Code without a theory

Peter Naur got at this in 1985, in a paper called Programming as Theory Building. His argument was that a program isn’t really the source code. It’s the theory that lives in the heads of the people who built it: how it works, why it’s built the way it is, and how it should be changed. The source code and the documentation are only a partial expression of it, and Naur argues the rest can’t be written down at all, let alone recovered from the code alone. He also predicted what happens next: a program text decays when it’s modified by people without a grasp of the theory behind it. What has changed since then is that we can now produce the code without ever building the theory.

Sometimes the cost shows up right away. A colleague asks in code review why it’s done this way and not another, or a product manager wants to know exactly why something behaves the way it does, and you don’t have an answer. Other times it shows up much later, during an incident when nobody on call can come up with a hypothesis because nobody holds a theory of the system anymore, or after a change that looked safe went out and broke an invariant, a rule the system assumes is always true, that only ever existed in the code. And every change made without understanding leaves the code a little harder to understand for whoever comes next, so over time you can end up with a codebase that is perfectly readable and that nobody actually understands.

Robert Laszczak puts it well in Writing code isn’t the bottleneck anymore, reading is: it doesn’t matter how much code you can generate, only how much of it you can take accountability for. I don’t think there is a way to fully close the gap between what you can generate and what you can account for, but two habits have helped me keep it under control. The first covers the change in front of you. The second covers the system around it. Neither substitutes for the other.

Don’t accept what you can’t explain

Before a change goes in, I should be able to explain it to a colleague without looking at the diff: what it does, why it’s done this way, and what would break if it were removed. If I can’t do that, I don’t understand the change yet, no matter what the tests say. Tests tell you that the code works. They don’t tell you that you know why it works.

This bar is for changes that alter behaviour or touch shared state. A generated migration or a renamed field doesn’t need a speech.

In practice, this means reviewing in smaller units than the tool produces. The model is perfectly happy to generate five hundred lines in one go, but nobody can properly review five hundred lines in one go. You skim them, and skimming is not understanding. So let the tool generate what it wants, then review one concern at a time: one module, one rule, one decision, and don’t move on until you could explain it. This is slower per change. It’s cheaper per incident, and in my experience the changes that come back as incidents are the ones I skimmed.

Keep a map, and point the tool at it

Nobody can keep a whole codebase in their head, so the understanding worth keeping is one level up. What are the main pieces? How does data flow between them? Which rules must always hold? Why were the non-obvious decisions made the way they were? Write that down, briefly, and keep it next to the code. Something like an ARCHITECTURE.md works well, as long as it stays concrete. Rules like, for example, “only the outbox table writes to the event bus”. Decisions that would look wrong to a newcomer, with the reason they aren’t wrong. A page like that outlives any amount of implementation detail, and it’s short enough that people actually keep it in their heads.

Naur would say the map is not the theory, and that no document can be. Fair. The map is scaffolding for rebuilding a theory quickly, which is weaker than having built it yourself and better than nothing. That only holds if someone can defend every line of it. Tools like Whiteboard, or an agent skill like Archify, will draft a page like this from the source. Treat the draft as a draft: read it, fix it, and delete any rule you can’t say the reason for. A generated map nobody can defend is the original problem moved one level up.

Then use the assistant in the other direction. The same tool that produces code faster than you can read it can also explain code faster than you could work through it yourself. Ask it to walk you through a module you didn’t write. Ask it to compare the code against your map and tell you where the two disagree. An explanation from the tool is a claim about the code, not a substitute for reading it. Check it against the code and the map. If you can’t check it, you haven’t understood anything, you’ve read a nicer summary. Every disagreement it finds is a lead: a bug, a stale map, or the tool misreading the code, and you have to find out which. When a change lands that you weren’t part of, have it summarized before you touch it, then read the parts the summary made you nervous about. The tool doesn’t have to be the reason you stop understanding your system. It can just as well be the reason you keep up with it.

How much of this you need depends on how long the code will live and how many people will touch it. A spike you’ll delete on Friday doesn’t need a theory. A payments service does.

The goal isn’t to slow the machine down. It’s to make sure that somebody still understands what the code does, and that the somebody is you.