Claude Code Review Workflow

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

Keep Claude Code out of final authority. Use it to prepare code review evidence, compare a PR diff against team conventions, and surface security questions before a human approves. A good Claude Code PR review leaves a receipt: files checked, commands run, risks found, and what still needs human judgement.

I would make this part of Team conventions, not a private habit each developer invents. The workflow belongs in the same place as branch rules, test expectations, and review ownership. Claude can do useful first-pass reading, but the team still owns the merge decision.

Start from the PR diff

Ask Claude Code to review the branch against the base branch before it reads half the repository. That keeps the first pass grounded in the actual change, not in a broad tour of the codebase.

In a GitHub pull request workflow, I usually want three things first: the changed files, the nearby tests, and the commands that prove the change still works. For example, if a PR changes an Express auth middleware and its Jest tests, the first pass should inspect the middleware diff, the route that calls it, the auth test file, and the package scripts before it comments on architecture.

A useful opening prompt is short: ask for review findings only, no edits, and require file paths plus evidence. If the agent cannot tie a finding to a line, test, log, or command, it should mark it as a question rather than a defect.

Give the review a narrow command

A slash command is a good home for this because it turns review behavior into a repeatable Claude Code workflow. The command should say what to inspect, what not to change, and what shape the final note must take.

Keep the command boring. Do not ask for “deep review” or “senior engineer judgement” without constraints. Ask for correctness, security-sensitive paths, test coverage, and migration risk, then require a receipt.

This is also where I connect it to the Review step in our methodology: Claude can prepare the review surface, but a person still accepts or rejects the work. The review note should make that boundary visible.

Keep integrations read-only first

MCP can make a Claude Code review more useful because it can connect the local repo to GitHub, issue trackers, docs, or internal knowledge. Start with read-only access for review work. A reviewer rarely needs an agent to write to GitHub, change ticket status, or edit documents while it is still forming findings.

For teams setting this up, I would separate “read PR and related issue” from “post comment” as two different permissions. The first can be part of the normal review command. The second should require an explicit human step until the team has seen enough receipts to trust the pattern.

If you have not already drawn that boundary, start with a small MCP permission note and compare it with the safer setup path in Set Up Claude Code MCP Safely. CLAUDE.md can support the habit by stating durable rules, such as “review commands may read linked issues but must not post comments without approval.”

Use hooks for proof instead of permission

Hooks are useful when they make the review harder to hand-wave. They can run or require checks around a Claude Code session, depending on how your team configures them.

For review, I prefer hooks that collect evidence or enforce a boundary. Run lint before the final receipt. Run the focused test command when the diff touches a tested package. Block writes outside the working tree during a review-only command if that matches your team policy.

A hook should not turn Claude into the approver. It should make sure the review note has the boring proof a human reviewer needs.

Choose the review pass deliberately

Not every PR needs the same Claude Code review agent behavior. A dependency bump, a payment-path change, and a docs-only patch should not get the same prompt.

This table is intentionally small. If a team creates ten review modes, people stop choosing carefully and fall back to the default.

Paste this review receipt into the PR

Use a receipt so the review can be checked without replaying the whole Claude session. This is the artifact I would put in the PR description or a review comment after the human has read it.

## Claude Code review receipt

PR:
Base branch:
Reviewer:
Date:

## Scope checked
- Changed files:
- Related tests:
- Related docs or issues:
- External systems checked through MCP:

## Commands run
- [ ] `npm test` or repo equivalent:
- [ ] Focused test command:
- [ ] Lint or typecheck:

## Findings
| Severity | File or area | Evidence | Recommendation | Human decision |
| --- | --- | --- | --- | --- |
| High / Medium / Low |  |  |  |  |

## Security and permissions
- Secrets, credentials, or tokens touched:
- Auth, authorization, or data access touched:
- MCP access used was read-only:
- Any write action requested from Claude:

## What Claude did not verify
- 

## Final human decision
- [ ] Request changes
- [ ] Approve after changes
- [ ] Approve
- Notes:

Do not let the receipt become theatre. If commands were not run, leave them unchecked. If Claude guessed at impact, write “not verified” and move on.

Further reading

• Claude Code docs
• Claude Code skills
• Claude Code hooks

Run it on one low-risk PR

Pick one small PR, run the review command, paste the receipt, and ask the human reviewer whether it saved time or hid risk. Keep the workflow only if the receipt improves the review conversation.