Claude Codeでコードレビューを仕組み化する実践ガイド

Claude Codeをコードレビューに入れる目的は、人間のレビュアーを置き換えることではありません。目的は、PRの差分を先に整理し、危ない領域を見つけ、レビュー観点を揃え、人間が設計判断と業務判断に集中できる状態を作ることです。

チームで使うなら「気が向いたときにClaude Codeへ聞く」だけでは足りません。PRテンプレート、CLAUDE.md、差分サイズのゲート、GitHub Actions、CODEOWNERS、レビュー用プロンプトをつないで、同じ基準で毎回確認できるようにします。

この記事では、Claude Codeによるコードレビューをリスクベースで運用する流れを、コピペして試せる設定と一緒に整理します。リスクベースとは、すべての差分を同じ重さで見るのではなく、認証、決済、権限、データ移行、パフォーマンス、テスト不足など、事故になりやすい場所へレビュー時間を寄せる考え方です。

公式仕様は、Claude Code common workflows、GitHubのpull requestドキュメント、GitHub CODEOWNERS、GitHub Actions workflow syntaxを確認してください。セキュリティ観点はOWASP Code Review Guideも併読すると、Claude Codeへの指示が具体的になります。

全体像

Claude Codeレビューの価値は、単発の指摘よりも「レビュー前の整流」にあります。PR本文で変更意図を固定し、差分サイズをCIで止め、CODEOWNERSで担当者を呼び、Claude Codeには証拠付きで懸念を出させます。

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"]

この図の大事な点は、Claude Codeを「自動修正係」にしないことです。レビューで不明点がある場合は、黙って書き換えるのではなく質問させます。特にデータ移行、権限、監査ログ、課金、外部API契約は、コードだけでは正解が分からないことが多いからです。

用語も最初に揃えておきます。diff scopeは「今回のPRで実際に変わった範囲」です。CI gateは「条件を満たさないPRを自動で止めるチェック」です。CODEOWNERSは「ファイルごとの責任者をGitHubに教える設定」です。hallucinated findingは「根拠のないAI指摘」です。レビューで一番避けたいのは、もっともらしいが差分に存在しない問題でチームの時間を使うことです。

ユースケース

1つ目は、認証と権限の変更です。ログイン、セッション、ロール、管理画面、APIキーを触るPRでは、Claude Codeに「認可漏れ、権限昇格、監査ログ欠落、秘密情報の露出」を重点的に見てもらいます。人間のレビュアーは、業務上そのユーザーが本当に操作できてよいかを判断します。これはセキュリティ監査の自動化とも相性がよい領域です。

2つ目は、パフォーマンスに影響する変更です。検索、一覧、キャッシュ、画像、集計、バッチ処理を変えるPRでは、N+1クエリ、不要な再計算、キャッシュキーの衝突、ページサイズの増加を見ます。Claude Codeには「どの入力サイズで遅くなるか」「計測方法は何か」を答えさせます。推測だけの「遅そうです」はレビューコメントとして弱いです。

3つ目は、テストとデータ移行です。migration、seed、スキーマ変更、バリデーション変更では、後戻りできるか、既存データが壊れないか、ロールバック手順があるかを確認します。Claude Codeには、変更ファイルだけでなく関連するテスト名、未追加のテスト観点、バックフィルの失敗パターンを出させます。

4つ目は、チームのレビュー負荷が高い大きなPRです。差分が1000行を超えるPRは、レビュー品質が落ちます。そこで差分サイズをCIで見て、Claude Codeには「分割案」を出させます。レビューを通すための小細工ではなく、設計単位に切るための支援として使います。

PRテンプレート

まずPR作成者がレビュー材料を出します。.github/pull_request_template.mdを置くと、変更意図、リスク、テスト、Claude Codeへの依頼が毎回同じ形式になります。

## 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

ポイントは「diff scope only」と書くことです。Claude Codeにリポジトリ全体の理想論を語らせると、差分にない問題が混ざります。レビューは今回のPRを良くするための行為なので、根拠を差分に閉じ込めます。

CLAUDE.md

次に、リポジトリ固有のレビュー規則をCLAUDE.mdへ書きます。CLAUDE.mdはClaude Codeに渡すプロジェクトの作業メモです。チームのレビュー観点をここへ置くと、毎回のプロンプトが短くなり、判断も揃います。詳しい運用はCLAUDE.mdベストプラクティスも参考にしてください。

## 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

ここで「質問する」ことを明示します。たとえば「この権限で削除できますか」は質問ですが、「権限漏れです」は根拠が必要です。Claude Codeの指摘を強くするほど、根拠ルールも強くしなければなりません。

差分サイズゲート

大きすぎるPRはレビューの失敗要因です。次のスクリプトをscripts/review-diff-gate.mjsとして保存すると、変更ファイル数、変更行数、リスクの高いパスをチェックできます。

#!/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.`);

ローカルでは次のように実行します。

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

このゲートは万能ではありません。小さくても危険なPRはありますし、大きくても機械的な変更はあります。そのため、止める条件と同時に例外申請の運用も決めます。例外は「急いでいるから」ではなく「生成ファイルだけ」「型名変更だけ」「マイグレーションに専任レビュアーを追加済み」のように説明可能な理由にします。

GitHub Actions

CIでも同じスクリプトを走らせます。.github/workflows/review-gate.ymlに置く例です。

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

Claude Codeのレビュー結果そのものをCIで自動採点する前に、まず差分サイズ、テスト、lint、型チェックを安定させます。AIレビューをマージ条件にするなら、誤検知で開発が止まらないように「警告」「人間の承認で解除」「セキュリティ領域だけ必須」のように段階を分けるのが現実的です。CI/CD設定ガイドと合わせて、既存のパイプラインに薄く足してください。

CODEOWNERS

CODEOWNERSは、危険な領域を適切な人に届けるための設定です。Claude Codeがリスクを見つけても、最終判断は責任者が行います。

# .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のレビューコメントに「この変更はCODEOWNERS上、誰の判断が必要か」を含めると便利です。たとえばマイグレーションを含むPRなら、バックエンドリードに「ロールバック手順」と「既存データのNULL扱い」を見てもらいます。認証なら、セキュリティ担当に「認可」と「監査ログ」を見てもらいます。

レビュープロンプト

最後に、Claude Codeへ渡すレビュー依頼を固定します。重要なのは、黙って修正させないこと、根拠を出させること、分からないことは質問に落とすことです。

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

「No issue found in」を入れると、Claude Codeが何を見たかが分かります。何も指摘しない場合も、セキュリティ、テスト、データ移行を見たのか、単に見落としたのかを区別できます。

落とし穴

よくある失敗は、Claude Codeに「全部直して」と頼むことです。レビューと修正を同時に任せると、指摘の妥当性を検証する前に差分が増えます。最初はレビューだけ、次に人間が合意した項目だけ修正、最後にテストという順番にしてください。

2つ目は、存在しない仕様を前提にした指摘です。たとえば「管理者だけが実行すべきです」と出ても、その機能が社内運用向けなら正しいかもしれません。Claude Codeには「仕様が不明なら質問」と書き、レビュアーは質問とバグを分けて扱います。

3つ目は、データ移行の軽視です。migrationはテストが通っても、本番データで失敗することがあります。既存NULL、重複値、ロック時間、バックフィル失敗時の再実行、ロールバック不能なDDLを必ず見ます。

4つ目は、CIゲートを厳しくしすぎることです。最初からすべてを必須にすると、チームは回避策を探します。まずは差分サイズと危険パスの通知から始め、次に一部を必須化します。PR品質全体の改善はClaude CodeでPR品質を上げるも参考になります。

実際に試した結果

この記事のサンプルは、PRテンプレート、CLAUDE.md、Nodeスクリプト、GitHub Actions、CODEOWNERSを小さなリポジトリに置く前提で確認しました。Nodeスクリプトはgit diff --name-onlyとgit diff --numstatだけを使うので、Node 22とGitがあればローカルでもCIでも動きます。実務では、最初の1週間はゲートを失敗扱いにせず、ログを見て閾値を調整してから必須化するのが安全でした。

チームで導入する場合は、この記事のテンプレートをそのまま入れるのではなく、自分たちの危険パス、レビュー責任者、テストコマンドに置き換えてください。次にレビューゲート導入前チェックを読み、1つのPRで試してから標準化するのが現実的です。