背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

一言でいうと何か

GitHub のプルリクエストを、複数のエージェントがコードベース全体のコンテキストで検査し、問題の行にインラインコメントとして結果を投稿する自動 PR レビュー機能です。ロジックエラー・セキュリティ脆弱性・壊れたエッジケース・微妙なリグレッションを探し、各エージェントが別クラスの問題を担当したうえで、検証ステップが偽陽性を除きます。結果は重大度でタグ付けされますが PR を承認/ブロックしないため、既存のレビューワークフローはそのまま使えます。CLAUDE.md や REVIEW.md で指摘内容を調整できます(研究プレビュー、Team/Enterprise 向け)。

どういう場面で役立つか

全 PR に自動でマルチエージェントのレビューを走らせ、本番を壊すバグを人間レビューの前に拾いたいとき。PR 作成時・全プッシュ時・手動、のいずれかでトリガーでき、問題の行に重大度付きコメントが付きます。

チーム独自の基準でレビューの粒度や対象を調整したいとき。REVIEW.md で「Important の定義」「nit の上限」「スキップするパス」「常にチェックする項目」などを指定できます。

GitHub App を入れずに、手元で差分をレビューしたいとき。任意のセッションで /code-review を実行すればローカルで差分をレビューでき、--comment でインライン投稿、--fix で修正適用もできます。

不要・向かないケース：Zero Data Retention が有効な組織では利用できず、対象は Team/Enterprise サブスクリプションです。Claude を自前の CI インフラで動かしたいなら GitHub Actions や GitLab CI/CD、自己ホスト GitHub なら GitHub Enterprise Server が案内されています。またレビューはマージをブロックしないため、結果でマージをゲートしたい場合はチェック実行出力を自前 CI で読み取る必要があります。コストは1レビュー平均 $15〜25 でトークン使用量課金(usage credits)なので、無制限に走らせる用途には注意します。

仕組み・トリガー・カスタマイズの実例

前提と仕組み

管理者が組織で Code Review を1回有効にしてリポジトリを選ぶと、設定に応じて PR オープン時・全プッシュ時・手動でレビューが走ります。実行時は Anthropic インフラ上で複数エージェントが並行して diff と周辺コードを分析し、検証ステップで候補を実際の挙動に照らして偽陽性を除き、重複排除して重大度でランク付けし、該当行にインラインコメント+概要を投稿します。問題が無ければ GitHub チェック実行を「問題なし」に更新します。コストは PR のサイズ・複雑さでスケールし、平均20分で完了します。結果の重大度は 🔴 Important(マージ前に直すべきバグ)・🟡 Nit(軽微だが直す価値あり)・🟣 Pre-existing(この PR で入ったのではない既存バグ)の3段階です。各コメントには 👍/👎 が既に付いており、マージ後にリアクションが収集されてレビュアーの調整に使われます(リアクションは再レビューや PR 変更を起こしません)。インラインへの返信では Claude は動かないため、対処はコードを修正してプッシュします。

チェック実行と、マージのゲート

各レビューは CI と並ぶ Claude Code Review チェック実行を作り、その Details に全結果の重大度テーブルが、Files changed タブに diff 行への注釈が出ます(注釈と重大度テーブルはインラインコメントとは独立して書かれるため、行移動でインラインが拒否されても残ります)。チェック実行は常に中立で完了しマージをブロックしないので、結果でゲートしたい場合は Details 末尾のマシン可読コメントを自前 CI で解析します。

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

これは {"normal": 2, "nit": 1, "pre_existing": 0} のような重大度別カウントの JSON を返し、normal が Important の件数です(ゼロ以外なら修正価値のあるバグを1つ以上検出)。

セットアップと手動トリガー

セットアップは管理者が claude.ai/admin-settings/claude-code の Code Review セクションから行い、Claude GitHub App を組織にインストール(Contents/Issues/Pull requests の読み書き権限を要求。Code Review 自体は contents 読み取りと pull requests 書き込みを使用)し、対象リポジトリと Review Behavior(Once after PR creation / After every push / Manual)を選びます。全プッシュでのレビューは最も回数が多くコストも高く、Manual は高トラフィックのリポジトリで PR ごとにオプトインしたい場合に向きます。設定に関わらず、2つのコメントコマンドでオンデマンド実行できます。

@claude review
@claude review once

@claude review はレビューを開始し、以降のプッシュにも購読させます。@claude review once は購読せず単発でレビューします(頻繁にプッシュする長期 PR や、動作を変えずに一度だけ第二の意見が欲しいときに便利)。どちらもトップレベルの PR コメントとして先頭にコマンドを置き、リポジトリへの Owner/Member/Collaborator 権限が必要で、PR は open である必要があります(手動トリガーはドラフト PR でも実行されます)。

CLAUDE.md と REVIEW.md でのカスタマイズ

Code Review は2つのファイルを読みます。CLAUDE.md は全タスク共通のプロジェクト指示で、Code Review はこれをコンテキストとして読み、新たに導入された違反を nit として扱います(PR が CLAUDE.md の記述を古くする変更なら、ドキュメント更新が必要とフラグします。階層の各レベルで読まれます)。REVIEW.md はレビュー専用ガイダンスで、レビューパイプラインの全エージェントのシステムプロンプトに最優先ブロックとして注入され、既定ガイダンスより優先されます(逐語貼り付けのため @ import は展開されません)。REVIEW.md では、Important の再定義、nit 件数の上限、スキップするパス/カテゴリ、リポジトリ固有の必須チェック、証拠を求める検証バー、再レビュー時の収束ルール、概要の形などを調整できます。

# レビュー指示
## ここで Important が意味するもの
Important は、動作を壊す、データをリークする、またはロールバックをブロックする結果のために予約します：不正なロジック、スコープされていないデータベースクエリ、ログまたはエラーメッセージの PII、および後方互換性のないマイグレーション。スタイル、命名、リファクタリング提案は最大でも Nit です。
## Nit をキャップする
レビューごとに最大 5 つの Nit を報告します。さらに見つけた場合は、インラインで投稿する代わりに、概要で「plus N similar items」と言います。見つけたすべてが Nit の場合、概要を「No blocking issues」で始めます。
## 報告しない
- CI が既に実装しているもの：lint、フォーマット、型エラー
- `src/gen/` の下の生成されたファイルと任意の `*.lock` ファイル
- 本番ルールを意図的に違反するテストのみのコード
## 常にチェック
- 新しい API ルートには統合テストがある
- ログ行にメールアドレス、ユーザー ID、またはリクエスト本文が含まれていない
- データベースクエリは呼び出し元のテナントにスコープされている

長い REVIEW.md は重要なルールを薄めるため、レビュー動作を変える指示に絞り、一般的なコンテキストは CLAUDE.md に残すのが推奨です。

料金と使用状況

Code Review はトークン使用量で課金され、1レビュー平均 $15〜25、PR サイズ・複雑さ・検証が要る問題数でスケールします。usage credits を通じて個別課金され、プラン内使用量にはカウントされません。トリガーの選択が総コストに効き(Once=PR ごと1回、After every push=プッシュ数で乗算、Manual=コメントされるまで無料)、どのモードでも @claude review はプッシュ購読を伴うため以降のプッシュごとに追加コストが出ます(単発なら @claude review once)。月次上限は claude.ai/admin-settings/usage で Claude Code Review サービスに設定でき、使用状況は claude.ai/analytics/code-review のダッシュボード(レビュー数・週次コスト・自動解決数・リポジトリ別内訳)で確認します(数値は監視用の推定で、正確な支出は請求書)。

ローカルで差分をレビューする

GitHub App を入れずに手元で差分を見るには、任意のセッションで /code-review を実行します。既定ではブランチのアップストリームより先のコミットと未コミット変更をカバーし、正確性バグに加えて再利用・簡素化・効率化のクリーンアップを報告します。--comment でインライン PR コメント投稿、--fix でレビュー後に修正をワーキングツリーへ適用します。努力レベルが低いほど高信頼で少数、high〜max は広カバレッジで不確実な結果も含みます。ファイルパス・PR 番号・ブランチ名・main...my-feature のような ref 範囲をターゲットに渡せます。より深いクラウドレビューは /code-review ultra --fix(第29回の ultrareview)で実行します。なおこのコマンドは v2.1.147 より前は /simplify という名前で、現在の /simplify はバグ探索なしのクリーンアップのみを行うため、バグ検出目的なら /code-review --fix を使います。

トラブルシューティングの要点

レビューはベストエフォートで、失敗時(Code review encountered an error/timed out)も中立完了でマージはブロックせず、自動再試行もされません。再実行は @claude review once か新しいプッシュで行います(Checks タブの Re-run は Code Review を再トリガーしません)。月次上限に達した場合は PR にスキップの旨がコメントされ、次の請求期間か上限引き上げで再開します。チェック実行が「問題あり」なのにインラインが見えないときは、チェック実行の Details、Files changed の注釈、レビュー本文の Additional findings(レビュー中にプッシュして現在の diff に無い行を指す結果)を確認します。

まとめ

Code Review は、複数エージェントが検証付きで PR を分析し、重大度別のインラインコメントを投稿する自動 PR レビューです(研究プレビュー、Team/Enterprise、ZDR 組織は不可)。トリガーは PR 作成時/全プッシュ時/手動で、@claude review・@claude review once でオンデマンド実行でき、CLAUDE.md(nit 扱い)と REVIEW.md(最優先で注入)で調整します。マージはブロックしないため、ゲートするならチェック実行出力を gh api で解析します。料金は1レビュー平均 $15〜25 の usage credits 課金で、GitHub App 不要のローカルレビューは /code-review で行えます。自前 CI で回すなら GitHub Actions/GitLab、という住み分けを押さえておくとよいでしょう。

次回は、関連する未執筆ページ(GitLab CI/CD、GitHub Enterprise Server、Channels、/goal、Agent SDK など)、あるいは長く保留している引き継ぎ課題(第5回欠番の補完・第1/2回の照合)に着手する予定です。

---

この記事は執筆時点の公式ドキュメントに基づいています。最新の情報は必ず公式ドキュメントをご確認ください。