Claude Codeでのコードレビュー：本番投入前にバグを捕捉する

Claude Code Reviewとは？

Claude Code Reviewは、リポジトリのコンテキストでPRを精査し、潜在的なバグ、セキュリティ問題、リグレッションを報告するマルチエージェント型のコードレビューシステムです。GitHub Code ReviewはGitHubのPRに対してエージェントを走らせ、ローカルの /code-review は現在の差分をClaude Codeから直接レビューします。

ここで重要なのは「コンテキスト」です。従来の差分レビューは変更行を検査します。Claudeのレビューエージェントは、リポジトリ全体の文脈でその変更を見ます。GitHubのワークフローでは、複数の専門エージェントが並行して動作し、その後に検証・重複排除・深刻度の順位付けが行われます。

例えば、pandasの10行の変更多でも、上流のdbtモデルが作るスキーマ、Snowflakeテーブルの粒度、下流ダッシュボードに埋め込まれた前提に依存し得ます。

ClaudeはPRを承認も拒否もしません。GitHub Code Reviewは中立のチェック結論を報告するため、独自にチェック出力を使ったCIロジックを構築しない限り、既存のブランチ保護ルールは変わりません。

3つのレビュー面

現在、Claude Codeでコードをレビューする主な方法は3つあります。

ローカルの /code-review コマンドは、ブランチのコミットを検査します。特定のファイル、ブランチ、PR番号、Gitの参照範囲を指定することもできます。

GitHub Code ReviewはPR中心の設計です。リポジトリ設定に応じて、PR作成後に一度、プッシュのたび、または @claude review で依頼されたときだけレビューします。

/code-review ultra はより重量級の選択肢です。Anthropicはこの機能をultrareviewと呼び、アカウントに機能が有効なら /ultrareview というエイリアスも動作します。リモートサンドボックスで多数のレビュアーエージェントを走らせ、報告される各バグは掲載前に再現・検証されます。現在はリサーチプレビューで、通常5〜10分程度かかります。

Claudeがフラグするもの／スキップするもの

Claude Code Reviewはまず正しさに焦点を当てます。Anthropicのドキュメントでは、本番に影響するバグと、整形の好みやテスト不足を明確に区別しています。

指摘の深刻度は3段階です。

この区別は有用です。データサイエンティストは、どこにレビュー時間を割くべきか意見が分かれがちだからです。revenue_df と weekly_revenue の命名提案は、多対多結合が変換に紛れ込んで売上を2倍にしてしまうのとは別物です。

Claude Codeでコードレビューを設定するには？

Claude Code Reviewの設定手順は、ローカルレビューかGitHubのPRレビューかで異なります。ローカルの /code-review はGitHubアプリ不要で、PRを開く前に実行できます。

GitHub Code Reviewには、組織のオーナーまたはプライマリオーナーがClaude GitHubアプリを設定し、対象リポジトリを選ぶ必要があります。PRレビューを行う場合は、レビュー専用のルールを記述する REVIEW.md を作成しておくとよいでしょう。

CLAUDE.md と REVIEW.md

CLAUDE.md と REVIEW.md は目的が異なり、混在させるとノイズの多いレビューにつながりやすくなります。

CLAUDE.md はClaudeが各タスクで参照する一般的なプロジェクトの指示を含みます。コードレビューもこれを読み、新たに導入された違反はNitとして報告されます。これに対して REVIEW.md はレビュー専用で、チームとして何をフラグし、スキップし、Importantとして扱うかをレビューエージェントに伝えます。

Pythonのデータ系リポジトリであれば、CLAUDE.md にはリポジトリ構成、pytest の実行方法、変換に pandas か polars を使うか、SQLモデルの配置などを中心に書きます。

レビューのルールは REVIEW.md に記載します。例として：

• 「新しい変換には対応するテストがあるかチェックする」
• 「資格情報をログに出力しない」
• 「生成ファイルはスキップする」

小さな REVIEW.md の例は次のようになります。

# Review instructions

## Important findings

Report as Important:
- Incorrect joins or filters that can change dataset grain
- Missing tenant or customer scoping
- Secrets or credentials written to logs
- Silent changes to revenue or customer metrics

## Do not report
- Formatting already enforced by Ruff
- Generated files
- *.lock files

## Always check
- New transformations have tests
- Joins use the intended keys
- Datetime operations specify timezone assumptions
- Missing values are handled explicitly

REVIEW.md は絞り込むことをおすすめします。長すぎる指示は重要なルールを埋もれさせます。現行の実装ではこのファイルは素の指示として読まれるため、@ のショートカットではなく、ルールを直接書き込んでください。

なお、ローカル開発時の /code-review は REVIEW.md を読みません。CLAUDE.md に従い、GitHub Code Reviewのパイプラインがレビュー専用の指示として REVIEW.md を使います。

ローカルとGitHubで同じレビュー規則を使いたい場合は、一般ルールを CLAUDE.md に、レビュー専用ルールを必要に応じて REVIEW.md に重ねて記述してください。

詳しくは、最良のCLAUDE.mdを書くためのガイド をご覧ください。

GitHubアプリとトリガーモード

GitHub Code Reviewは、組織のオーナー／プライマリオーナーがClaudeの管理設定から構成します。管理者はClaude GitHubアプリをインストールしてリポジトリへのアクセス権を付与し、レビュー対象リポジトリを選び、各リポジトリにレビュー動作を割り当てます。

トリガーモードは3種類あります。

3つすべてに共通の例外：Claudeはフォークからのプルリクエストを自動ではレビューしません。誰かが @claude review とコメントする必要があります。

2026年7月のアップデート以降、手動コマンドは次のように変更されました。

• @claude review は単発のレビューを開始し、以後のプッシュには自動登録しません。

• @claude review always はレビューを開始し、以後のプッシュでも自動レビューするようPRを購読します。

• @claude review once は素のコマンドと同じ動作です。

2026年初頭にClaude Code Reviewを学んだ場合、古いチュートリアルでは @claude review で以後も自動レビューされると説明しているかもしれませんが、この挙動は2026年7月に変更され、2026年9月時点でも有効です。

組織のGitHub Code ReviewにアクセスできないPro/Maxユーザーは、アプリを使わずにローカルの /code-review と、より深いレビュー用の /code-review ultra を利用できます。

ローカルで/code-reviewを使って差分をレビューするには？

ローカルの /code-review は、PRを開く前に現在のブランチをレビューします。私は必ずここから始め、作業中に問題を捕捉してCI失敗を防ぎます。

レビュー対象のケース

ECのリポジトリに、order_id、customer_id、order_date、status、revenue を持つ受注テーブルがあり、週次売上を計算する weekly_revenue.py を作るとします。

orders = load_orders()
customers = load_customers()

# Derive the reporting week from the order date
orders["week"] = orders["order_date"].dt.to_period("W").dt.start_time

weekly_revenue = (
    orders
    .merge(customers, on="customer_id", how="inner")
    .groupby("week", as_index=False)["revenue"]
    .sum()
)

一見、変なところはありません。merge() は明示的で、グルーピングは読みやすく、結合後に売上を集計しています。

問題は、顧客テーブルに一部の顧客について履歴レコードが複数あることです。2件の履歴を持つ顧客は、結合後に2行になり、その顧客に紐づく売上が倍増します。これは、テーブルの粒度を確認せずにローカルで変換コードを読むと見落としがちなバグです。

差分のスコープを絞る

Claude Codeのセッションから /code-review を実行します。

このコマンドは、上流ブランチに対して先行している現在ブランチのコミットと未コミットの変更をレビューします。特定のファイル、ブランチ、PR、または main...feature/weekly-revenue のような範囲を指定することもできます。

例：

/code-review weekly_revenue.py

または：

/code-review main...feature/weekly-revenue

また、/code-review high のように労力レベルも渡せます。low と medium では確度の高い指摘のみを報告し、high〜max ではカバレッジが広がる代わりに、偽陽性の可能性も増えます。

フラグでレビューを調整する

ワークフローに慣れてきたら、次の2つのフラグが便利です。

• --fix は、レビュー後に指摘を作業ツリーへ適用します。

• --comment は、指摘をインラインコメントとして投稿します。

Claudeはレビューをバックグラウンドのサブエージェントとして実行するため、処理中も作業を続けられます。結果は完了後にセッションへ戻ってきます。

レビューは次のように報告するかもしれません。

🔴 Important
weekly_revenue.py:9

The merge on customer_id can duplicate order rows because
customers contains multiple records per customer. This can
inflate revenue when a customer has more than one matching
customer record.

Verify that customer_id is unique in customers or join against
the intended current-record subset before aggregating revenue.

レビューは具体的な失敗パターンを見つけ、実際のスキーマで検証できる材料を与えてくれます。Claudeの判断を鵜呑みにする必要はありません。

指摘を読む

/code-review --fix を走らせる前に、まずは手動で一通り確認します。customers を構築しているコードを探し、一意制約を確認し、weekly_revenue.py 周りのテストを見ます。

customers.customer_id が本当に一意なら、Claudeの指摘は偽陽性です。もしテーブルが顧客×有効日ごとに1行であれば、指摘は正しく、変換を修正すべきです。

重要なのは、Claudeのレビュアーはコードの挙動を見ており、データが何を表すかの知識は依然として自分の責任だという点です。

レビュー後に調査を依頼することもできます。

Investigate the customer_id join finding.
Check how the customers table is built and determine whether
customer_id is unique at the point of this merge. Do not modify
the code yet.

この2段階目は、コメントを盲目的に修正させるより有用なことが多いです。レビューをコード生成ではなく、簡潔な調査に変えてくれます。

GitHubのPRでClaude Code Reviewを実行するには？

GitHub Code Reviewは、Claudeの指摘をPRに直接投稿するため、レビュアーは変更コードの横で問題を確認できます。

順序が重要です。レビューは既存のPRに紐づくため、次の流れになります。

1. git push で weekly-revenue ブランチをGitHubへプッシュ。

2. プルリクエストを作成。ClaudeはオープンなPRしかレビューできないため、それ以前は何も起きません。

3. 自動トリガー設定なら自動で開始。手動設定なら、PRのトップレベルコメントとして @claude review を投稿して開始します。

ここでつまずきやすい要件が3つあります。コマンドはトップレベルのPRコメントである必要があり、インラインレビューコメントへの返信では機能しません。また、リポジトリへのwrite/maintain/admin権限が必要です。さらに、コマンドはコメントの先頭に書き、once や always を付ける場合は同じ行に記載します。

レビューをトリガーする

コストに効いてくる選択は、手動と自動のどちらかではなく、手動コマンドの2種類のどちらかです。

@claude review は単発レビューを実行しPRは未購読のまま、@claude review always はレビューを実行し、以後のプッシュごとに新しいレビューを開始します。

これは2026年7月以降、2026年9月時点でもの挙動です。以前は素の @claude review コマンドで自動購読されていたため、古いチュートリアルに従っている場合は注意してください。

レビューは概ね20分ほどかかりますが、Anthropicによるとコストと所要時間はPRの規模と複雑さに依存します。各レビューはプランに含まれる使用量とは別に使用クレジットで個別に課金されます。コスト構造の詳細は Claude Codeの使用制限ガイド を参照してください。

インラインコメントとチェック結果を読む

レビューが完了すると、Claudeは該当行にインラインコメントを投稿します。GitHubのチェック実行には深刻度のサマリも含まれ、weekly_revenue.py、SQLモデル、テストファイルにまたがって複数の指摘がある場合に有用です。

例：

インラインコメントでは個々の問題を調査し、チェック実行ではレビュー全体の輪郭を把握します。

なお、👍 や 👎 をクリックしても再レビューは走りませんし、インラインコメントに返信してもClaudeは反応しません。再レビューには、コードを修正してプッシュするか、新たなトップレベルPRコメントとして @claude review を投稿してください。

また、レビュー自体がマージをブロックすることはありません。チェックは中立の結論を返しますが、出力には機械判読可能な深刻度情報が含まれるため、必要なら gh と jq を使って独自のマージゲートを構築できます。

Claudeのレビューコメントをどのようにトリアージするか？

レビューサイクルでは、人間が介在し続けることが肝心です。つまり、各指摘が実バグなのか、非ブロッキングの改善なのか、偽陽性なのかを判断します。レビュアーは実装挙動を検査できても、データセットや指標のビジネス前提すべてを知っているわけではないからです。

私はシンプルな3択を使います。

この最後のカテゴリが重要です。30件の指摘を出すレビュアーが、5件の指摘のレビュアーより優れているとは限りません。pandas の結合に関する偽陽性コメントは、元の変更より時間を奪いかねません。

修正・見送り・差し戻し

重複顧客行のバグが本物なら、上流モデルを調べてから次のような修正をClaudeに依頼するでしょう。

The customer_id finding is valid. Inspect the existing customer
model and update weekly_revenue.py to join only the current
customer record. Add a regression test for a customer with
multiple historical records, then run the relevant tests.

Claudeはリポジトリを調べ、Pythonコードを変更し、テストを追加し、テストスイートを実行できます。

GitHubのレビューコメントを起点に作業したい場合、Claude Codeは GitHub CLI（gh）経由でリポジトリと対話することもできます。重要なのは、「全部直して」と投げるのではなく、有効だと判断した修正だけを選んで依頼することです。

これにより、開発者がレビューのループに残ります。

1. Claudeが問題の可能性を見つける。
2. 私がコードとデータの前提に照らして検証する。
3. Claudeが依頼した修正を行う。
4. テストを実行。
5. Claudeが結果の差分を再レビュー。

最初のレビュー出力を自動リファクタのキュー扱いにするより、このループの方がずっと安全です。

データ系PRで人間が必要なことは？

Claudeがカバーできない失敗は、「コードは正しく動くのに、やっていることが間違っている」ケースです。典型が3つあります。

• 差分外にある前提。 Claudeが読むのはリポジトリであって、データウェアハウスや設定サービス、他チームの契約ではありません。結合が正しいキーを使っていても、結果の粒度を変えてしまうことがあります。キーごとの行数は上流テーブルの属性であり、目の前のコードの属性ではないからです。

• チームだけが持つ定義。 売上を注文単位・顧客単位・週単位のどれで数えるかはビジネス上の決定です。Claudeは groupby() が与えられた行を素直に合計すると教えてくれますが、経理チームが承認する数値はどれかは教えてくれません。

• 時間と型の前提。 2026-08-27 はUTC日なのか、ローカル営業日なのか、上流モデルが定めたレポート日なのか。暗黙の型変換も同様です。object、nullable int、タイムゾーン付きdatetime、文字列列をまたぐ演算は、見かけ上もっともらしい結果を返しつつ、比較の挙動を密かに変えることがあります。

最初のカテゴリの最たる例はデータリークです。特徴量生成で、予測日以降にしか存在しない情報を含むテーブルへ訓練セットを結合してしまうことがあります。結合は正しく、行数も想定通りでも、モデルは破綻します。

そのため、私はClaudeを実装挙動のレビュアーとして扱い、定義のオーナーにはしません。

Code ReviewとUltrareviewはいつ使い分けるべきか？

素早いローカルフィードバックには /code-review、深いマージ前チェックには /code-review ultra を使います。どちらもコードをレビューしますが、/code-review は反復に最適化され、ultraは複数のリモートエージェントが独立にバグを検証します。

Anthropicは現在、ultraレビューをリサーチプレビューと位置付けています。Pro/Max加入者は一度限り無料3回分を受け取り、その後は変更規模に応じて通常$5〜$25です。Team/Enterpriseでは無料枠はなく、Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundry、Zero Data Retention有効の組織では利用不可です。

重要な違いは検証です。/code-review ultra はリポジトリの状態をリモートサンドボックスに送信し、レビュアーエージェント群を実行、報告バグを返却前に独立に再現します。

毎回のコミットで走らせるべきではありません。ノートブックの変数名変更やdbtモデルの整形調整ならローカルの /code-review で十分です。プロダクションモデルの特徴量生成ロジックの変更、売上変換の書き換え、顧客単位集計の修正などでは、追加レビューに価値があります。

名称の細かい注意点もあります。公式コマンドは /code-review ultra で、/ultrareview はアカウントで利用可能なときに動作するエイリアスです。古いチュートリアルでは /ultrareview を主コマンドとしていることがありますが、現在のドキュメントでは深いクラウドレビューは /code-review ファミリーの一部とされ、/code-review ultra はクラウド機能が使えない場合にローカルレビューへフォールバックします。

同じPRでultraレビューを実行する

リポジトリから次を実行：

/code-review ultra

GitHubのPRを直接レビューするには：

/code-review ultra <pr#>

引数なしでは、/code-review ultra は現在ブランチをデフォルトブランチと比較し、未コミット・ステージ済み変更も含めます。ブランチレビューは既定で変更ファイル約500件、変更行約8,000行に上限があります（数値は変わる可能性あり）。差分が大きすぎる場合はブランチをプッシュしてPRとしてレビューしてください。

PR番号を指定した場合、リモート環境はGitHubからPRをクローンし、あなたのマシンからは何もアップロードされません。

開始前に、Claudeはレビュー範囲、残りの無料実行回数、推定コストを表示します。確認後、レビューはバックグラウンドで走るため、リモートエージェントの実行中もClaude Codeを使い続けられます。

今回の weekly_revenue.py では、ultraの方が常に正しいと決めつけず、指摘を比較します。

もし /code-review が顧客結合をフラグし、ultraも独立に売上重複を再現したなら、その指摘への確信は高まります。ultraが上流テーブルの一意性保証を理由に無視したなら、両レビューの根拠と実際のモデル定義を確認してからコード変更します。

複数レビュアーの有益な性質は、見解が食い違うと調査材料が得られることです。

コスト面も考慮しましょう。GitHub Code Reviewは現在1回$15〜$25、ultraレビューは無料枠消化後に通常$5〜$25です。GitHub Code Reviewのコストはプランの含有使用量とは別で、Anthropicは組織向けに支出管理を提供しています。

個人で作業するなら、ローカルの /code-review に時折 /code-review ultra を組み合わせるのが良い出発点です。Team/Enterpriseで全PRに自動レビューを付けたいなら、GitHub Code Reviewが適しています。

実践的なClaude Code Reviewワークフロー

有用なのは「マージ前に毎回Claudeを走らせる」ことではありません。コストも捕捉できる問題も異なるため、開発の異なる段階でレビューを行うシーケンスです。

本番変更でのプロセスは次の通りです。

Write code
	   ↓
Run tests and data checks
	   ↓
/code-review
	   ↓
Fix verified findings
	   ↓
Open GitHub PR
	   ↓
GitHub Code Review
	   ↓
Human triage
	   ↓
/code-review ultra for higher-risk changes
	   ↓
Final tests
	   ↓
Human merge

ローカルレビューは、安価に直せる段階で問題を捕捉します。GitHubレビューはチーム全体に共有記録を提供し、ultraレビューは重大なマージ前に高コストでも確度の高いセカンドオピニオンを与えます。

データサイエンティスト向けの追加チェック

データ業務では、モデルに任せきりにせず、Claudeの周辺に次の4つを追加します。

• 重要な結合の前後で行数とデータセット粒度を確認
• 変換や特徴量ロジックの単体・結合テストを実行
• 機械学習の特徴量生成でリークをチェック
• ビジネス指標を既知の正解クエリやダッシュボードで検証

Claudeは4つすべてに関与できますが、期待する結果はClaudeの説明ではなく、コード・テスト・データから得られるべきです。

まとめ

Claude Code Reviewは、自動承認スタンプではなく、レビューに参加するもう一人のエンジニアとして扱うと最も力を発揮します。

ローカルの /code-review はPR作成前の素早いレビューを提供します。GitHub Code ReviewはTeam/EnterpriseのPRにマルチエージェントの指摘を持ち込み、/code-review ultra は重要な変更に対してより深いリモートレビューを提供します。

まずは小さく始めましょう。通常のブランチ作業に /code-review を組み込み、GitHubレビュー用に短い REVIEW.md を用意し、失敗コストの高い変更で /code-review ultra を試してみてください。

基礎となるモデル概念は、Introduction to Claude Models コースで広く学べます。GitHub Foundations と Intermediate GitHub Concepts は、Code Reviewの前提となるGit/GitHubワークフローを扱います。GitHubリポジトリのトリアージの着想を得るには、Claude Codeコネクターチュートリアル もおすすめです。