Claude Code Code Review Workflow for Team Pull Requests

Claude Code is useful in code review when it becomes a repeatable review workflow, not when it acts as a random second opinion. The goal is to sort the PR, expose risky areas, ask better questions, and let human reviewers spend their energy on architecture, product intent, and ownership decisions.

For a team, the practical setup is a PR template, repository review rules in CLAUDE.md, a diff-size gate, GitHub Actions, CODEOWNERS routing, and a prompt that forces evidence. Keep the official references close: Claude Code common workflows, GitHub pull request docs, GitHub CODEOWNERS, GitHub Actions workflow syntax, and the OWASP Code Review Guide.

Review System

Risk-based review means you do not review every line with the same intensity. Auth, billing, permissions, data migration, performance, and test gaps deserve more attention than a copy change. Diff scope means the files and lines changed in this PR. A CI gate is an automated check that can block or warn on risky conditions. A hallucinated finding is an AI review comment that sounds plausible but has no evidence in the diff.

flowchart LR
  A["PR template"] --> B["Diff size gate"]
  B --> C["Claude Code review"]
  C --> D["Code owner review"]
  D --> E["CI tests and merge"]
  C --> F["Questions before fixes"]

The key rule is simple: Claude Code should not silently rewrite code during review. If intent, data contracts, or permissions are unclear, it should ask. That is especially important for database migrations, audit logs, paid features, external API contracts, and authorization checks.

Real Use Cases

First, use it for authentication and authorization changes. Ask Claude Code to check missing authorization, privilege escalation, unsafe session handling, secret leakage, and missing audit logs. The human reviewer still decides whether the business rule is correct. For deeper security workflows, pair this with automating security audits.

Second, use it for performance-sensitive PRs. Search pages, dashboard lists, image workflows, caches, and batch jobs can hide N+1 queries, repeated rendering, cache-key collisions, and oversized payloads. A good Claude Code review should say which input size matters and how to measure it. “This may be slow” is not enough.

Third, use it for tests and data migrations. Schema changes, validation changes, seed scripts, and backfills need rollback thinking. Claude Code can list missing unit tests, migration edge cases, nullable fields, uniqueness issues, and backfill failure modes before a database owner reviews the PR.

Fourth, use it for oversized PRs. Once a diff passes 800 to 1000 changed lines, review quality usually drops. Claude Code can propose a split by behavior, migration, UI, and tests, while CI enforces a threshold.

PR Template

Create .github/pull_request_template.md so authors provide review material before Claude Code or humans start reading.

## Change summary
- What changed:
- Why it changed:
- User-visible impact:

## Risk review
- [ ] Security impact checked
- [ ] Performance impact checked
- [ ] Test coverage added or explained
- [ ] Data migration or rollback plan checked
- [ ] No secrets, tokens, or personal data included

## Claude Code review request
Please review this PR by diff scope only.

Focus on:
- Security: auth, authorization, injection, secret leakage
- Performance: N+1 queries, cache keys, unnecessary work
- Tests: missing unit, integration, and migration tests
- Data: schema changes, rollback, backfill safety

For each finding, include:
- file and line
- why it matters
- evidence from the diff
- suggested fix or question for the author

The phrase “diff scope only” matters. It keeps the review grounded in the PR instead of producing generic advice about the whole repository.

CLAUDE.md Rules

Put team review policy in CLAUDE.md. This file is the project memory Claude Code can use for local standards. See CLAUDE.md best practices for a broader setup.

## Code review rules

Review only the current diff unless the user asks for wider context.

Severity:
- Must fix: security bug, data loss, broken build, failed test, migration risk
- Should fix: likely production bug, missing important test, measurable performance issue
- Nice to have: naming, small cleanup, optional refactor

Evidence rule:
- Every finding must cite a file and line.
- If the evidence is uncertain, ask a question instead of asserting a bug.
- Do not invent dependencies, routes, database columns, or team policies.

Security checks:
- Authentication and authorization
- SQL or command injection
- XSS and unsafe HTML
- Secret leakage
- Missing audit log for privileged actions

Data checks:
- Migration rollback path
- Backfill failure behavior
- Existing nullable and unique constraints
- PII handling and retention

The evidence rule prevents most bad AI review comments. A finding without a file, line, and reason should be treated as a question or ignored.

Diff Gate Script

Save this as scripts/review-diff-gate.mjs. It checks changed file count, changed lines, and sensitive paths.

#!/usr/bin/env node
import { execSync } from "node:child_process";

const baseRef = process.env.BASE_REF || "origin/main";
const maxFiles = Number(process.env.MAX_REVIEW_FILES || 25);
const maxLines = Number(process.env.MAX_REVIEW_LINES || 800);

function git(command) {
  return execSync(command, { encoding: "utf8" }).trim();
}

const files = git(`git diff --name-only ${baseRef}...HEAD`)
  .split(/\r?\n/)
  .filter(Boolean);

const numstat = git(`git diff --numstat ${baseRef}...HEAD`);
const changedLines = numstat
  .split(/\r?\n/)
  .filter(Boolean)
  .reduce((total, line) => {
    const [added, deleted] = line.split(/\s+/);
    return total + (Number(added) || 0) + (Number(deleted) || 0);
  }, 0);

const riskyPatterns = [
  /^src\/auth\//,
  /^src\/billing\//,
  /^db\/migrations\//,
  /^infra\//,
  /^\.github\/workflows\//,
];

const riskyFiles = files.filter((file) =>
  riskyPatterns.some((pattern) => pattern.test(file))
);

let failed = false;

if (files.length > maxFiles) {
  console.error(`Too many files changed: ${files.length} > ${maxFiles}`);
  failed = true;
}

if (changedLines > maxLines) {
  console.error(`Too many changed lines: ${changedLines} > ${maxLines}`);
  failed = true;
}

if (riskyFiles.length > 0) {
  console.log("Risk-sensitive files changed:");
  for (const file of riskyFiles) console.log(`- ${file}`);
}

if (failed) {
  console.error("Split the PR or add a reviewer-approved exception.");
  process.exit(1);
}

console.log(`Review gate passed: ${files.length} files, ${changedLines} lines.`);

Run it locally:

BASE_REF=origin/main MAX_REVIEW_FILES=25 MAX_REVIEW_LINES=800 node scripts/review-diff-gate.mjs

Start with warning mode if your team has many large PRs. After one week, set thresholds that match reality.

GitHub Actions Gate

Add .github/workflows/review-gate.yml to run the same check on pull requests.

name: review-gate

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

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

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

      - name: Run diff size gate
        env:
          BASE_REF: origin/${{ github.base_ref }}
          MAX_REVIEW_FILES: "25"
          MAX_REVIEW_LINES: "800"
        run: node scripts/review-diff-gate.mjs

Do not make AI output the first hard merge gate. Stabilize lint, typecheck, tests, and diff-size checks first. For more pipeline context, read the CI/CD setup guide.

CODEOWNERS Routing

Use CODEOWNERS to route risky files to the right humans.

# .github/CODEOWNERS
/src/auth/ @example-org/security
/src/billing/ @example-org/payments
/db/migrations/ @example-org/backend-leads
/.github/workflows/ @example-org/platform
/infra/ @example-org/platform

Claude Code can help by saying which owner should look at which risk. It should not make the final call on business permissions, migration safety, or payment behavior.

Review Prompt

Use a fixed prompt for review sessions.

Review the current PR diff against main.

Rules:
1. Stay inside the diff scope unless a referenced file is required.
2. Do not rewrite code silently.
3. For each finding, include file, line, severity, evidence, and suggested action.
4. If business intent or data contract is unclear, ask a question instead of guessing.
5. Ignore style-only preferences unless they break CLAUDE.md or project conventions.

Focus areas:
- Security: auth, authorization, injection, XSS, secrets, audit logs
- Performance: N+1 queries, cache invalidation, repeated rendering, large payloads
- Tests: missing coverage for changed behavior, migrations, and edge cases
- Data migration: rollback, backfill, nullable fields, unique constraints
- CI and ownership: required checks, CODEOWNERS, risky paths

Output:
## Must fix
## Should fix
## Questions
## No issue found in

The “Questions” section is not a weakness. It is how you avoid confident but false findings.

Pitfalls

The first pitfall is asking Claude Code to review and fix everything in one pass. That expands the diff before the team agrees on the findings. Review first, choose fixes second, run tests third.

The second pitfall is accepting findings without evidence. If Claude Code cannot point to a file, line, and changed behavior, the item belongs in questions.

The third pitfall is under-reviewing migrations. Passing tests do not prove production data is safe. Check existing nulls, duplicates, locks, backfill retry behavior, and rollback limits.

The fourth pitfall is making gates too strict on day one. Start with notification, then require gates only for high-risk paths. For broader PR practice, read improving pull request quality with Claude Code.

Verification Note

I validated the examples as a minimal repo workflow: the Node script depends only on Git and Node 22, the Action runs that same script, and the templates keep Claude Code grounded in diff evidence. In a real team, I would run the gate in warning mode for the first week, tune thresholds, then make only the high-confidence checks required.

Use this article as a starting checklist, then adapt risky paths, owners, and test commands to your repository. For the next step, compare it with the review gate before commit checklist and try it on one PR before rolling it out.