Reviewing Plans and Diffs
Review agent work like a skeptical senior engineer. Check the plan before code, read the diff instead of the summary, and treat test results as evidence you check, not proof you accept.
The Summary Is Not the Work
At the end of a run, Claude Code writes a tidy summary: what it changed, why, and that the tests pass. Summaries are useful. They are also the agent describing its own work, and the agent is the one participant that can’t see its own blind spots.
Discernment with an agent means reviewing three things in order: the plan, the diff, and the evidence. The summary is a guide to where to look, not a substitute for looking.
- 1 Plan
Is the approach right?
- 2 Diff
Does the code do it, and only it?
- 3 Evidence
Do the checks prove it?
The earlier you catch a wrong turn, the less it costs to fix:
Stage 1: Review the Plan
A plan is the cheapest point to catch a wrong turn. Ask:
- Did it understand the goal? Restate the goal in your own words and compare.
- Did it find the right code? Does the plan name the files you’d expect? Is anything obviously missing, like the migration, the config, or the second place the logic is duplicated?
- Is the approach proportionate? A two-line bug fix shouldn’t come with a plan to “refactor the session layer.”
- What did it assume? Look for “I’ll assume…” and confirm or correct each assumption.
- What’s the verification step? If the plan doesn’t say how it will prove the change works, add that before approving.
Push back freely. “Simpler: just fix the expiry calculation; don’t touch the middleware” is a perfectly good response to a plan.
Stage 2: Read the Diff
Read the actual changes with git diff, in your IDE’s diff view, or in the desktop app’s diff pane. Don’t stop at “looks reasonable.” Check:
| Look for | Why it matters |
|---|---|
| Files you didn’t expect | Scope creep: “while I was there” changes that nobody asked for and nobody will review carefully. |
| Deleted or weakened tests | The fastest way to make a failing test pass is to change the test. |
| New dependencies | Each one is code you now trust and maintain. Is it real, maintained, and needed? |
| Swallowed errors | try { ... } catch {} makes symptoms disappear without fixing causes. |
| Hardcoded values | Magic numbers, test-only branches, or special cases that make one input work. |
| Duplicated logic | The agent wrote a new helper instead of finding the existing one. |
| Comments that don’t match the code | Often a sign that it changed its approach partway through. |
For a large diff, ask the agent for help, but in a way that makes it argue against itself: “Review this diff as a skeptical reviewer. What’s the riskiest change, and what would you test that I haven’t?” A fresh session or a review subagent is better still, because it doesn’t share the original session’s assumptions.
Common mistake: reading “Fixed the bug, all 142 tests pass” and approving.
That summary might be true. It might also leave out that the agent deleted the test that was failing, so now 142 tests pass instead of 143. The only way to know is to look. A quick git diff --stat before anything else shows which files changed and how much, and often reveals the surprise in seconds.
Stage 3: Check the Evidence
Tests passing is evidence, not proof. Ask what the evidence actually shows:
- Did the right tests run? “All tests pass” means little if the changed code has no tests.
- Did the new test fail first? A test written after the fix may pass for the wrong reason. Ask the agent to show it failing against the old code.
- Does it work outside the tests? For UI, look at the page. For a CLI, run it. For an API, call it.
- Were the edge cases tried? Empty input, very large input, the unhappy path, the concurrent case.
Run the key check yourself, at least once, rather than trusting the transcript’s report of it.
Calibrating Review Depth
Not every diff needs the same scrutiny. Match your review to the risk:
| Risk | Example | Review depth |
|---|---|---|
| Low | Docs, comments, test-only changes, formatting | Skim the diff, run the checks |
| Medium | Feature code with good test coverage | Read every line; check tests fail-then-pass |
| High | Auth, payments, data migrations, concurrency, infra | Line by line, run it yourself, second human reviewer |
- Give Claude Code a medium-sized task on a branch, such as a small feature or a bug fix with tests.
- When it finishes, don’t read its summary yet. Run
git diff --stat, then read the full diff. - Write your own three-sentence summary of what changed.
- Now read the agent’s summary. What did it mention that you missed? What did it leave out that you found?
- Ask a fresh session to review the diff skeptically. Did it find anything neither of you caught?
1. Why review the plan before the code?
The plan is the cheapest checkpoint. It doesn't replace the diff review; it makes it easier.
2. The agent reports that all tests pass after fixing a bug. Which of these most needs checking?
Changing the test is the easiest way to make it pass. 'All tests pass' only means something if the right tests exist and are intact.
3. What makes an AI-assisted second review most useful?
A fresh context doesn't share the original session's assumptions, and a skeptical framing invites real criticism instead of agreement.
Up Next
Now that you know how to review, the next lesson catalogs the specific ways agents fail, so you know what to look for.