Understanding AI code

Understanding code your agent wrote

When an AI agent writes most of the code, understanding it becomes the hard part. A practical way to rebuild your mental model of what changed and why.

The strange part of working with a coding agent is not that it writes code. It is that a week later you own a system you cannot fully explain.

Nothing is wrong, exactly. The tests pass. But somebody asks why checkout calls the cache twice, and you realise you approved that on a Tuesday without ever deciding it.

Why understanding slips

Agents work faster than anyone can follow. Each change is reasonable on its own. The understanding you used to build by writing the code yourself never gets built, because you did not write it.

So understanding has to be rebuilt on purpose, and it is cheapest right after the change, while the agent still holds the whole context.

Ask for the model, not the summary

A good explanation of a change has three parts:

1. The situation. What a person was doing when this code runs. "A customer presses Pay" is better than "the placeOrder method".
2. The mechanism. The few lines that carry the behaviour, in order.
3. The decision. What was chosen, what the alternative was, and what it costs.

Most agents give you the middle part in prose, with file names you have to open. That is the part your eyes can check, and it is the part you are least able to check from a paragraph.

See it instead of reading about it

deck turns that explanation into something you look at. Your agent writes it as a deck. The narration sits on top, the code sits underneath, and each sentence lights the lines it is about. When something moves over time, like requests piling up behind a pool or two writes racing, it gets a small chart that plays in step with the words.

You click through it at your own pace. Where it does not add up, you select the lines and ask. The answer comes back in the same window, from the same agent, sometimes as a new chart or another file brought in beside the first.

A habit that keeps understanding

• After any change you would struggle to explain, ask your agent to show you it before you move on.
• Keep each explanation to one concern. Three short decks beat one long one.
• End each one on a decision you actually make, so the choice is yours on record.