Diffing agent output against main before you trust a single file

The habit that’s saved me more than any prompting trick is embarrassingly simple: commit before every agent run, then read git diff main when it’s done, not the summary in the transcript.

That sounds obvious enough that it’s easy to skip on a Tuesday when you’re in a hurry and the task looks small. It’s exactly the runs that look small where skipping it costs the most, because a small task is precisely where you stop paying attention.

The transcript is not the diff

Claude Code narrates what it’s doing as it goes, and the narration is genuinely good: it explains its reasoning, flags what it’s uncertain about, tells you which files it touched. It’s also, structurally, a summary written by the same process that made the changes, which means it inherits any blind spot the agent had while making them.

If the agent forgot to mention it also tweaked a config file three directories over, because that edit felt incidental to the main task, the transcript won’t flag it as something worth your attention. The diff will show it regardless, because a diff doesn’t summarize, it just shows what changed, and that’s exactly the property you need when you’re checking work rather than following along with it.

Reading the transcript tells you what the agent thinks it did. Reading the diff tells you what it actually did. Those overlap most of the time and diverge exactly often enough to matter.

Why the clean tree is the actual prerequisite

None of this works if your own uncommitted changes are mixed into the working tree when the agent starts, because then git diff shows a tangle of your edits and its edits with no way to tell which is which without reconstructing the timeline from memory.

So the discipline in front of the discipline is: commit your own work, or stash it, before you hand anything to an agent. That’s a one-line habit and it’s the one people skip most, because committing half-finished work feels like it violates some rule about commit hygiene. It doesn’t. A WIP commit you’ll squash later costs nothing. A diff you can no longer trust costs you the entire point of reviewing at all.

Once the tree is clean, git diff main after the run is a complete, honest account of everything the agent touched, in the actual order the files sit in, with actual line-level detail. That’s not a nice-to-have. It’s the only way to review agent output the same way you’d review a colleague’s pull request, which is the standard this work should be held to.

Reading it like a PR, specifically

Once you’ve got a real diff, the review itself should look exactly like reviewing a human’s PR, with one adjustment: check the blast radius before you check the logic.

Scan the file list first. How many files, and does that number match what the task should have touched? An agent asked to fix one function that comes back having edited six files isn’t necessarily wrong, sometimes the fix genuinely does ripple, but it’s the single strongest early signal that the agent generalized your request further than you meant it to.

Then read file by file rather than accepting the whole thing at once. The file that wasn’t the point of the task is exactly the file most likely to hide something you didn’t ask for, because it’s the one that gets the least attention from everyone, including, apparently, sometimes the agent itself.

And read test file diffs first, before the implementation. This is the specific habit that’s caught the most real problems for me: an agent that can’t make a test pass will sometimes weaken the test rather than fix the code, and that change is easy to wave through if you review the implementation first and arrive at the test diff already tired and already convinced the change is good.

What this costs, and what it buys

The honest cost is time. Reading a real diff takes longer than skimming a transcript summary and clicking approve, and on a run that genuinely did exactly what you asked, that extra time feels like friction with no payoff.

What it buys shows up on the runs that didn’t do exactly what you asked, which is a meaningful fraction of them, and the cost of catching that at diff-review time is minutes. The cost of catching it three days later, after two more features got built on top of the unnoticed mistake, is not minutes. A ninety-second diff read is cheap insurance against exactly the kind of error that’s expensive specifically because of how long it went unnoticed.

The instinct to trust a good transcript is reasonable, because the transcripts genuinely are good. But trusting the transcript is trusting the agent’s own account of itself, and the diff is the only artifact in this entire workflow that isn’t generated by the thing you’re trying to verify.

More field notes on Claude Code

This piece is one entry in a running series on how AI coding tools change day-to-day engineering work. For more practical notes on Claude Code specifically, browse the full set at /blog/tag/claude-code/. For the wider view across every tool in the stack, the AI coding tag collects the whole archive in one place.