An AI agent just finished a task. The terminal says “done,” the tests it wrote are green, and there’s a tempting little voice saying you can just merge it. Then you remember the last time you did that — a helper function got duplicated instead of reused, and it took a teammate’s comment two weeks later to notice.
A disciplined git diff review workflow is the single habit that makes vibe coding sustainable. Writing code by conversation is fast precisely because you’re not typing every line yourself, but that speed only pays off if you actually read what came out the other end before it lands in main. This post lays out a concrete, repeatable way to review a diff — in an order that catches the expensive mistakes before the cosmetic ones.
Why Diff Review Matters More With AI Agents
When you write code yourself, review is almost incidental — you already know what you meant to change, because you typed it. An AI agent’s diff carries no such guarantee. It can be entirely correct and still do things you wouldn’t have chosen: adding a new dependency for something the standard library already handles, touching a file that wasn’t part of the task, or quietly changing formatting across a file it barely needed to edit.
None of that is a reason to distrust agents — it’s a reason to build a review habit that catches it reliably instead of by luck. The workflow below is ordered specifically so you see the highest-risk changes first, and it pairs naturally with the isolation habits covered in why every AI coding agent should get its own branch — a clean branch per agent makes the diff you’re reviewing here far easier to reason about in the first place.
The Five-Pass Diff Review
Reviewing a diff top to bottom, line by line, is how you miss things — your attention flattens after the first screen. A staged pass, each with one job, works better:
- Scope pass. Run
git diff --statfirst, before looking at any actual code. Does the list of changed files match what you asked for? A one-line bug fix that touched twelve files is a signal to slow down. - Structure pass. Skim function and file boundaries — new functions added, functions deleted, files moved. This is where you catch an agent solving the problem by introducing a whole new abstraction when a two-line fix would have done.
- Logic pass. Now read the actual diff hunks for the core change. Does the logic match your mental model of the fix? This is the pass most people jump straight to — it works far better after the first two.
- Side-effect pass. Check anything touched outside the obvious target: config files, migrations, package manifests. Agents sometimes “helpfully” bump a dependency version or adjust a lint rule while fixing something unrelated.
- Test pass. Confirm new tests actually exercise the changed behavior, not just that they pass. A test that asserts
true === truewill stay green forever and catch nothing.
# Pass 1 — scope: what files changed, and how much
git diff --stat main...feature-branch
# Pass 2 & 3 — structure and logic: the actual hunks
git diff main...feature-branch -- src/
# Pass 4 — side effects: anything outside src/
git diff main...feature-branch -- package.json '*.yml' '*.toml'
# Pass 5 — tests: did the test files change, and how
git diff main...feature-branch -- '*test*' '*spec*'
A Quick Reference Checklist
| Pass | What you’re checking | Red flag |
|---|---|---|
| Scope | File count and location match the task | Unrelated files touched |
| Structure | New/removed functions, moved code | New abstraction for a small fix |
| Logic | The actual behavior change | Logic doesn’t match the request |
| Side effects | Config, deps, migrations | Silent dependency or version bump |
| Tests | New tests target the real change | Trivial or tautological assertions |
Keep this list next to you until the order becomes automatic — most people find that after a couple weeks it stops feeling like a checklist and starts feeling like how they naturally read a diff.
Tools That Make This Faster
The git diff command itself is enough to run this workflow, and the official git-diff documentation covers every flag worth knowing, including --stat, path filters, and the different diff algorithms. But a terminal-only diff has real limits once you’re reviewing several agent sessions a day: no syntax highlighting by default, no way to comment inline, and no persistent view of “which files still need a look.”
A visual diff panel — the kind built into an IDE or a dedicated agent tool — turns the same five passes into something closer to a checklist you click through: file tree on one side grouped by change type, syntax-highlighted hunks on the other, and a clear marker for files you haven’t opened yet. The workflow doesn’t change; the friction of following it does.
Common Mistakes That Skip the Workflow Entirely
- Reading only the final “summary” the agent prints, and trusting it matches the diff. Agents summarize their own work reasonably well most of the time, but “most of the time” is exactly the gap this workflow exists to close.
- Merging because the tests pass. Passing tests confirm the tests pass — nothing more. A test suite an agent wrote alongside the change it’s testing shares the same blind spots as the change itself.
- Skipping the side-effect pass because the diff “looks small.” Small diffs hide dependency bumps and config changes just as easily as large ones — arguably more easily, since you’re paying less attention.
- Reviewing in the terminal for genuinely large diffs. Past a certain size, scrolling through raw diff output in a terminal is where real misses happen; switch to a visual tool once a diff spans more than a few files.
Building This Into a Team Habit
If you work with other people, the five-pass workflow is worth writing down somewhere shared, not just keeping in your own head. A one-paragraph note in your CONTRIBUTING.md — “review agent-generated diffs in this order” — turns an individual habit into a team norm, and it gives you a concrete thing to point to when a review catches something. It’s also a natural companion to a broader code review checklist for AI-written code: the five passes here tell you how to move through a diff, and a checklist tells you what to look for once you’re in each pass.
Getting Started
- Next time an agent finishes a task, resist merging immediately — run
git diff --statfirst and just look at the file list before reading a single line of code. - Work through the five passes in order once, even if it feels slow. Speed comes with repetition, not with skipping steps.
- Notice which pass catches the most surprises for your particular codebase — for many people it’s the side-effect pass — and pay extra attention there going forward.
- If you’re doing this daily, Agents builds a right-side diff review panel into every session, so the five-pass workflow above happens in one place instead of switching between a terminal and your editor.
Vibe coding doesn’t get safer by writing less code by hand — it gets safer by reading the code that comes back with the same discipline you’d want from any collaborator. A five-pass diff review is a small habit that pays for itself the first time it catches something a green test suite didn’t.