How to actually read the code your AI agent wrote

An agent session ends with a cheerful summary and a diff that touches a lot of files. The easy move is to scroll through it, see that it looks reasonable, and merge.

That's skimming, not review. The summary tells you what the agent meant to do; the diff tells you what it actually did, and the two don't always match. This post is the workflow I'd suggest for closing that gap, whether the change came from Claude Code, Codex, Cursor or anything else.

Agent work usually reaches you in one of three shapes, and each needs a slightly different approach.

A single commit. Good when the agent commits as it goes. git show <sha> gives you the message and the diff together. Read the message first and treat it as a claim you're going to check.

A branch compared against main. This is the usual shape for a longer task. There are two different questions here:

Uncommitted local changes. Common with agents that edit your working tree and leave committing to you. git diff covers tracked files, but it doesn't show new files the agent created. Run git status and look at the untracked list, or git add -N. so new files show up in git diff (undo with git reset ). Agents create helper files, scripts and fixtures more often than their summaries mention.

Before reading any hunk, get an overview:

git diff --stat main...feature git diff --name-status main...feature Enter fullscreen mode Exit fullscreen mode Then ask a few questions:

Diff tools list files alphabetically, which is rarely the order the change makes sense in. A better order:

For each hunk, don't stop at the changed lines. Open the function they live in. A two-line change to a condition can only be judged with the surrounding code in view, and that's exactly the context a diff leaves out.

Agents produce code that reads fluently, so "does this look like reasonable code?" is the wrong test. Better questions:

If something doesn't add up, ask the agent why it made that choice. Then verify the answer against the code instead of accepting it. An explanation that cites specific lines is easy to check; one that doesn't is just more text to trust.

Review is much easier when the units are small. A few habits help:

Yenpo is the Mac app I made for the reading step above. To be clear about what it is and isn't:

You don't need it to follow this workflow. git diff, your editor and some discipline get you most of the way. If you want to try it: yenpo.app.

I'd like to hear how others handle this, especially on large agent diffs. What do you check first?

Drafted with AI assistance and reviewed by me.