Claude Codeレビューの仕組みを解説：差分、フック、そしてエージェントが検出するもの
シニアエンジニアが行うようなエージェント型レビューを、差分から直接、余計な手間なく実行できます。
Claude Code レビュー: エージェント型PRレビューの実践ガイド
Claude Codeは、経験豊富なシニアエンジニアが行うのと同じように、プルリクエストやローカルのdiffをレビューできます — 変更されたファイルを読み、呼び出し箇所をたどり、テストを確認し、重大度でランク付けされた指摘事項を修正案とともに返します。このガイドは、コードレビューのために Claude Code（Anthropicのエージェント型CLIツール）を使用することに特化しています。起動方法、効果的なプロンプトの与え方、すべてのコミットやPRでの自動化方法、チームパイプラインへの組み込み方について解説します。
「Claude Code レビュー」が実際に意味すること
人々が「Claude code review」と呼ぶものには、大きく異なる2つのものがあります。1つ目は、チャットインターフェースでClaudeに貼り付けたコードスニペットを見てもらうことです。2つ目 — このガイドの主題です — は、実際のリポジトリ内で本物のdiffやプルリクエストに対してClaude Code（Anthropicのエージェント型CLI）を実行することです。
この違いは非常に重要です。Claude Codeがdiffをレビューする際、貼り付けられた抜粋について単独で推論しているわけではありません。ファイルを開き、importをたどり、CLAUDE.mdのプロジェクト指示を読み、隣接するテストを確認し、1件の指摘を出す前に変更の全体的な文脈を理解できる自律的なエージェントなのです。このファイル横断的な把握力こそが、出力を単なる汎用的なものではなく、真に有用なものにしています。
Claude Codeは、ローカルにインストールするCLI（npm install -g @anthropic-ai/claude-code）としても、クラウドサンドボックス上で動作するエージェントとしても利用可能です — 両方のアプローチについては後述します。Anthropicの公式ドキュメントにインストールと初期セットアップの手順が記載されています。
/review ワークフローをステップごとに解説
Claude Codeには、まさにこのタスクのために設計された/reviewスラッシュコマンドが搭載されています。以下は、diffから実行可能な出力までの全ワークフローです。
ステップ1 — Claude Codeにdiffを指定する
レビューしたい変更を渡す方法はいくつかあります。
ステージされた変更（/reviewコマンド）:
/reviewClaude Codeセッション内で、/reviewスラッシュコマンドは変更のレビューを開始します。これは最も一般的なローカルワークフローです。作業をステージし、/reviewを実行して、コミット前に指摘事項を確認します。（正確なコマンドの挙動は進化するため、最新の構文についてはAnthropicのClaude Codeドキュメントを確認してください。）
特定のgit範囲:
自然言語でエージェントに依頼することもできます — 例えば、*「mainとこのブランチの間のdiffをレビューして、バグや退行がないか確認して」*といった具合です。Claude Codeは自らgitコマンドを実行できるため、指定した範囲のdiffを生成しレビューします。これは、PRを開く前にフィーチャーブランチをレビューする際に便利で、正確なフラグ構文に依存する必要がありません。
GitHubプルリクエストのURL:
プロジェクトでGitHub CLIが設定されている場合、Claude CodeはPRのdiffを直接取得できます。プロンプトにPRのURLまたは番号を指定すると、エージェントはghを使ってdiffとPRの説明を取得し、コードとともに意図の文脈も得ることができます。
ステップ2 — コンテキストの読み込み
指摘事項を出す前に、Claude Codeはdiffを適切に評価するために必要なコンテキストを読み込みます。
CLAUDE.md— プロジェクトの指示ファイルで、レビューの重点領域、禁止パターン、アーキテクチャルール、チームの規約などを定義できます。これは、エージェントが何に注意を払うかをカスタマイズするための主要な手段です。- importされたモジュールと呼び出し元 — 変更された関数が10箇所から呼ばれている場合、エージェントはその呼び出し箇所を読んで、変更が後方互換性を保っているかを確認します。
- 既存のテスト — 変更されたコードの意図された契約を理解し、新しいロジックにカバレッジが不足していないかを確認するために、テストファイルを読みます。
- 設定ファイル —
eslint、tsconfig、pyproject.tomlなどのファイルは、CIで既に強制されているlintルールをエージェントが理解する助けとなり、ツールがすでに検出している内容を重複して指摘しないようにします。
ステップ3 — 分析
Claude Codeの分析パスは、複数の観点を同時にカバーします。
- 正しさ — ロジックバグ、off-by-oneエラー、nullデリファレンス、誤ったアルゴリズムの前提
- セキュリティ — インジェクションのリスク、露出した認証情報、安全でないデシリアライズ、認可チェックの欠落
- 信頼性 — エラーハンドリングの欠落、処理されていないPromiseの拒否、捕捉されていないエッジケース
- 保守性 — 重複ロジック、不明瞭な命名、非自明な挙動に対するドキュメントの欠如
- テストカバレッジ — 対応するテストがないまま追加されたコードパス
エージェントは単に行を指摘するだけではありません。その指摘が_なぜ_重要なのか、もしそのままリリースされた場合の影響は何かを説明します。
ステップ4 — 構造化された指摘事項
出力は指摘事項のリストであり、それぞれに以下が含まれます。
- 重大度ラベル（通常: critical / warning / suggestion）
- ファイルと行の参照
- 問題についての平易な英語での説明
- 修正案 — 多くの場合、そのまま適用可能なコードスニペット
デフォルトでは指摘事項はターミナルに出力されます。チーム利用の場合、これをリダイレクトできます — ファイルにパイプする、gh pr commentでPRコメントとして投稿する、フックを使って共有レビューログに書き込む、などです。
Claude Codeレビューは構造化されたパイプラインに従います — diffの入力からコンテキスト読み込み、分析、ランク付けされた指摘事項と修正案まで、フックによって完全な自動化が可能です。
実例で見る: 実際のdiff、実際のレビュー
これを具体的に示すために、最小限のPythonのdiffと、Claude Codeレビューが明らかにする内容を見てみましょう。
diff:
# Before
def get_user(user_id):
result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
return result[0]
# After (in PR)
def get_user(user_id):
result = db.query(f"SELECT * FROM users WHERE id = {user_id}")
if result:
return result[0]
return NonePRの作成者が修正したと考えていたこと: ユーザーが見つからない場合のKeyError。
Claude Codeがレビューで明らかにすること:
-
Critical — SQLインジェクション（2行目）: f-stringが
user_idを直接クエリに埋め込んでいます。1; DROP TABLE users;--のような値が実行されてしまいます。修正案: パラメータ化クエリを使用してください —db.query("SELECT * FROM users WHERE id = ?", (user_id,))。 -
Warning — 暗黙的な
None返却の伝播:Noneをチェックしないget_userの呼び出し元は、離れた場所で失敗するようになります。ユーザーオブジェクトが常に返されると想定している3つの呼び出し箇所（ファイルごとに列挙）を確認してください。 -
Suggestion — 型アノテーションの欠落: 戻り値の型は
Optional[User]であるべきで、そうすればIDEや型チェッカーが呼び出し箇所で自動的にNoneケースを検出できます。 -
Suggestion — テストは追加されているが不完全: 新しいテスト
test_get_user_not_foundはNoneが返されることのみを確認しており、user_idが0や非整数の場合の挙動を検証していません。
元の作成者はKeyErrorを修正しましたが、暗黙のNone伝播リスクを新たに持ち込み、既存のSQLインジェクションに気づきませんでした。Claude Codeは両方を捕捉しました — diffだけでなく呼び出し箇所を読んだからこそ発見できたのです。
より良いレビューのためのClaude Codeへのプロンプト
レビューの質は、エージェントに与えるコンテキストの質に直接比例します。以下のプロンプトとテクニックは、一貫してより良い出力を生み出します。
CLAUDE.mdを使って恒常的な指示を設定する
最も効果があるのは、プロジェクトのCLAUDE.mdファイルです。## Review Guidelinesセクションを追加してください。
## Review Guidelines
- We use parameterized queries everywhere. Flag any string interpolation in SQL.
- All public functions must have return-type annotations (Python) or JSDoc (JS).
- Security findings should always be severity: critical, not warning.
- We prefer explicit error returns over exceptions in the data layer.
- Do not flag import ordering — Black handles that automatically.これはエージェントに一度指示するだけで、プロジェクト内の以降のすべてのレビューがこれらのルールを引き継ぎ、再度プロンプトする必要がなくなります。
プロンプトで意図を伝える
対話的にレビューを呼び出す際は、そのPRが何を達成しようとしているのかをエージェントに伝えてください。
/review This PR migrates our auth flow from JWT to session cookies. Focus on
session fixation, secure cookie attributes, and any places we might be leaking
the old JWT validation logic.意図の文脈があることで、Claude Codeはすべての観点にわたって一律のチェックリストを生成するのではなく、関連する指摘事項を優先できます。
まず重大度のみのパスを依頼する
大規模なdiffの場合、2パスのアプローチが効率的です。
/review Pass 1: list only critical and warning severity findings with file+line.
No suggestions yet.その後、criticalなリストが手に入ったら、特定の指摘事項について修正の詳細を依頼します。これにより、200行のレビュー出力の中でスタイルの提案に埋もれてcriticalなバグが見逃される問題を回避できます。
理解の確認を依頼する
複雑な変更の場合:
Before reviewing, summarize what this diff is trying to do in two sentences,
then proceed with the review.要約が間違っていれば、エージェントがdiffを誤読していることが分かり、誤った指摘事項に時間を無駄にする前に訂正できます。
フックによるレビューの自動化
/reviewを手動で実行するのは有用ですが、本当の生産性向上は、人が覚えておかなくても、すべてのコミットや開かれたPRごとに自動的にトリガーされるようにすることです。Claude Codeのフックシステムがこれを可能にします。（フックシステムについてはClaude Code hooksガイドで詳しく解説しています — このセクションではレビューのユースケースに特化して説明します。）
すべてのコミットで自動レビュー
プロジェクトの.claude/settings.jsonにStopフックを追加します。
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "claude -p 'Review the diff from the last commit (git diff HEAD~1 HEAD) and list any bugs, security issues, or regressions.'"
}
]
}
]
}
}これを設定すると、Claude Codeがタスクを完了するたび（コミットで終わるコーディングタスクを含む）にフックが発火し、結果のdiffをレビューします。指摘事項は、コミットが完了した直後にターミナルに表示されます。
PRオープン時の自動レビュー
CI統合の場合、GitHub ActionsジョブでClaude Codeをヘッドレスモード（claude -p "<prompt>"）で実行し、結果をPRコメントとして投稿します。以下のパターンは例示的なものです — Anthropicは公式のClaude Code GitHub Actionも公開しているため、フラグをそのままコピーするのではなく、最新の推奨CIセットアップについてはClaude Codeドキュメントを確認してください。
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Claude Code
run: npm install -g @anthropic-ai/claude-code
- name: Run review
run: |
claude -p "Review the diff between origin/${{ github.base_ref }} and HEAD. \
List bugs, security issues, and regressions, ranked by severity." > review.md
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- name: Post review as PR comment
run: gh pr comment ${{ github.event.number }} --body-file review.md
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}これにより、プッシュのたびにClaude Codeの指摘事項が自動的にPRコメントとして投稿されます。人間のレビュアーは、エージェントがすでに明らかにした項目にレビュー時間を費やすのではなく、Claude Codeが確実に捕捉する項目以外に注意を集中できるようになります。
Claude Codeレビューが捕捉すること — そして見逃すこと
その能力の範囲について明確に理解しておくことが重要です。AIレビューは特定の種類の指摘事項に対しては本当に強力ですが、それ以外については確実に不十分です。
Claude Codeは機械的な正しさ、セキュリティパターン、一貫性に優れています — 一方、製品判断、新しい脅威、コンプライアンスの承認は依然として人間の責任です。
Claude Codeが確実に捕捉すること:
- diffとその直接的な文脈で見える範囲の、off-by-oneエラー、null/undefinedデリファレンス、型の不一致
- 既知のセキュリティパターン: SQLインジェクション、XSS、CSRFの欠陥、安全でない直接オブジェクト参照、入力検証の欠落、コード内のシークレット
CLAUDE.mdと設定ファイルで定義されたルールに対するスタイルおよび規約違反- 重複ロジック — エージェントのファイル横断的な把握力により、追加した関数が2つ離れたディレクトリのユーティリティモジュールにすでに存在することに気づく
- エラーハンドリングの欠落 — 処理されていないPromiseの拒否、素の
except節、呼び出し元が想定していないのにNoneやundefinedを返しうる関数 - diffで追加された特定のコードパスに対するテストカバレッジのギャップ
Claude Codeが人間の判断に取って代わらないこと:
- 製品と要件の判断。 その機能が存在すべきかどうか、UXが理にかなっているか、APIの契約が正しい抽象化かどうか — これらにはどのエージェントも持ち得ないビジネス上の文脈が必要です。
- 新しいセキュリティ上の脅威。 エージェントは既知の脆弱性クラスを知っていますが、アプリケーションのデプロイ環境やビジネスロジックに特有の脅威モデルを考案することはありません。
- 大規模なパフォーマンス。 静的解析は、プロファイラの出力、負荷テストの結果、実際のトラフィックパターンの理解の代わりにはなりません。
- 規制遵守。 GDPR、HIPAA、PCI-DSSなどは人間の承認が必要であり、しばしば法務レビューも必要です。AIレビューはその代わりにはなりません。
- チームのダイナミクスとアーキテクチャガバナンス。「これはこのモジュールに属すべきか？」「この依存関係を導入すべきか？」といった判断には組織的な文脈が必要です。
健全な捉え方はこうです。Claude Codeレビューは、機械的なエラーの捕捉、規約の強制、既知の悪いパターンの指摘といったコードレビューの_退屈な_部分を排除します。それにより、人間のレビュアーは実際に人間の判断が必要な判断事項に限られた注意を集中させることができます。
Claude Codeレビューをチームパイプラインに統合する
チームに一貫してエージェント型レビューを実際に使ってもらうには、それをオプションの追加機能としてではなく、ワークフローの第一級の一部として扱う必要があります。
3層モデル
うまく機能するチームパイプラインには3つの層があります。
- ローカルのプリコミット — 開発者はプッシュ前に
/reviewを実行します。上述のフック設定によりこれが自動化されます。この層での指摘事項は、修正コストが最も低いものです。 - CIゲート — GitHub Actionsのワークフローは、人間のレビュアーが割り当てられる前に、Claude Codeの指摘事項をPRコメントとして投稿します。人間のレビュアーは、CIレビューが通過した後（criticalな指摘事項がない場合）にのみ割り当てられます。
- 人間のレビューの焦点 — 人間のレビュアーは、Claude Codeのコメントをトリアージのガイドとして使用します。彼らの仕事は、アーキテクチャの適合性、製品の正しさ、パフォーマンスのトレードオフといった判断事項を評価することであり、タイプミスを探すためにすべての行を読み直すことではありません。
CLAUDE.mdの規約を共有する
CLAUDE.mdはエージェントのレビュー挙動の設定層です。コードと同様に扱ってください — コミットし、バージョン管理し、変更はPRでレビューしてください。チームが特定のパターンをClaude Codeがもうフラグ立てしないことに合意したら（linterでそれをカバーしているため）、CLAUDE.mdを更新すれば、その変更は今後のすべてのレビューに適用されます。
重大度のしきい値を調整する
チームは、初期段階ではデフォルトの重大度の調整がノイズが多すぎると感じることがよくあります。それを制御するためにCLAUDE.mdに明示的な指示を追加してください。
## Review Severity Rules
- Only flag console.log as a warning if it is in a non-test, non-debug file.
- Import ordering is never a finding; Prettier handles it.
- Treat any hardcoded credential as critical regardless of context.
- Performance suggestions are informational only unless they affect O(n²) loops.数週間の利用後、ほとんどのチームは、エージェントの注意が実際にコードベースで重要なパターンに調整されると、ノイズのレベルが大幅に下がることに気づきます。
誤検知への対処
Claude Codeは時折、何かを誤って指摘することがあります。正しい対応は、レビュー全体を却下することではなく、そのパターンに対処するプロジェクト固有の指示をCLAUDE.mdに追加することです。時間が経つにつれ、これによりチームの実際の基準を反映した、ますます正確でプロジェクト固有のレビュー設定が作られていきます。
ローカルインストールなしでClaude Codeレビューを実行する
ここまで説明したことはすべて、ターミナルでClaude Codeがインストールされ動作していることを前提としています。多くのチーム — 特にロックダウンされた企業のマシンを使用している、WSLのないWindows環境である、あるいはブラウザタブからレビューしたい開発者にとって — ローカルインストールは摩擦点となります。
Happycapyは、ブラウザ内で直接Claude Codeを安全なクラウドサンドボックス上で実行します。ファイル横断的なコンテキスト読み込み、CLAUDE.mdサポート、/reviewコマンドを含む、フルのエージェント型レビュー機能を、何もインストールせずに利用できます。これは特に以下の場合に有用です。
- ブランチをローカルにプルすることなく、ブラウザからプルリクエストをコードレビューする
- 共有された一貫性のある環境をローカルインストール展開前に求める、Claude Codeレビューに移行するチーム
- グローバルなnpmパッケージのインストールにIT部門の承認が必要な、ロックダウンされたマシン
- リポジトリ全体をクローンせずにエージェントのコンテキスト読み込みを利用したい、不慣れなリポジトリのレビュー
Claude Codeがエージェント能力の面で代替ツールとどう比較されるか気になる場合は、Claude Code vs. GitHub CopilotやClaude Code vs. Cursorをご覧ください。また、Happycapyがブラウザコンテキストでどのようにclaude Codeを実行しているか理解したい場合は、ブラウザ上のClaude Codeでアーキテクチャを解説しています。
よくある質問
Q: Claude Codeレビューはどんな言語でも動作しますか？
はい。Claude Codeは言語に依存しません — テキストベースのdiffであれば何でも読み、その中に含まれるコードについて推論を適用します。Python、TypeScript、JavaScript、Go、Rust（トレーニングデータでの表現量が多い言語）で最も精度が高い傾向がありますが、Ruby、Java、C#、その他ほとんどの主流言語でも有用な指摘事項を出します。ドメイン固有の言語や珍しいフレームワークについては、CLAUDE.mdにコンテキストを追加することで出力の精度が大幅に向上します。
Q: /reviewは、チャットでClaudeにdiffを見てもらうよう頼むのとどう違いますか？
主な違いはエージェント型のツール使用とリポジトリのコンテキストです。チャットでは、Claudeは貼り付けられたものしか見えません。Claude Codeの/reviewコマンドは、エージェントがファイルを開き、importをたどり、テストを確認し、プロジェクトの規約を読むことを可能にし、抜粋ではなく実際のコードベースに基づいた指摘事項を生み出します。大規模あるいは相互に関連する変更では、この違いは非常に大きくなります。
Q: Claude Codeレビューはセキュリティ脆弱性を捕捉しますか？
SQLインジェクション、XSS、CSRFの欠陥、安全でない直接オブジェクト参照、ハードコードされたシークレット、入力サニタイズの欠落といった、よく知られた脆弱性クラスは確実に捕捉します。デプロイ環境の理解を必要とする新しい、アプリケーション固有の攻撃ベクトルに対しては、それほど信頼性が高くありません。これは徹底的な一次セキュリティスキャンとして扱い、侵入テストの代替とは考えないでください。
Q: linterがすでに処理している内容をレビューがフラグ立てするのを止めるにはどうすればいいですか？
CLAUDE.mdに明示的な除外事項を追加してください。「import順序をフラグ立てしないでください — isortがこれを処理します」や「末尾の空白をフラグ立てしないでください — Prettierが強制します」といった具合です。ほとんどのチームは2〜3週間の利用でこのリストを構築し、シグナル対ノイズ比が劇的に改善することに気づきます。
Q: 複数言語のモノレポでClaude Codeレビューを使用できますか？
はい。パス引数や、変更したサブディレクトリのみをカバーするgit diff範囲でレビューの範囲を絞ることができます。また、CLAUDE.mdに言語固有のレビューセクションを維持し、エージェントがコンテキスト読み込みの一部としてそれを読むようにすることもできます。
Q: diffが非常に大きい場合 — 例えば3,000行のPRの場合はどうなりますか？
非常に大きなdiffの場合は、2パスのアプローチを検討してください。まずcriticalとwarningの指摘事項のみを依頼し（suggestionなし）、それをトリアージした後、特定のファイルやサブシステムについて完全な分析を依頼します。極めて大規模なリファクタリングについては、PRを分割することがより良い解決策です — 人間とAIどちらのレビューアビリティにとってもです。
Q: レビュー出力は決定論的ですか？2回実行しても同じ指摘事項が得られますか？
いいえ — 他のすべての大規模言語モデルの出力と同様に、実行間でばらつきがあります。重要性の高いレビューでは、コマンドを2回実行して指摘事項を比較するのが妥当なプラクティスです。ほとんどのcriticalな指摘事項は一貫して現れますが、軽微な提案はよりばらつきがあります。（ワークフローで設定可能であれば）より低いtemperatureを使用する、あるいはより指示的なプロンプトを使用することで、ばらつきが減少します。
Q: Claude Codeレビューは既存のlinterや静的解析ツールとどう連携しますか？
それらを置き換えるのではなく、補完します。linterは強制されたスタイルルールを機械的かつ高速に捕捉します。Claude Codeはセマンティックな理解を加えます — 関数が_正しいことをしているか_を評価できるのは、どのlinterにもできないことです。理想的なパイプラインは両方を実行します。プリコミットフックでlinter（高速、決定論的）、CIでClaude Codeレビュー（低速、セマンティック）です。/reviewコマンドはlinterの設定を認識しており、ツールがすでに生成している指摘事項を重複させないようにします。
Q: SlackやチケットへのポストのためにレビューOutput出力のフォーマットをカスタマイズできますか？
はい。エージェントに、JSON、Markdown、あるいはチームのPRコメントスタイルに合ったテンプレートなど、特定のフォーマットで指摘事項を出力するようプロンプトできます。これをフックシステムと小さなシェルスクリプトと組み合わせれば、チームが指摘事項を追跡する場所ならどこにでも構造化された指摘事項を投稿する、完全に自動化されたレビューパイプラインが完成します。
関連: Claude Code hooks徹底解説 — レビューを超えて、プリコミットチェック、lint、カスタムワークフローを自動化する。
