BuildGist

How to review AI-generated code before you merge

Kayvan Zahiri ·

Review AI-generated code before you merge it by reading the request, the diff, and the risky files, then running the tests that cover the behavior you are about to ship.

The request, then the diff

Reread what you asked for before any of the code. The question is whether the change does that, and what it does past it. An agent that "finished" can have done the request and also opened a hole beside it. You will not see the hole in the closing message. You will see it in the diff, if you read the right files.

In the project folder, list the change you are about to merge or commit:

git status
git diff --stat
git diff HEAD

git diff HEAD is everything since the last commit, staged or not. That is the patch a commit from this working tree would record. If the work is already in commits on a branch, read those commits instead of only the uncommitted remainder:

git log --oneline -10
git show

Use the commit ids from the log. If the branch has several commits, git diff from the commit the branch started at, to the tip, is the whole change in one patch. Read that before you merge. A clean git status only means the tip is committed. It does not mean you have read it.

How to take that patch apart for one run, including uncommitted work, is in what did Claude Code change? How to turn each important hunk into one sentence is in how to understand code your AI coding agent wrote.

The steps

  1. Restate the request in one sentence. If you cannot, you are not ready to merge.
  2. Read git diff --stat. Note files you did not expect. An unexpected migration, a new dependency, or a change under sign-in is a stop, not a footnote.
  3. Read sign-in, sessions and permissions first. Then anything that deletes or overwrites data. Then payments. Then new dependencies and lockfiles. Then configuration, CI, and calls to a service that was not there yesterday. Read copy and docs last.
  4. For each important change, finish "Now a user can ...". A change you cannot finish that sentence for stays unmerged.
  5. Check who is rejected, what is deleted, and what a missing or forged id does. The path the request named is the easy one to see.
  6. Search the diff for secrets: keys, tokens, passwords, and files named like .env . BuildGist never records files named like secrets. The merge still can. If a secret is in the patch, take it out before you commit.
  7. Run the tests that cover the sentences from step 4. Run them yourself. A line in the chat that says tests passed is a lead, not the run.
  8. Read new dependencies far enough to know why they were added and whether the request needed them.
  9. Merge or commit only the files that belong to this request. Leave unrelated edits out of the commit.

The home page's run, as a review

The BuildGist home page shows a real Claude Code run, shortened and edited. The request was "Add login with Google." 7 files changed, +224 -16. A review that stopped at "sign-in works" would merge it. The high concern is the reason not to.

The second "now" is a failed review. The delete path asks for sign-in and does not check who owns the note. You find that by reading the delete handler in the diff, or by reading the concern and then reading that handler. Either way the merge waits on the ownership check. The sign-in code can be correct and the change can still be unsafe to ship.

The requested path can be done while a nearby path was left open: an id in a URL, a delete, an admin flag, a new route still wearing the old permission check. The step about rejection and deletion is there so that nearby path gets a sentence of its own.

Where an explanation fits

BuildGist writes a plain-English explanation after each meaningful run of Claude Code, Cursor or Codex, flags concerns, and puts it in your Inbox. Small changes stay quiet. The explanation is a first read of one run: what changed, what it means, what to check. It is written by AI, so the checklist above still ends on the code and on tests you run.

Use the explanation to choose which files to open. Do not use it as the approval. An explanation can include edits you made by hand between agent turns, so a concern might be about a line you wrote. git diff settles whose line it is. When the diff is enough on its own, and when it is not, is in BuildGist or the git diff.

Comment-only, formatting-only and docs-only changes are not given that explanation. They are still in the diff. Skim them so a drive-by edit did not land inside them, and spend the review on the risky files.

After you merge

If more work remains, hand the next agent the request, the sentences you wrote, and the step that is left. A fresh agent with only the merged code will guess the unfinished part. The note in how to switch from Claude Code to Codex is that handoff. Setup for BuildGist, if you want the Inbox explanation on the next run, is in Getting started.

What you need

Codex needs you to approve BuildGist once, in Codex. BuildGist shows the steps. Setup is in Getting started.

To explain a run, your computer sends BuildGist what that run needs, and BuildGist passes it to Anthropic. BuildGist does not keep this material. It does not send your whole repository, files the run did not change, or files named like secrets, such as .env files and keys. It keeps the explanation and short cited excerpts of changed code, at most 12 lines each. Secret masking is best-effort. Privacy has the full list.

Every account gets 7 days of BuildGist Pro free, with no card. The 7 days start at your first explanation or Continue handoff. Nobody is charged when the trial ends. After that, BuildGist Pro is $12 per month, plus any applicable tax shown at checkout. See pricing.

Try BuildGist

Apple silicon, macOS 12 or later. United States, 18 or older.

Related

Questions: kayvanandre@gmail.com.