How do we review code written by Claude Code agents before it is merged?
Treat agent output like any contributor's pull request, but add a local self-review pass before the PR opens, a second reviewer that is not the author, and a merge script that refuses until both have passed. The two-stage gate we run and the records it keeps.
Review agent code the way you review any pull request, with two additions. First, the agent reviews its own branch diff locally and fixes what it finds before the pull request is opened, so the human or second reviewer sees a cleaned diff instead of a first draft. Second, merging goes through a script that checks the review record and refuses otherwise; nobody, including the agent, can merge by hand. The gate is in the repo, so it applies to every session.
Why a plain pull request is not enough
Agent-written branches arrive faster than people read them, and the author never gets tired of pushing fix commits. Without a gate, two things happen: reviewers approve diffs they skimmed, and every fix push restarts a review round. If the second reviewer is a paid or rate-limited service, a long fix loop can burn its budget on one pull request. Our rule, written into CLAUDE.md as a hard rule: never open the PR before the local review pass, and batch fixes into one push.
Stage 1: the agent reviews itself before the PR exists
The pull request is opened by a skill, not by a raw gh pr create. Ours is .claude/skills/self-review/SKILL.md, and the root CLAUDE.md names it as the only path. Its preconditions abort with a message when they fail:
BR=$(git branch --show-current)
[ "$BR" = "main" ] && { echo "on main, make a feature branch first"; exit 1; }
git fetch --quiet origin main
[ -z "$(git diff --stat origin/main...HEAD)" ] && { echo "no diff vs main"; exit 1; }
[ -n "$(git status --porcelain)" ] && { echo "uncommitted changes, commit first"; exit 1; }
Then it reviews git diff origin/main...HEAD with a fixed severity scale:
- P0: breaks production, loses data, opens a security hole, or turns the build red.
- P1: a real bug, wrong behaviour, a missing critical test, a regression.
- P2: quality: reuse, simplification, naming, dead code, minor edge cases.
- P3: nits and style.
P0 and P1 are fixed on the branch and the review loops until none remain; safe P2 fixes go in the same push. Only then does the skill open the pull request. The size check runs first: a diff past a set line or file count gets a split suggestion. It is a warning, not a block, because bulk renames and generated files are legitimate.
The review engine is itself a skill, and for code diffs it fans the diff out to several parallel reviewers with different briefs (security, performance, tests, naming, edge cases) and merges their findings into one list. The author’s session fixes; it does not grade its own work alone.
Stage 2: a reviewer that is not the author
The opened pull request gets a second review from something that did not write it. In our repo that is an automated reviewer bot on the git host; in a team of people it is a teammate. Two details carry over either way:
- Re-review is anchored to a commit. After a fix push, the re-review request names the new SHA. A request without one can silently review the old commit.
- One round, not N. Because stage 1 already removed the P0 and P1 findings, stage 2 usually confirms. If it finds something, the fixes are batched into a single push and a single re-review request.
The merge script is the only door
Direct gh pr merge is blocked by a PreToolUse hook in .claude/settings.json; the hook returns a reason that points at scripts/safe-merge.sh. The script runs the gates in order:
- The second reviewer has approved the current head.
- No open P0 or P1 findings remain on the pull request.
- Pull requests that touch the UI need a
--ui-confirmedflag, meaning a person looked at the preview deployment. - A final confirmation, or
--autofor an unattended run that still enforces gates 1 to 3.
Without --auto the script aborts when stdin is not a terminal, so an unattended session cannot fall through a prompt by accident. P2 and P3 findings do not block; the script files them as backlog issues so they are not lost.
When the second reviewer is unavailable
Review services run out of quota. The wrong response is a bypass flag. Ours is a reviewer swap: REVIEW_MODE=local makes the merge script accept a local review record instead of the external approval, and nothing else changes. The record is a JSON file keyed by the head commit SHA, written by the self-review skill when the diff is clean, and kept out of version control. Any fix push moves the head and invalidates the record, mirroring the freshness rule of the external reviewer. The engine that wrote the record is named in the file, and the team rule is to name it honestly: a quick inline read is not recorded as the full multi-reviewer pass.
There is also an emergency bypass. It requires a reason string and writes to a log file every time it is used. The log is the review of the bypass.
Checklist for your repo
- Write the severity scale into the repo so every review, human or agent, uses the same words.
- Make a skill the only way to open a pull request, with preconditions that refuse a dirty tree or a branch off
main. - Block the merge command with a hook; route merges through a script that checks reviewer approval on the current SHA.
- Require a person to confirm anything user-visible before merge.
- Give the script a documented reviewer-swap mode for outages, with a SHA-pinned record, and a logged emergency bypass.
- Batch fixes into one push; re-review once, with the commit SHA in the request.
- Let P2 and P3 go to the backlog automatically so review does not stall on nits.
This gate is one of the components we install in a team’s repositories; the list is on the Claude Code fleet setup page.
Ready to automate your business?
Get a free workflow analysis to discover your highest-ROI automation opportunities.