AI code review

How to review code your agent wrote

Reviewing AI-generated code is not like reviewing a colleague's. Here is what to look for, why diffs and summaries fall short, and how to see the decisions your agent made.

Your agent finished. The diff is 900 lines across eleven files, and the summary says it "refactored the pricing flow and added caching". You have to approve it, and you did not write any of it.

Reviewing code an agent wrote is a different job from reviewing a colleague's. A colleague made a few decisions and can tell you why. An agent made dozens, quickly, and the reasons live in a conversation you may have skimmed.

Review the decisions, not the lines

You do not need to read every line. You need to find the handful of places where something was decided: a timeout chosen, a cache added, an error swallowed, a query moved, a field made optional. Those are the lines that will page someone at three in the morning.

A useful order:

1. What was the goal? Write it in one sentence before you open the diff.
2. Where did behaviour change? Not where text changed. Formatting, renames and moved files are noise.
3. What did it assume? About load, about data shape, about who calls this.
4. What did it not do? Tests it did not write, cases it did not handle, old paths it did not remove.

Why the diff and the summary both fall short

A diff shows every changed line with the same weight. The decision on line 412 looks exactly like the import on line 3.

A summary has the opposite problem. It is the agent's own account of what it did, in prose, with file:line references you have to open one at a time and hold in your head. By the fourth file you are assembling the argument yourself.

Make the agent show you

The fix is to ask for the review in a different shape: one claim at a time, each with the code that proves it, in front of you.

That is what deck does. Your agent writes a short deck instead of a paragraph. Each group is one claim, and the lines it rests on are open beside it. Click a sentence and its lines light up. When the claim is about behaviour over time (a queue backing up, two requests racing), the agent can draw it as a small chart that moves with the sentence.

When you disagree, you select the lines and say so. Your comment goes back to the same agent, pinned to those lines, and it picks up from there.

A checklist for agent-written changes

• Every new dependency, cache, retry or timeout: why this value?
• Every catch block: what is swallowed, and who would notice?
• Every query or loop that touches the network: what happens at ten times the load?
• Every deleted line: was anything else relying on it?
• Every test: does it test the behaviour, or the implementation the agent just wrote?

Ask your agent to answer those as a deck, and you review the reasoning instead of hunting for it.