Claude Codeのコードレビューは、作業中の差分を確認する /code-review と、GitHub PRに指摘を残す @claude review で入口が分かれます。先に対象差分と修正の有無を決めると、意図しない範囲のレビューや、修正後の確認漏れを減らせます。
この記事では、ローカルで差分を確認してから、必要なPRをGitHubのCode Reviewに渡す運用を扱います。公式仕様は2026年9月9日に確認しました。コマンドや設定の説明と、この記事で提案する導入ルールを分けて記載します。
| 確認したいこと | 入口 | 本文の読む場所 |
|---|---|---|
| push前の差分と修正内容 | Claude Codeの /code-review | 次のローカルレビュー手順 |
| PRに残す指摘とレビュー基準 | GitHubの @claude review | GitHub App・REVIEW.mdの節 |
| 未完了のレビューをどう扱うか | check runの詳細と対象commit | check runの節 |
Claude Code自体の導入は Claude Code実践ガイド を参照してください。脆弱性に絞った確認は security review設計ガイド、CI失敗やPRコメントを受けた修正は Auto-Fix実践ガイド で扱います。本記事の役割は、通常のバグ・回帰レビューの対象と、指摘を受け取った後の判断を整えることです。
ローカル /code-review の対象を確認してから実行する
比較するbranchと未コミット差分を把握する
公式の ローカルレビュー仕様 では、引数なしの場合はupstreamより先のbranch commitと未コミット変更を対象にします。ローカルで起動する、という意味であり、オフライン実行を意味しません。
実行前に次を確認するのをおすすめします。
git status --short
git branch -vv
git diff --stat
git diff --cached --statたとえば作業branchのupstreamが同名のremote branchなら、引数なしの対象と、PRでmainに取り込む差分が一致するとは限りません。PRのbaseを確認し、比較範囲を明示します。以下はbaseが main、作業branchが feature-auth-session の場合の入力例です。実在するrefに置き換えてください。
/code-review main...feature-auth-sessionこの例を使った後に未コミット変更も追加した場合は、今回どの差分を見たかを結果と照合してください。レビュー済みのcommitと、その後に書いた変更を同じ扱いにしないことが運用上の要点です。
--fix を使う前に戻せる作業単位を作る
ローカルレビューは CLAUDE.md に従い、GitHub Code Review用の REVIEW.md は読みません。また、バックグラウンドで適用した --fix の編集は /rewind の対象外です。読み込む指示と編集の仕様
最初はフラグを付けずに指摘を読み、修正する範囲を選びます。--fix を使う場合は、既存作業を確認できるcommitや専用worktreeを用意してから実行する運用をおすすめします。戻す際はGitで対象の差分を特定し、自分の変更までまとめて破棄しないようにします。
同じ比較範囲に修正を適用する入力例です。上の準備と指摘の確認を済ませた場合に使います。
/code-review --fix main...feature-auth-session修正後は git diff と git diff --cached で変更を読み、対象機能のテストとプロジェクトのbuildを実行します。「指摘が出た」「修正が入った」「検証が通った」は別々に記録してください。
ローカル確認からPRレビューに渡す情報
PRへ渡す際は、少なくとも比較したref、確認したcommit、修正を採用した理由、実行した検証を残します。以下は記録用テンプレートです。実行していない検証を埋めないでください。
- 比較したref:
- 確認したcommit:
- 採用した指摘と理由:
- 見送った指摘と理由:
- 修正後に実行した検証と結果:
- 未確認の条件:深いクラウドレビューが必要かを判断する場合は Claude Code ultrareview設計ガイド、繰り返す作業手順を再利用したい場合は Claude Code Skills設計ガイド を参照してください。ここでは対象差分の確認と修正後の検証までに留めます。
GitHub PRレビューはManualから導入する
私なら、Claude Code code review は次の構成から始めます。
| 項目 | 初期設定 |
|---|---|
| 対象 repository | 重要 repo 1つだけ |
| review behavior | Manual |
| 起動方法 | @claude review |
| 継続 review | 必要な PR だけ @claude review always |
| 指示ファイル | REVIEW.md にレビュー基準を書く |
| 費用 | monthly spend cap を必ず設定 |
| merge gate | 最初は branch protection に直結しない |
理由は単純です。Code Review は research preview で、Team / Enterprise 向けの機能です。さらにレビューは token usage に基づいて課金され、PR サイズ、codebase の複雑さ、検証が必要な指摘数で費用が変わります。最初から every push にすると、レビュー品質の検証より先に費用と通知量の問題が出ます。
Manual で始めると、対象を選べます。
@claude review一回だけの確認ならこれで十分です。同じ PR を以後の push でも継続的に見たい場合だけ、次を使います。
@claude review alwaysalways は便利ですが、PR が活発に更新されるほど費用も増えます。大きな PR、外部 API、認可、請求、migration のような高リスク差分だけに使う方が安定します。
GitHub Code ReviewとActionsの担当を決める
Anthropic docs では、Code Review と Claude Code GitHub Actions は別の導線として扱われています。ここを混ぜると設計が濁ります。
| 仕組み | 主な用途 | 起動 |
|---|---|---|
| Code Review | PR の bug / regression / security finding を出す | GitHub App、review behavior、@claude review |
| GitHub Actions | issue / PR comment から実装、修正、調査、独自 automation を動かす | workflow、@claude mention、prompt |
| Routines | schedule / API / GitHub trigger で cloud 側の反復作業を走らせる | routine trigger |
| Hooks | Claude Code の tool 実行前後に local gate を置く | settings.json |
Code Review はレビュー専用 lane です。PR に inline comment や check run output を出し、既存のレビュー workflow と並走します。一方、GitHub Actions は Claude Code を runner 上で動かす汎用 automation です。実装修正や issue 対応まで任せるなら GitHub Actions、PR 差分の危険面を見たいだけなら Code Review、と分けます。
この線引きをしないと、@claude mention に「レビューして、直して、テストして、必要ならPR更新して」と詰め込みがちです。レビューは発見、修正は別の作業として分けた方が、人間が判断しやすくなります。
GitHub App の権限を先に確認する
Code Review の setup では、organization owner が Claude Code admin settings から Code Review を有効化し、Claude GitHub App を install します。公式 docs では、GitHub App が repository contents、issues、pull requests の read / write permission を要求すると説明されています。
ここで「レビューだけなのに write がある」と違和感を持つ人は正しいです。Code Review 自体は contents read と pull request write を使いますが、同じ app permission set は GitHub Actions 側の機能にも関係します。だから、組織導入では次を先に決めます。
以下は導入範囲を検討する記入例です。repository名と担当は仮のもので、製品の設定ファイルではありません。
claude_code_review_rollout:
repositories:
- name: web-app
reason: auth and billing changes are reviewed weekly
github_app_scope:
installation: selected_repositories_only
owners:
admin_owner: platform
review_policy_owner: engineering_manager
disabled_repositories:
- customer-data-export
- billing-ops-private-runbooks最初から全 repository に入れません。まず「レビュー結果に価値が出やすく、秘密情報や顧客データの露出が少ない repo」を選びます。private repo に入れる場合は、既存の GitHub App review、third-party access review、audit log review と同じ棚に載せるべきです。
@claude review / always / once を使い分ける
Manual mode では、comment command で review を起動します。
| command | 使いどころ |
|---|---|
@claude review | その時点の PR を一回だけ見る |
@claude review once | @claude review と同じ扱いで、一回だけ見る |
@claude review always | その PR を以後の push-triggered review にも載せる |
私なら、初期ルールはこのようにします。
## Claude Code Review trigger policy
- Use `@claude review` for auth, permission, payment, migration, and external API changes.
- Use `@claude review always` only when the PR is still changing and each push can introduce regression.
- Do not use `always` on docs-only, style-only, generated-output-only, or dependency-lock-only PRs.
- If a PR is split after review, trigger a new one-time review on the final smaller PR.always を濫用すると、「push するたびに AI レビューが再実行される状態」が標準になります。これは安全に見えますが、実際には費用、待ち時間、重複コメントが増えます。PR の差分が落ち着いてから @claude review を一回呼ぶ方がよい場面も多いです。
GitHub Code Review用の REVIEW.md に基準を書く
GitHub上のCode Reviewは CLAUDE.md と REVIEW.md を読めます。ローカル /code-review とは適用範囲が違います。ただし責務は違います。
| ファイル | 置くもの |
|---|---|
CLAUDE.md | project 全体の作業ルール、build command、style、禁止事項 |
REVIEW.md | review-only の観点、severity、報告形式、見ないもの |
Claude Code を普段の実装にも使っている repo では、CLAUDE.md が既に太りがちです。Code Review のためにさらに review 観点を足すと、実装時にもレビュー用の話が混ざります。レビュー専用基準は REVIEW.md に分けます。
最小構成はこれで足ります。
# REVIEW.md
Review newly introduced behavior changes only.
Prioritize:
- auth bypass
- permission escalation
- data loss
- payment or billing mistakes
- migration rollback risk
- missing tests for changed behavior
Treat severity as:
- Important: must be addressed before merge
- Nit: useful but non-blocking
- Pre-existing: not introduced by this PR
Do not comment on:
- wording preferences
- formatting covered by automated tools
- naming style unless it hides a bug
- broad architecture rewrites unrelated to the diff大事なのは「見ないもの」を書くことです。AI レビューは指摘を増やすほど価値が上がるわけではありません。人間が merge 前に判断すべき finding だけを前に出す方が、運用に残ります。
neutral checkとレビュー完了を分けて確認する
Code Review の check run は neutral conclusion で完了するため、そのまま branch protection の必須 check にしても merge を止める gate にはなりません。公式 docs では、severity breakdown を check run output から読み、自分の CI で gate したい場合に使う流れが説明されています。
neutralだけでレビュー済みと判断しない運用が必要です。公式の トラブルシューティング では、エラーやtimeoutでもneutralとなり、自動再試行されないと説明されています。
レビュー待ちのPRでは、対象commitとcheckの詳細を照合し、未完了なら人間のレビューを続けるか再実行するかを決めます。コメントがないことを「指摘なし」の根拠にせず、Detailsに結果があるか確認してください。費用上限によるskipも未レビューとして記録します。
以下は観察からCI判定へ進める運用案です。製品に渡す設定ファイルではありません。
claude_code_review_gate:
phase_1:
behavior: observe_only
action: human reads inline comments and check run details
phase_2:
behavior: soft_gate
action: release owner confirms Important findings are resolved
phase_3:
behavior: custom_ci_gate
action: parse check run output and fail only on Important findingsいきなり CI gate にすると、誤検知、GitHub annotation の欠落、review timeout の扱いで詰まります。まず 2 週間ほど observe-only で運用し、Important finding が本当に merge blocker として使えるかを見ます。
spend cap は導入条件に入れる
Code Review は plan の included usage とは別に usage credits として扱われます。公式 docs では、review 平均費用の目安、review behavior による費用差、monthly spend cap、analytics dashboard が説明されています。
初期導入ではreview behaviorと一緒に上限を決めます。以下の金額と割合は検討用の仮定値で、推奨予算や製品の設定キーではありません。管理画面で実際の上限を設定してください。
claude_code_review_budget:
monthly_cap_usd: 200
default_behavior: manual
always_allowed:
- security-critical
- billing
- auth
always_requires_comment:
- why repeated review is needed
alert_when:
weekly_spend_percent: 60費用を絞りすぎると、必要な PR で review が skipped になります。逆に広げすぎると、毎 push review が標準化します。最初は小さめに始め、analytics の PRs reviewed、weekly cost、repository breakdown を見て調整します。
実務の導入手順
私なら、次の順番で入れます。
- 対象 repo を 1 つ選ぶ
- Claude GitHub App の installation scope を selected repositories にする
- review behavior は Manual にする
REVIEW.mdを置く- monthly spend cap を設定する
- auth / payment / migration PR だけ
@claude reviewする - 2 週間、Important finding の精度と費用を記録する
- 必要な repo だけ Once after PR creation へ広げる
この段階では、merge block にはしません。review finding を人間が分類し、PR author が修正するか、別 issue に送るか、no action にするかを決めます。
運用ログはこのくらいで十分です。
## Claude Code Review rollout log
- Repo:
- Review behavior:
- Spend cap:
- REVIEW.md version:
- PRs reviewed this week:
- Important findings:
- False positives:
- Skipped by spend cap:
- Decision:毎週これを見ると、「高リスク PR では役に立つが docs PR では不要」「migration では見落としを拾うが UI copy ではノイズが多い」のような判断ができます。
よくある失敗
いきなり every push にする
PR が動くたびに review が走り、費用と通知が増えます。最初は Manual で十分です。
CLAUDE.md に review 基準を詰め込む
GitHub Code Review用の基準は REVIEW.md に分けます。ローカル /code-review にも必要なルールは CLAUDE.md 側に残し、両者の適用範囲を確認します。
指摘を自動修正まで一気通貫にする
review と fix を同じ自動 lane にすると、人間が「本当に直すべき指摘か」を見る余地が減ります。最初は finding を読むだけにします。
neutral check run を gate だと思う
Code Review の check run は既存 workflow を壊さないため neutral です。merge gate にするなら、severity output を自分の CI で読む必要があります。
spend cap に到達してから気づく
cap 到達時は review が skipped されます。高リスク PR で使えなくなる方が困るので、weekly cost と repo 別平均を見ます。
PRを渡す前に確認すること
ローカルでは比較refを明示し、修正を入れたら差分と検証結果を残します。GitHubではManualで対象PRを選び、REVIEW.md と費用上限を整えます。最後に、レビューが最新commitを対象に完了したかを確認してから、人間がmergeを判断します。
Claude Code の全体導入順を整理したい場合は Claude Code の使い方 実践ガイド、PR review を Codex 側で設計する場合は Codex code review 実践ガイド、レビュー前に実行時の危険操作を止める場合は Claude Code Hooks の使い方 実践ガイド を先に読むと、review lane の責務が分かれます。