Claude Code Review Workflow Checklist: Catch PR Risk Before You Ship

The first three lines decide how deep the review gets

When someone says a Claude Code review felt shallow, the failure is usually not just the model. The request often lacks the changed scope, the behavior that must not break, the checks already run, and the decision the reviewer needs to make.

This article turns Claude Code review into an operating workflow. A review workflow is not a polite request for comments. It is a repeatable sequence: narrow the diff, name the risk, attach evidence, ask for findings first, and keep the final ship decision with a human owner.

For beginners, a diff means the exact code or content changed in this PR. A review gate is the checkpoint before merge or publication. A verification receipt is the short record of commands, browser checks, logs, screenshots, and remaining risk. Keep the official Claude Code overview, common workflows, GitHub pull request review docs, and npm scripts docs nearby when you turn this into team practice.

Use this workflow with the deeper Claude Code code review checklist and the verification receipt workflow. The checklist gives review angles. The receipt makes the result auditable.

The workflow before Claude Code sees the diff

Claude Code is much better at finding defects when the input has four pieces: scope, risk, evidence, and handoff. Without them, it will often produce a reasonable summary that still misses the issue that blocks release.

Input	Purpose	Weak version	Strong version
Scope	Limit what changed	Fixed a few things	Only article CTA links, copy, and mobile spacing changed
Risk	Name the impact	Should be fine	Product, consultation, and internal links affect revenue
Evidence	Show what was checked	Works locally	npm run build passed and CTA path was checked at 360px
Handoff	Define the output	Please review	Return P1/P2/P3 findings, residual risk, and next checks

flowchart LR
  A["Diff"] --> B["Scope and risk"]
  B --> C["Claude Code review"]
  C --> D["Human decision"]
  D --> E["Fix, verify, or ship"]
  E --> F["Review receipt"]

The key boundary is simple: Claude Code is a second set of eyes, not the approver. It can reduce missed issues, suggest tests, and point to weak assumptions. The PR owner still decides whether to fix, re-test, or ship.

Pre-review checklist

Start by collecting the working tree state and the verification commands. The commands below fit a Node project. In other stacks, replace the last lines with bundle exec rspec, go test ./..., pytest, or your normal CI entry point.

git status --short
git diff --stat
git diff --name-only
npm run build
npm run test -- --runInBand

Then put a concrete checklist in the PR description, .github/review-checklist.md, or your team wiki.

# Claude Code Review Checklist

## Scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] No unrelated formatting, dependency, or generated files are mixed in.

## Risk
- [ ] Risk level is marked as low, medium, or high.
- [ ] User-facing routes, forms, auth, billing, analytics, and CTA paths are named.
- [ ] Rollback or recovery steps are written for high-risk changes.

## Evidence
- [ ] Build, test, lint, or typecheck commands are listed with results.
- [ ] Manual checks include browser width, account state, and actual URL when relevant.
- [ ] Screenshots, logs, or console output are attached for UI and integration changes.

## Review output
- [ ] Findings come first, ordered by severity.
- [ ] Each finding has file reference, reproduction condition, and expected fix.
- [ ] Residual risk is written even when no blocker is found.

The checklist exists to make the review concrete. You are not asking Claude Code to admire the implementation. You are asking it to find release risk and convert that risk into the next action.

Copy-paste review prompt

The prompt can stay short if the output contract is strict. The most useful phrases are “bug-finding mindset”, “findings first”, and “do not rewrite code yet”.

Review this diff with a bug-finding mindset.

Scope:
- Only review the files changed in this PR.
- Do not rewrite code yet.

Prioritize:
1. behavioral regressions
2. security, privacy, or permission mistakes
3. missing tests or weak verification
4. broken mobile layout, internal links, product CTA, or training CTA

Return:
- Findings first, ordered by P1/P2/P3 severity
- File and line references when possible
- Why each issue matters to users or revenue
- Checks I should run next
- Residual risk if no blocker is found

Keeping the first pass read-only matters. If Claude Code starts editing while reviewing, the team loses the list of issues and the reasoning behind priorities. Accept the findings first, then open a separate fix task.

Four practical review use cases

The first use case is a CTA or revenue path change. If the article footer, product block, pricing copy, or consultation link changes, review the destination URL, product match, button order, mobile layout, and analytics event. A real failure mode is a button that says “templates” but still points to an old Gumroad product. Ask Claude Code to inspect product CTA, training CTA, and mobile width together. Link readers to /en/products/ and /en/training/ in the same order the article promises.

The second use case is auth, permission, or private data. UI code that hides a button is not the same as server-side authorization. Claude Code should check who can perform the action, who must be rejected, whether logs expose email or payment IDs, and whether tests cover the rejected user. The common pitfall is reviewing readability while missing a privilege bypass.

The third use case is multilingual publishing. One locale can read naturally while another has an old updatedDate, an unclosed code fence, a missing product link, or mojibake. Tell Claude Code the exact locale files it may touch, what metadata must be preserved, and which strings must be present. Pair this with the bug report template when only one language is broken.

The fourth use case is build or test failure triage. Do not paste a huge log and ask for a fix. Give the failing command, the last relevant log lines, the files changed just before failure, and what you already tried. The pitfall is letting a small build fix turn into dependency churn. The review question is whether the fix stays inside the failure cause.

Failure cases to avoid

The most common bad request is “review everything”. That scope pushes Claude Code toward safe generalities. A better request says which files changed, which behavior must not change, and which area is out of scope.

The next failure is missing evidence. If the review cannot tell whether npm run build, typecheck, a browser path, or a mobile layout was checked, it must guess. If you could not run a command, write that down with the reason. Honest unknowns are better than fake confidence.

Revenue paths have their own traps. Desktop-only checking misses CTA wrapping, horizontal scroll, and product cards that hide the next action. A review should inspect /products/, /training/, Gumroad links, free resources, and the order of the calls to action against the article’s reader intent.

Security mistakes often start with prompts that include too much data. Do not paste API keys, tokens, customer emails, payment IDs, or private content. Reduce logs to the minimum reproducible lines before asking for help.

Verify the review receipt mechanically

This small Node script checks that a review receipt has the required sections and at least one checked command. It is not a full quality gate, but it prevents the most common process failure: shipping with no evidence.

{
  "requiredSections": ["Scope", "Risk", "Checks run", "Findings", "Residual risk"]
}

#!/usr/bin/env node
const fs = require("node:fs");

const receiptPath = process.argv[2] || "review-receipt.md";
const policyPath = process.argv[3] || "review-policy.json";
const receipt = fs.readFileSync(receiptPath, "utf8");
const policy = fs.existsSync(policyPath)
  ? JSON.parse(fs.readFileSync(policyPath, "utf8"))
  : { requiredSections: ["Scope", "Risk", "Checks run", "Findings", "Residual risk"] };

const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
const missingSections = policy.requiredSections.filter((name) => {
  const heading = new RegExp(`^## ${escapeRegExp(name)}\\b`, "m");
  return !heading.test(receipt);
});

const hasCheckedCommand = /^- \[(x|X)\] `(npm|pnpm|yarn|node|pytest|go test|cargo test)/m.test(receipt);

if (missingSections.length || !hasCheckedCommand) {
  for (const section of missingSections) console.error(`Missing section: ${section}`);
  if (!hasCheckedCommand) console.error("Missing checked command evidence such as - [x] `npm run build`");
  process.exit(1);
}

console.log("Review receipt passed.");

# Review receipt

## Scope
Article CTA links and mobile layout only.

## Risk
Medium: product and training links affect revenue.

## Checks run
- [x] `npm run build` passed
- [x] mobile CTA path checked at 360px

## Findings
- P2: Product CTA text and destination mismatch on one locale.

## Residual risk
Analytics event names were not checked in production.

This script deliberately checks process, not taste. Teams can wire the same idea into a PR template, a Claude Code prompt, or a lightweight CI check.

Next step

Solo developers should start with the free Claude Code cheatsheet to stabilize daily commands and safe review phrasing. If you keep rewriting review, debugging, and triage prompts, use Prompt Templates and the /en/products/ page to standardize them.

For teams, the hard part is not one clever prompt. It is agreeing on CLAUDE.md, permission boundaries, review gates, verification receipts, and who can approve a high-risk PR. For a workflow adapted to a real repository, use /en/training/ to plan the rollout.

In my test on a small article update, the structured request found a CTA mismatch, a mobile-width gap, and an unverified test path more clearly than a plain “please review this” prompt. Claude Code is not a magic approver, but it is useful as a disciplined pre-ship reviewer when the workflow gives it evidence and boundaries.