Claude Code Code Review Checklist for Teams

Start With Risk, Not With “Review This”

If you paste a diff into Claude Code and only say “review this PR”, you will usually get helpful but generic feedback.

Team review needs a sharper frame: what can break, what data is touched, what proof exists, and what must be blocked before merge.

This article gives you a copy-pasteable review checklist, a Claude Code review prompt, a GitHub pull request template, and a GitHub Actions guard for PR hygiene.

Claude Code is not a replacement for human accountability. It is a second set of eyes that can make reviewers more consistent. For the platform details, keep the official Claude Code code review setup guide, Claude Code GitHub Actions docs, GitHub docs for pull request templates, protected branches, and Actions workflows nearby. For security review language, anchor the checklist in the OWASP Secure Code Review Cheat Sheet.

What Risk-Based Review Means

Risk-based review means you do not review every PR with the same weight. A copy change, a marketing CTA, a billing webhook, and a destructive database migration do not deserve the same process. Treating them equally creates two bad outcomes: small changes become slow, and dangerous changes do not get enough attention.

Use three simple levels:

Risk	Examples	Required review
Low	Copy changes, simple CSS, docs, harmless logging text	One reviewer, clear summary, screenshot or diff explanation
Medium	Forms, UI state, search, API response shape, read-only data access	One reviewer, test evidence, Claude Code review
High	Auth, authorization, billing, personal data, migrations, deletes, webhooks	Two reviewers, rollback plan, required CI, security/privacy review

A migration is any database structure or data-shape change. Code can often be reverted. Deleted columns, rewritten records, and failed backfills are harder to recover. That is why migration review must ask “can we roll back?” before it asks whether the code is elegant.

The key is to tell Claude Code the risk level. A vague review request often produces style notes. A focused request such as “High risk: billing webhook and customer email changed” pushes the review toward signature validation, idempotency, privacy, logging, retries, and test evidence.

In Masa’s team notes, the repeated failure was using abstract checklist words such as “quality”, “security”, and “maintainability” without forcing evidence. Those words are fine as headings, but they are weak as review questions. A durable PR template asks for files, data types, risk reasons, test evidence, and rollback steps.

Copy-Paste Review Checklist

Put this in .github/review-checklist.md, a team wiki, or your CLAUDE.md review section. The wording is intentionally concrete so Claude Code and human reviewers can inspect facts instead of intentions.

# Code Review Checklist

## 0. PR scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] Generated or AI-written files are marked in the PR description.
- [ ] No unrelated formatting, dependency, or config changes are mixed in.

## 1. Risk level
- [ ] Risk level is marked as low, medium, or high.
- [ ] High-risk PRs have two human reviewers.
- [ ] High-risk PRs include rollback or recovery steps.

## 2. Security and privacy
- [ ] User input is validated on the server side.
- [ ] Authorization is checked near the data access point.
- [ ] Secrets are not printed, committed, or sent to Claude prompts.
- [ ] Logs do not include email, tokens, addresses, payment IDs, or private content.
- [ ] OWASP-relevant risks such as injection, XSS, broken access control, and SSRF were considered.

## 3. Tests
- [ ] Unit or integration tests cover the changed behavior.
- [ ] Regression tests cover the bug that motivated the PR.
- [ ] Manual verification steps are written with actual result, not "works locally".
- [ ] Snapshot changes are explained.

## 4. Performance
- [ ] New loops, queries, and network calls are bounded.
- [ ] N+1 queries were checked.
- [ ] Large lists, images, and bundles have a budget.
- [ ] Metrics or before/after evidence are attached for performance-sensitive changes.

## 5. Accessibility
- [ ] Keyboard operation works for interactive UI.
- [ ] Focus order and visible focus state are preserved.
- [ ] Form fields have labels and errors that screen readers can understand.
- [ ] Color contrast and reduced-motion behavior are checked where relevant.

## 6. Migration and data risk
- [ ] Migration is backward compatible during rollout.
- [ ] Destructive changes have backup or recovery steps.
- [ ] Old and new app versions can run during deployment.
- [ ] Data cleanup jobs are idempotent.

## 7. AI-generated diff hygiene
- [ ] AI-generated code was read by a human before approval.
- [ ] The diff does not remove tests, monitoring, analytics, or CTA links by accident.
- [ ] New dependencies are justified.
- [ ] Comments do not claim verification that was not actually done.

The important detail is that each item is observable. “Security was considered” is weak. “Logs do not include email, tokens, addresses, payment IDs, or private content” can be checked. “Accessibility is okay” is weak. “Keyboard operation works and visible focus state is preserved” can be checked.

Claude Code Review Prompt

The review prompt should give Claude Code a role, a risk profile, and a rule: produce findings before editing. This keeps review and implementation separate. If you ask for fixes too early, the diff grows while nobody has agreed which findings are real.

You are reviewing a pull request for a production team.

Goal:
- Find concrete risks before merge.
- Prioritize correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
- Do not rewrite code yet. Produce review findings first.

Context:
- Risk level: <low | medium | high>
- Business area: <auth | billing | content | search | admin | analytics | other>
- Sensitive data touched: <none | email | payment | address | health | private content | other>
- Rollout plan: <flag | migration | immediate deploy | other>

Review method:
1. Read the PR summary and changed files.
2. List the top risks by severity.
3. For each finding, include file, line or function, why it matters, and a minimal fix.
4. Separate "must fix before merge" from "follow-up".
5. Check whether tests prove the changed behavior.
6. Check whether any AI-generated code, dependency, config, or formatting change is unrelated to the PR goal.

Output format:
- Findings first, ordered by severity.
- Then missing evidence.
- Then questions for the author.
- Then a short merge recommendation: block, approve with fixes, or approve.

This pairs well with codebase navigation and testing strategy. Before the review, ask Claude Code to explain the domain touched by the PR. That short orientation often prevents a review from becoming only naming and formatting comments.

GitHub Pull Request Template

GitHub can prefill PR text when you add .github/pull_request_template.md. The goal is not paperwork. The goal is to collect review evidence in the same place where reviewers, Claude Code, and branch protection can all see it.

## Summary
- TODO

## Risk
Risk level: low | medium | high

Risk reasons:
- Data touched:
- Users affected:
- Rollout:

## Review focus
- [ ] Correctness
- [ ] Security/privacy
- [ ] Tests
- [ ] Performance
- [ ] Accessibility
- [ ] Migration/data risk
- [ ] AI-generated diff hygiene

## Test evidence
- Automated:
- Manual:
- Not tested because:

## Security and privacy notes
- Secrets changed: no | yes
- Personal data in logs: no | yes
- Authorization boundary changed: no | yes

## Migration / rollback
- Migration included: no | yes
- Backward compatible: no | yes | not applicable
- Rollback plan:

## Claude Code review prompt
Paste this into Claude Code after the PR is ready:

Review this PR as risk level "<low|medium|high>".
Focus on correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
Return findings first with file/function references and minimal fixes.

Avoid a template that is only checkboxes. A large checkbox wall trains people to click through it. Fields such as Risk reasons, Test evidence, and Rollback plan require evidence. They also make automated checks more useful because a guard can fail the PR when the evidence is missing.

CI Guard With GitHub Actions

This guard checks the PR body and changed files. It does not prove the code is correct, but it catches missing review evidence before a reviewer wastes time asking for the basics.

.github/workflows/pr-review-guard.yml:

name: PR review guard

on:
  pull_request:
    types: [opened, edited, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: read

jobs:
  review-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Check PR review evidence
        run: node scripts/pr-review-guard.mjs
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}

scripts/pr-review-guard.mjs:

import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";

const eventPath = process.env.GITHUB_EVENT_PATH;
if (!eventPath) {
  throw new Error("GITHUB_EVENT_PATH is missing. Run this in GitHub Actions.");
}

const event = JSON.parse(readFileSync(eventPath, "utf8"));
const pr = event.pull_request;
const body = pr?.body ?? "";
const base = process.env.BASE_SHA ?? pr?.base?.sha;
const head = process.env.HEAD_SHA ?? pr?.head?.sha;

function safeRef(value, name) {
  if (!value || !/^[a-f0-9]{40}$/i.test(value)) {
    throw new Error(`${name} must be a full git SHA.`);
  }
  return value;
}

const baseSha = safeRef(base, "BASE_SHA");
const headSha = safeRef(head, "HEAD_SHA");
const changedFiles = execSync(`git diff --name-only ${baseSha} ${headSha}`, {
  encoding: "utf8",
})
  .split(/\r?\n/)
  .filter(Boolean);

function includesFile(pattern) {
  return changedFiles.some((file) => pattern.test(file));
}

const failures = [];
const hasRisk = /Risk level:\s*(low|medium|high)/i.test(body);
const hasTests = /## Test evidence[\s\S]*Automated:\s*\S/i.test(body) ||
  /## Test evidence[\s\S]*Manual:\s*\S/i.test(body);
const hasRollback = /Rollback plan:\s*\S/i.test(body);
const highRisk = /Risk level:\s*high/i.test(body);
const migrationChanged = includesFile(/migrations?|schema|prisma|drizzle/i);
const authOrBillingChanged = includesFile(/auth|session|permission|billing|payment|webhook/i);

if (!hasRisk) {
  failures.push("Add `Risk level: low | medium | high` to the PR body.");
}

if (!hasTests) {
  failures.push("Add automated or manual test evidence.");
}

if ((highRisk || migrationChanged) && !hasRollback) {
  failures.push("High-risk or migration PRs need a rollback plan.");
}

if (authOrBillingChanged && !/Security and privacy notes[\s\S]*(Authorization|Personal data|Secrets)/i.test(body)) {
  failures.push("Auth, billing, or webhook changes need security/privacy notes.");
}

if (changedFiles.length > 40 && !/AI-generated diff hygiene/i.test(body)) {
  failures.push("Large diffs need an AI-generated diff hygiene note.");
}

if (failures.length > 0) {
  console.error("PR review guard failed:");
  for (const failure of failures) console.error(`- ${failure}`);
  process.exit(1);
}

console.log("PR review guard passed.");

Make this workflow a required status check on protected branches only after the team has used it for a few PRs. Start strict for high-risk PRs and migrations. Keep low-risk PRs lightweight so the process remains credible.

Security, Privacy, Tests, Performance, and Accessibility

For security, split the review into input, authorization, output, logging, and external calls. Is server-side validation present? Is authorization enforced near the data access point, not only in the UI? Can output produce XSS? Do logs contain private data? Can an external URL, webhook, or proxy path become SSRF or signature-bypass risk?

Privacy is broader than secrets. Email addresses, payment IDs, addresses, inquiry messages, analytics identifiers, and private content all deserve care. Do not paste real API keys, customer emails, contracts, or payment IDs into prompts. Mask the values and give Claude Code the shape of the data.

For tests, require evidence rather than claims. “Works locally” is not evidence. A useful PR says which automated test ran, which manual flow was checked, and what result was observed. If no test was added, the PR should explain why.

For performance, ask Claude Code to look for unbounded loops, N+1 queries, repeated network calls, bundle growth, image weight, and expensive client rendering. Performance review is strongest when it includes before/after numbers, even if the first number is simple.

For accessibility, do not stop at visual screenshots. Check keyboard use, focus order, visible focus state, labels, error messages, dialog focus trapping, and reduced-motion behavior. Claude Code-generated UI often looks clean while missing these details.

Practical Use Cases

Use case one is authentication and admin screens. User lists, role changes, and audit logs must be protected at the API or data access layer. Review authorization, audit logging, personal data in logs, and tests for unauthorized access.

Use case two is billing and webhooks. A payment webhook needs signature validation, idempotency, retry handling, duplicate-event safety, cancellation handling, and privacy-aware logs. Ask Claude Code whether the same event can arrive twice without corrupting state.

Use case three is database migration. Adding a column can still break production if old and new application versions overlap during deployment. Review defaults, not-null constraints, index creation, backfill safety, rollback, and expand-contract sequencing.

Use case four is a large AI-generated UI diff. When Claude Code generates a page, form, modal, or table, review for unintended CTA removal, analytics event changes, accessibility gaps, unexplained snapshot updates, and dependency additions.

Use case five is a revenue content site. A code review for an article page, product page, or lead form should also protect the conversion path. If a change removes a products link, breaks a free PDF form, or stops consultation tracking, the bug is business-critical even when the UI still renders.

Common Pitfalls

The first pitfall is accepting Claude Code findings without verification. AI can make plausible claims. Match each finding to the diff, tests, official docs, or a reproduced result.

The second pitfall is mixing review and implementation. Ask for findings first. Then fix only the accepted must-fix items. This keeps the PR understandable and prevents the diff from expanding during review.

The third pitfall is allowing unrelated AI-generated cleanup. Formatting, dependency changes, config changes, and deleted tests can hide inside a useful-looking diff. Ask Claude Code to list unrelated changes explicitly.

The fourth pitfall is treating database rollback like code rollback. Reverting a commit does not restore deleted data. A high-risk migration needs a backup, recovery SQL, feature flag, or staged migration plan.

The fifth pitfall is making the CI guard too strict. If every small PR needs a long essay, people will write fake evidence. Make high-risk changes strict, keep low-risk changes fast, and use medium-risk changes to build the team’s review habit.

Monetization CTA and Rollout

Review quality protects revenue. Billing flows, product pages, lead forms, free PDF signups, Gumroad links, analytics events, and consultation CTAs are part of the system. A PR that silently removes a CTA can cost money without throwing an exception.

For individual practice, start with the free Claude Code checklist. For reusable review prompts, PR templates, CLAUDE.md patterns, and CI guard material, use the products and templates page. For team rollout across auth, billing, migrations, and review operations, use the Claude Code training and consultation page.

I tested this checklist shape against three small scenario PRs: a Next.js UI change, a database migration, and a Claude Code-generated UI diff. The biggest improvement came from forcing Risk level and Rollback plan into the PR body. Claude Code also gave more concrete findings when the prompt included the risk level and data type. More checklist items alone did not help. A short, evidence-driven template did.

Summary

A Claude Code code review checklist is not just a prompt. It is a team workflow that connects risk classification, PR evidence, human review, CI, and protected branches.

Start small: add the PR template, run the CI guard in advisory mode, then make it required for high-risk changes. Combine this with AI pair programming and CLAUDE.md best practices so the review standard lives in the repository instead of in one senior engineer’s head.