Reviewing agent diffs efficiently

Agent code is fluent. It’s well named, consistently formatted and confidently commented, which makes it easy to skim and approve. That’s the trap.

Reading every line top to bottom doesn’t scale either. What works for me is a fixed order that puts my attention where the risk is.

Read in this order, not file order

The review pass

1. 1

   1 min

   Summary vs brief

   Read the agent's final summary next to your brief. Anything it says it didn't do, or did extra, tells you where to look first.

2. 2

   1 min

   Scope check

   Look at the list of changed files and line counts before any code. Files you didn't expect are the first question to answer.

3. 3

   3 min

   Tests first

   Did any existing test change? Do the new tests assert real behaviour, with expected values you'd write yourself?

4. 4

   3 min

   Interfaces and contracts

   Public signatures, database migrations, config, dependency changes, error handling at boundaries. Mistakes here spread.

5. 5

   5+ min

   Core logic

   The few functions where the actual decision lives. Read these line by line and run the code if in doubt.

6. 6

   1 min

   Mechanical changes

   Renames, imports, generated files, formatting. Skim for anything that isn't mechanical hiding among them.

Make the agent hand you a map

The agent knows which parts of its change were tricky. Ask it to say so, at the end of every run.

Before you finish, give me a review guide:
1. Changed files grouped as: core logic / tests / interfaces / mechanical.
2. Any existing test you changed, and why.
3. Decisions you made that I didn't specify.
4. What you did NOT verify, and anything you're unsure about.

Red flags worth stopping for

Flip each card. These are the patterns I stop and question, however clean the rest of the diff looks.

🃏 Diff red flags

Tap a card to flip it

An expected value in an existing test changedEither the requirement changed or the test was bent to fit the code. Only you know which. Ask before accepting.A new dependency appearedDid the task need it? Is it maintained, licensed correctly, already solved by something in the repo? Dependencies outlive the task.A catch block that logs and continuesErrors swallowed to make a flow pass. Check what the caller should really see when this fails.Code deleted as 'unused'Unused by what the agent searched, maybe. Reflection, config, other services and scripts don't always show up in a search.Hard-coded values that match the test fixturesThe code may be special-casing the test data instead of implementing the rule. Try a value the tests don't use.CI, build or lint config editedChanging the rules of the game is rarely part of the task. Treat it as its own change, reviewed on its own.

Reviewing agent code as a team, with ownership and approvals, is its own topic. We cover it in Module 6.

Before you move on

✅ Key takeaways

0 / 4 completed

• I read the summary and the file list before any code.
• I review tests before implementation and check whether existing tests changed.
• I spend most of my attention on interfaces and core logic, and skim mechanical changes.
• My briefs ask the agent for a review guide, and I treat it as a map, not a verdict.

↺ Reset