Claude Code PRレビュー：事前レビューで差分をより速く、安全に

PRレビューに時間がかかる理由

PRレビューが長引くのはコードが"難しい"からだけではありません。差分は変更点を示すだけで全体像を伝えないため、レビュアーは意図やリスク、影響範囲を再構築しなければならないからです。

小さな編集が隠れた依存関係に触れることがあります：フィールド名を変更してレポートが壊れる、デフォルトを変えて挙動が変わる、条件を微調整してエラーハンドリングが変わる。レビュアーが文脈を探してクリックし回したり、アプリをローカルで実行したり、何を意図したPRなのかを理解するために追加の質問をする必要があると、レビュー時間は増大します。

人間の読み方にも問題があります。人は差分を予測可能な方法でざっと見がちで、「主要な」変更に注目してしまい、バグが隠れやすい退屈な行（境界チェック、null処理、ログ、クリーンアップ）を見落とします。また見慣れたものを読む傾向があるため、コピペミスや条件の反転が見逃されることもあります。

良い事前レビューは判決ではありません。人が慎重になるべき箇所を指し示す、迅速で構造化された第二の目線です。理想的なアウトプットは次のとおりです：

• 何が変わったかの平易な要約
• 具体的なリスク箇所（ファイル、関数、前提）
• 可読性に関する指摘（命名、混乱する制御フロー）
• 正確性の懸念（ロジック、エラーハンドリング、データ整合性）
• テストすべきエッジケース（入力、時間、権限、空状態）

やってはいけないこと：PRを「承認」したり、要件を捏造したり、十分な証拠なしにランタイム挙動を推測したりすることです。差分に十分な文脈（期待される入力、制約、呼び出し側の契約）が含まれていない場合、事前レビューはそう指摘し、何が不足しているかを正確に列挙すべきです。

AIの助けは、意味が失われがちなビジネスロジックやリファクタを含む中規模のPRで最も効果的です。一方で、正解が深い組織固有の知識（レガシー挙動、本番のパフォーマンスの癖、社内のセキュリティ規則）に依存する場合は弱いです。

例："ページネーションを更新するだけ"というPRは、しばしばオフバイワンや空結果、APIとUI間のソート不一致を隠しています。事前レビューは、人が30分かけて再発見する前にそうした疑問を浮き彫りにすべきです。

事前レビューでClaudeに何を頼むか

Claudeを速くて厳しいファーストパスのレビュアーとして扱ってください。PRを出すかどうか決める人ではありません。目的は早期に問題を表面化すること：分かりにくいコード、隠れた挙動の変更、テストの欠落、近接していると忘れがちなエッジケースです。

公平な人間のレビュアーが必要とするものを与えましょう：

• PRのゴール（1〜3文）
• 何を壊してはいけないか（APIの形、後方互換性、パフォーマンス予算、セキュリティ規則）
• 特別な制約やトレードオフ（締め切り、段階的ロールアウトなど）
• 意図を理解するのに十分な周辺コードを含む、関連する差分ハンク

PRが既知の高リスク領域に触れるなら、（認証、課金、マイグレーション、同時実行など）最初にそれを明示してください。

その上で、実行可能なアウトプットを依頼しましょう。強力なリクエストの例：

• 変更点を平易な英語（平易な日本語）で要約してください。
• 可読性の問題を指摘してください（命名、構造、驚き、不一致パターン）。
• 正確性のリスクを特定してください（null処理、エラーパス、オフバイワン、データ形状の不一致）。
• テストすべきエッジケースと失敗モードを列挙してください（タイムアウト、リトライ、空入力、部分更新）。
• 欠けているテストと、それぞれのテストが何を証明するかを提案してください。
• 短いレビュアーチェックリストと、マージ前に尋ねるべき5〜10の質問を作ってください。

不確実性に関しては人間が主導権を持てるようにしてください。Claudeに発見を「diffから確実に分かる」ものと「確認が必要」なものにラベル付けし、各懸念を引き起こした正確な行を引用するよう求めてください。

プロンプトする前に差分と文脈を準備する

Claudeの有効性は見せる内容に依存します。大きな差分をゴールも制約もなく貼り付けると、一般的な助言しか得られず、実際のリスクを見逃します。

具体的なゴールと成功基準から始めましょう。例：「このPRはログインエンドポイントにレート制限を追加して悪用を減らします。レスポンスの形は変えてはいけません。平均レイテンシは50ms未満を保つ必要があります。」

次に、重要なものだけを含めます。20ファイル変わっていてもロジックに関わるのは3つなら、その3つに集中してください。関数のシグネチャ、主要な型、振る舞いを変える設定など、スニペットだけだと誤解を招く場合は周辺コンテキストを含めてください。

最後に、テスト期待を明示してください。エッジケースに対する単体テストが欲しいのか、重要な経路の統合テストが必要なのか、手動のUI確認が必要なのかを書いてください。意図的にテストを省略しているなら、その理由を明記してください。

うまく使える簡単な「コンテキストパック」例：

• PRのゴール：何が変わるのか、ユーザーが何を見るのか、何が改善するのか
• 関連差分チャンク：主要なファイルのみ、意図が分かるくらいの周辺コード付き
• ハードな制約：パフォーマンス予算、互換性要件、セキュリティ／プライバシー規則
• テスト期待：何をカバーすべきか、何が追加されたか、実行方法
• "変更してはいけない"項目：公開APIの契約、DBスキーマ、UXの挙動、ログ/監査フォーマット

ステップバイステップ：再現できる事前レビューの流れ

優れたClaude Code PRレビューは短いループで回ります：必要な文脈だけ与え、構造化されたノートを受け取り、それをアクションに変える。人間の代替ではありません。チームメンバーが長時間差分を読む前に簡単な見落としを捕まえます。

5パスの流れ

毎回同じパスを使えば結果は予測しやすくなります：

1. 変更を平易に説明する。 ClaudeにPRの内容、変更されたファイル、変更の理由をまとめさせる。シンプルに説明できないなら、PRの説明を明確にするかスコープを小さくするべきです。
2. まず正確性をチェックする。 ロジックエラー、破られた前提、黙って変わる挙動（デフォルト、エラーハンドリング、権限、タイムゾーン、オフバイワン）を探します。
3. 抜けているケースをスキャンする。 ユーザーと本番の両方の視点で考える：空入力、null、リトライ、部分失敗、同時実行、後方互換性。
4. 可読性と保守性を確認する。 分かりにくい名前、長すぎる関数、重複ロジック、不明瞭なコメント、将来のレビュー時間を増やす小さなリファクタを指摘します。
5. 指摘用コメントをドラフトする。 ファイルごとにコメントをまとめ、関数名や引用スニペットを付けて人間が該当箇所を素早く見つけられるようにします。

ノートを受け取ったら、それを短いマージゲートに落とし込みます。

マージチェックリスト（短く保つ）：

• 新しい挙動と少なくとも1つのエッジケースをカバーするテストがある
• エラーは一貫して処理されている（必要ならログもある）
• 明確な移行パスなしに破壊的変更がない
• 命名と構造が近隣のコードと一致している
• リスクの高い部分にロールバック計画がある

最後に、マージ前に明確にするための3〜5の質問を求めます。例：「APIが空リストを返したらどうなりますか？」や「この処理は同時リクエスト下で安全ですか？」などです。

シンプルなルーブリックを使う（可読性、正確性、エッジケース）

Claudeは固定の視点を与えると最も役に立ちます。ルーブリックがないと、最初に目についたもの（しばしばスタイルの指摘）に偏ってしまい、リスクの高い境界ケースを見落としがちです。

実用的なルーブリック：

• 可読性：明確な命名、単純なフロー、小さな関数、なぜそうしているかを説明するコメント、死んだコードやデバッグ出力なし。
• 正確性：主要な不変条件が保たれている、エラーが一貫して処理されている、null/空値で安全、境界（オフバイワン、丸め）が正しい。
• エッジケース：空／巨大な入力、オプションフィールドの欠如、タイムゾーンや夏時間、二重書き込みを招くリトライ、競合状態。
• セキュリティとプライバシー：認可チェックが適切な場所にある、コードやログにシークレットがない、ログがトークンや機微なペイロードを漏らさない。
• 互換性とロールアウトの安全性：古いクライアントや保存データが壊れない、マイグレーションが安全、ロールバック計画がある。

プロンプト時に各カテゴリについて短い段落を依頼し、「最もリスクが高い問題を先に提示」するよう指示してください。その順序が人間の注意を保ちます。

有用なレビュー・ノートを生むプロンプトテンプレート

テンプレートを再利用するとPRごとに結果が揃います。PRの説明を貼り、差分を続けます。ユーザー向けの挙動があるなら、期待動作を1〜2文で追加してください。

You are doing a pre-review of a pull request.

Context
- Repo/service: <name>
- Goal of change: <1-2 sentences>
- Constraints: <perf, security, backward compatibility, etc>

Input
- PR description:
<...>
- Diff (unified diff):
<...>

Output format
1) Summary (max 4 bullets)
2) Readability notes (nits + suggested rewrites)
3) Correctness risks (what could break, and why)
4) Edge cases to test (specific scenarios)
5) Reviewer checklist (5-10 checkboxes)
6) Questions to ask the author before merge (3-7)

Rules
- Cite evidence by quoting the relevant diff lines and naming file + function/class.
- If unsure, say what info you need.

高リスク変更（認証、支払い、権限、マイグレーション）には、失敗時とロールバックを明示的に考える指示を追加してください：

Extra focus for this review:
- Security/privacy risks, permission bypass, data leaks
- Money/credits/accounting correctness (double-charge, idempotency)
- Migration safety (locks, backfill, down path, runtime compatibility)
- Monitoring/alerts and rollback plan
Return a “stop-ship” section listing issues that should block merge.

リファクタの場合は「振る舞いを変えない」ことを厳格ルールにしてください：

This PR is a refactor. Assume behavior must be identical.
- Flag any behavior change, even if minor.
- List invariants that must remain true.
- Point to the exact diff hunks that could change behavior.
- Suggest a minimal test plan to confirm equivalence.

高速スキムが欲しいときは「200語以内で答えて」などの制限を付け、深堀りしたければ「最大10件の所見と理由を出して」と依頼してください。

Claudeの出力をレビュアーチェックリストに変える

Claudeのノートが有用になるのは、それを人が閉じられる短いチェックリストに変えたときです。差分を繰り返すのではなく、リスクと意思決定を記録してください。

項目を2つのバケットに分けて、スレッドが好みの議論にならないようにしましょう：

Must-fix（マージをブロック）

• 正確性：期待結果が一文で書かれてチケットと一致している
• エッジケース：null/空入力とエラーパスが明確に扱われている（あるいは拒否されている）
• データ安全：書き込みとマイグレーションが既存データと古いコードに対して安全である
• テスト：主な挙動をカバーするテストが1つ、最も危険な失敗をカバーするテストが1つある
• 可観測性：デバッグに十分なログ/メトリクスがある（リクエストID、ユーザーID、ジョブIDなど）

Nice-to-have（フォローアップ）

• 可読性：最も分かりにくい識別子をリネームするか短い「なぜ」コメントを追加する
• 一貫性：既存パターンに合わせる（エラー処理、命名、ファイル配置）
• パフォーマンス：ホットパスの変更をメモし、現行スケールで問題かどうかを示す
• ドキュメント：新しいオプション/フラグが追加されたらインラインDocsを更新する

ロールアウト準備（安全なデプロイ順序、リリース後に見るべき項目、元に戻す方法）も記録してください。

マージ前に尋ねるべき質問

事前レビューが役立つのは、最後に明確化を促す小さな質問セットで終わるときです。

振る舞いと正確性

• ユーザーに見える変更は何か、何を変えてはいけないか？
• 「振る舞いを変えない」が前提なら、出力が同一であることの証拠は何か？
• 本番で最も起きそうな失敗は何で、どこに現れるか（UI、API、データ）？
• コードは入力、順序、時間、ネットワーク呼び出しについてどんな前提をしているか？
• エラーが握りつぶされて静かなデフォルトになっていないか？

エッジケース、テスト、運用

• 最悪の現実的な入力（空、巨大、不正、重複）は何で、どうなるべきか？
• どの一般的なフローがこれを二度発火させる可能性があるか（リトライ、ダブルクリック、バックグラウンドジョブ）、それは安全か？
• 主要な挙動を証明するテストはどれで、最も危険なエッジケースをカバーするテストはどれか？
• テストが欠けている場合、それは書くのが難しいのか、コードがテストしにくいのか？
• 運用側に必要なもの：有用なログ、メトリクス、アラート、設定デフォルト、ロールバック手順は何か？

これらに明確に答えられなければ、マージを一時停止してスコープを絞るか証拠を追加してください。

よくある落とし穴（と回避法）

多くの失敗はプロセスの問題で、モデルの問題ではありません。

• 大きな差分を無差別に貼る。 リスクの高い1〜3領域に絞ってレビューを依頼し、関連ハンクと依存するシグネチャだけを貼る。
• 意図と期待動作を省く。 ゴールがなければレビューがぶれる。何が変わるか、何を変えてはいけないかを2行で書く。
• 自信のある推測を鵜呑みにする。 差分への引用を要求する。引用できないなら仮説として扱いテストを要求する。
• スタイルの些末で議論が長引く。 "Must-fix"と"Nice-to-have"に分け、スタイルは上限を設ける。
• チーム標準を無視する。 早期リターンやエラー型、ログ形式などの慣習があるなら明示して含める。

チェックアウトエンドポイントを新規追加するPRなら、サービス全体を貼らずにハンドラ、バリデーション、DB書き込み、スキーマ変更だけを貼り、「目的：二重課金を防ぐ。非目的：命名のリファクタ」と明記してください。そうすると指摘は少なく検証しやすくなります。

現実的な例：小さなPRの事前レビュー

小さな実例：設定画面に"表示名"フィールドを追加する。サーバ側のバリデーションとクライアントのUIテキストに触れる。十分に小さいがバグが隠れやすい箇所が多い。

貼るべき差分スニペットは次のようなもの（期待動作や関連チケットを2〜3文付ける）：

- if len(name) == 0 { return error("name required") }
+ if len(displayName) < 3 { return error("display name too short") }
+ if len(displayName) > 30 { return error("display name too long") }

- <TextInput label="Name" value={name} />
+ <TextInput label="Display name" value={displayName} helperText="Shown on your profile" />

期待する発見の例：

• 可読性：ファイル間で"displayName"と"name"が混在している。用語を統一して後の変更で翻訳作業が増えないようにする。
• 正確性：サーバは長さを検証しているがクライアント側はしていない。ユーザーは1〜2文字で入力でき、送信後にのみエラーを見ることになる。
• エッジケース：空白のみの文字列は len(displayName) を通過してしまう。検証前にトリムする。

これをチェックリストに変える例：

• API、DBフィールド、UIラベルで命名が一貫している
• クライアント側のチェックがサーバルール（最小/最大、必須）と一致している
• 入力はトリムされる（Unicode/絵文字の扱いが許容できるか確認）
• エラーメッセージはサーバとUIで一致して分かりやすい

クイックチェック、測定、次のステップ

Claude Code PRレビューは以下で終えると効果的です：

• 振る舞い：ユーザーにとって何が変わるか、何を変えてはいけないか
• テスト：何がカバーされ、何が欠けているか、どこがフレークしやすいか
• ログとエラー：失敗時のメッセージは明確か、使えるか
• パフォーマンス：新しいループ、N+1クエリ、大きなペイロード、余分なネットワーク呼び出しがないか
• セキュリティ：バリデーション、認可チェック、シークレット、危険なデフォルト

効果を測るには、2〜4週間で以下の2つの簡単な指標を追跡してください：レビュー時間（オープンから最初の意味あるレビューまで、オープンからマージまで）と手戻り（レビュー後の追加入力コミット数、あるいはコメントによってコード修正が必要になった回数）。

標準化は完璧なプロンプトより強力です。テンプレートを1つ選び、短いコンテキストブロック（何が変わるか、なぜ、どうテストするか）を必須にし、"完了"の定義に合意してください。

チームがチャットベースで機能を作るなら、同じワークフローをKoder.ai内で応用できます：変更を生成し、ソースコードをエクスポートして、事前レビューのチェックリストをPRに添付すれば、人間のレビューは最もリスクの高い部分に集中できます。