Claude Code ultrareviewの使い方 — /code-review ultraの実行手順
Claude CodeのultrareviewをCLIから動かす手順を、ブランチ・PR指定、結果の投稿、非対話実行、無料枠の管理まで具体的にまとめます。
/code-review ultraを実行すると、Anthropicのインフラ上のクラウドセッションでレビューエージェントの一群が起動し、あなたのブランチかPRのバグを並行して探します。ローカルの/code-reviewと違い、報告される指摘はすべて独立に再現・検証済みです。この記事では、呼び出しから、結果のPR投稿、CIへの組み込み、無料枠を溶かさないための注意点までを扱います。
Claude Code ultrareviewは何をするコマンドか
ultrareviewはリサーチプレビュー機能で、/code-review ultraというコマンド名で呼び出します。利用できるアカウントでは/ultrareviewという別名でも同じ処理が走ります。ローカル/code-reviewとの違いは3点です。指摘の信頼度が高いこと(複数エージェントが実コードで再現・検証してから返す)、カバレッジが広いこと(大きめのエージェント群が並行して探索する)、そして手元のリソースを使わないことです。レビューはリモートのサンドボックスで完結するため、実行中も端末は空いたままです。
実行前に確認しておく3つの前提
ultrareviewはclaude.aiアカウントでの認証を必要とします。APIキーのみでサインインしている場合は/loginでclaude.ai認証を済ませてから呼び出してください。
次に、利用環境です。Amazon Bedrock・Google CloudのAgent Platform・Microsoft Foundry経由でClaude Codeを使っている場合と、Zero Data Retentionを有効化した組織では利用できません。この条件下で/code-review ultraを呼ぶと、エラーにはならず、セッション内でのローカルレビューが走ります。
最後にリポジトリの状態です。ブランチレビューにはリモートリポジトリとの正常なgit履歴が必要で、git initのあとにgit fetch <url>してFETCH_HEADをチェックアウトしたような、detached HEADだけでブランチが1つも無い状態は拒否されます。拒否文言は次のとおりです。
Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.文言どおりgit checkout -b <名前>でブランチを作れば通ります。v2.1.221より前は、この状態で全ファイルのレビューを試みてアップロードが失敗していました。
基本の実行方法 — 対象は引数で決まる
引数なしで実行すると、現在のブランチとデフォルトブランチの差分(未コミット・ステージ済みの変更を含む)がレビュー対象になります。実行前には確認ダイアログが出て、対象範囲・残っている無料枠・見積もり費用が表示されます。ブランチレビューでは対象ファイル数と変更行数も併せて表示されるので、確認してから進められます。
/code-review ultra比較先をデフォルトブランチ以外にしたいときは、ブランチ名を引数に渡します。指定したブランチがローカルに無くても、Claude Codeがoriginから取得します。コミットIDやタグも比較先にでき、その場合は指定した地点以降にブランチへ載った変更がレビュー対象です。名前を打ち間違えたときは、近いブランチ名がエラーで提案されます。
/code-review ultra developGitHubのPRをレビューしたいときはPR番号を渡します。#1234やPR 1234、貼り付けたPRのURL(現在のディレクトリのリポジトリを指すものに限る)も認識されます。PRモードでは手元の作業ツリーをアップロードせず、リモートのサンドボックスがPRを直接クローンします。対応するのはgithub.comと、Owner権限で接続済みのGitHub Enterprise Serverインスタンスです。
/code-review ultra 1234github.comのPRでは、クローンに使われるのはClaudeアカウントにつないだGitHubアカウントです。つながっていないと、起動前に次のように拒否されます。この拒否では無料枠も使用量クレジットも消費されません。
Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting)./web-setupでGitHub CLIのログインをClaudeアカウントに引き継ぐのが近道で、接続後は1分ほど置いてから再実行します。アカウントはつながっていてもリポジトリが見えない場合は、Your connected GitHub account can't see <owner>/<repo>という別の文言で止まります。多くはClaude GitHub Appが対象Ownerに入っていないか、別のGitHubアカウントがつながっているケースです。この2つのチェックはv2.1.248から入っており、それ以前は起動前の確認がありませんでした。
Claude Code v2.1.218以降では、地の文で作業内容を説明してから呼び出すこともできます。対象は引数なしの場合と同じ現在のブランチのままで、渡した文章はメモとして確認ダイアログに表示され、届いた指摘と関連付けられます。
/code-review ultra check my auth changesメモとして扱われるのは、2語以上でブランチ名やPR参照に見えない文字列だけです。1語だけならブランチ名かPR参照として読まれるため、打ち間違えたブランチ名は最も近い名前を示すエラーになります。check PR 123 againのようにPR参照と他の語が混ざった文は、どちらの意味でも起動せず、PR番号だけで再実行するか、参照を外して現在のブランチを対象にするよう促されます。
レビューが走っているあいだと完了後の動き
起動してから指摘が届くまでの流れは、次の4段階です。
起動から指摘が届くまで
- 1
確認ダイアログで承認する
対象範囲・無料枠の残り・見積もり費用が表示されます。承認するとクラウドセッションが始まり、この時点で1回分としてカウントされます。
- 2
バックグラウンドで走らせる
通常5〜10分です。待つあいだも同じセッションで作業を続けられます。PRへの投稿を選んだ場合は、レビューが終わるまでセッションを開いたままにします。
- 3
`/tasks`で様子を見る
出力にブラウザのリンクは出ないので、進み具合はここで確認します。実行中・完了済みのレビュー一覧を開き、詳細を見たり、途中で停止したりできます。停止するとクラウドセッションはアーカイブされ、途中経過の指摘は返りません。
- 4
指摘を受け取る
検証済みの指摘がファイル位置と説明付きの通知として届きます。そのままClaude Codeに修正を依頼できます。
クラウドセッションがclaude.ai側で停止・アーカイブされると、Claudeは停止されたと伝えます。セッションが削除された場合や、起動後に別のアカウント・組織へサインインし直した場合は、セッションが見つからないと伝えます。アカウントを切り替えても、レビューは元のアカウントのもとで完了していることがあります。実行中なら元のアカウントでサインインし直し、claude --resumeで会話を再開すると再接続できます。
結果をPRに投稿するまでの流れ
Claude Code v2.1.227以降、github.comのPRをレビューした場合に限り、完成した指摘を自分のGitHubアカウントからPRへ1件のプレーンコメントとして投稿できます。承認やレビューそのものではなく、コメントの末尾には「Generated by Claude Code」の注記が付きます。ブランチレビューやGitHub Enterprise ServerのPRでは、指摘はセッション内に表示されるだけです。
投稿するかどうかは実行のたびに選びます。既定は投稿しない--no-postです。対話セッションでは、起動ダイアログで「Run and post the findings to the PR as me」を選ぶか、コマンドに--postを付けて起動を先に選択しておきます。いずれの場合も投稿を最終確認するのはダイアログです。
投稿はClaude Codeの端末からではなく、レビューのセッションIDを受け取ったAnthropic APIが、つないであるGitHubアカウント経由で行います。そのため、サードパーティプロバイダーやCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを設定した環境では使えません。
対話セッションでは、指摘が届いた時点で投稿が始まります。投稿の選択はそのセッションの中にしか保存されないため、レビューが終わる前にセッションが終わると、後で会話を再開しても投稿されません。投稿が終わると、結果は次の3つのどれかで返ります。
- 投稿できた場合は、コメントへのリンクが示されます
- 同じレビューの投稿がすでにあれば、二重には投稿せず、PRへのリンクが示されます
- 失敗した場合は理由が示され、指摘は端末に残るので手で貼れます
CI・スクリプトから動かす — claude ultrareviewサブコマンド
対話セッションを開かずにCIやスクリプトからultrareviewを起動するには、claude ultrareviewサブコマンドを使います。/code-review ultraと同じレビューを起動し、完了まで待ってから指摘を標準出力に表示します。ヘルプはv2.1.287で次のように出ます。
$ claude ultrareview --help
Usage: claude ultrareview [options] [target]
Run a cloud-hosted multi-agent code review of the current branch (or a PR number
/ base branch) and print the findings
Options:
-h, --help Display help for command
--json Print the raw bugs.json payload instead of formatted
findings
--no-post Do not post the findings to the PR (the default; accepted
for parity with the /ultrareview and /code-review ultra
flags)
--post Post the finished review's findings to the PR as you (PR
targets only; one plain comment, not a review)
--timeout <minutes> Maximum minutes to wait for the review to finish
(default: 45)[target]にはPR番号や比較先ブランチを渡せます。待ち時間の上限は既定45分です。
claude ultrareview
claude ultrareview 1234
claude ultrareview origin/mainサブコマンドを実行すること自体が、マージ元が見つからない場合の全ファイルフォールバックと、課金確認への同意を兼ねるため、入力を待たずに開始します。そのかわり、Claude自身がBashツール経由でこのサブコマンドを実行した場合は、全ファイルのレビューが拒否されます。進行メッセージは標準エラー出力に流れるので、標準出力はJSONなどをそのままパースできる状態を保ちます。
| フラグ | 効果 |
|---|---|
--json | 効果整形済みでなく生のbugs.jsonをそのまま出力 |
--timeout <分> | 効果完了を待つ上限時間(既定45分) |
--post | 効果完了した指摘をPRへ1件のコメントとして投稿(github.com対象・v2.1.227以降。対象外のときはフラグを無視してその旨を表示) |
--no-post | 効果投稿しない(既定。両方付けると投稿されない) |
終了コードは、指摘の有無に関わらず完了時が0です。起動失敗、完了前の停止、クラウドセッションのエラー、タイムアウトは1、Ctrl-Cで中断したときは130になります。クラウドセッションが起動に失敗したときは、30分待たずに早めに終了し、理由を表示して1で戻ります。
サブコマンドが指摘の到着前に終わると、指摘は端末に届きません。クラウド側のレビューは走り続けている場合があります。同じコマンドを打ち直しても続きからの再開にはならず、新しいレビューが始まって、無料枠か使用量クレジットをもう1回分使います。
--postを付けた場合は、指摘を出力した直後に投稿が始まり、リンクが標準エラー出力に出ます。実行が失敗・停止・タイムアウトしたときは何も投稿されません。レビューが完了しても投稿だけ失敗したときは、理由が標準エラー出力に出て、指摘は標準出力に残ります。
v2.1.218以降はclaude -p '/code-review ultra'のように非対話セッションで直接呼ぶこともできますが、クラウドレビューを起動した時点で終了し、指摘は待ちません。課金が発生する見込みのレビューは、起動せずに止まります。CIで指摘を取りたいなら、claude ultrareviewを使います。
料金と無料枠の管理
ultrareviewは通常のプラン利用枠ではなく、使用量クレジットとして課金されるプレミアム機能です。
| プラン | 無料枠 | 超過後 |
|---|---|---|
| Pro | 無料枠3回 | 超過後使用量クレジットで課金 |
| Max | 無料枠3回 | 超過後使用量クレジットで課金 |
Pro・Maxの3回はアカウントごとに一度きりの割り当てで、時間が経っても補充されません。無料枠を使い切ると、変更の規模に応じておおよそ5〜25ドルが使用量クレジットから引かれます。
無料枠を減らすのは、クラウドセッションが起動した時点です。途中で停止したりレビューが失敗したりしても、その回は1回消費されます。有料レビューは実際に走った分だけ課金されます。逆に、起動前に拒否されたレビューは消費されません。差分が大きすぎるときの拒否と、GitHubアカウント未接続の拒否は、どちらもセッション起動より前に返ります。
使用量クレジットが有効になっていないアカウント・組織では、有料レビューの起動自体がブロックされます。請求管理の権限があれば設定画面へ案内されます。現在の設定確認や変更には/usage-creditsを使います。課金の確認は会話ごとに1回表示され、/clearで新しい会話を始めると、次の有料レビューで再度確認されます。
/code-reviewとの使い分けは、変更の重さで決める
どちらを呼ぶか
/code-review
ローカルのセッション内で数秒〜数分。エフォート引数で深さが変わります。対象は作業中の差分のほか、PR番号・ブランチ・パスも指せます。通常の利用枠に計上され、チームメイトのPRを承認前に見る用途にも向きます。
/code-review ultra
クラウドのサンドボックスで5〜10分。複数エージェントが独立に検証します。対象は作業中の差分かPRです。無料枠のあとは1回およそ5〜25ドルがかかるので、認証・課金・データ破壊に関わる変更のマージ直前に絞って使う組み合わせが無理のない運用です。
この判断軸そのものはClaude Codeコードレビューの4経路で扱っています。また、PRごとに自動で走らせたいなら、CLIの手順を挟まずに指摘をインラインコメントとして投稿するCode Reviewという別の仕組みもあります。
ultrareviewで止まる・消えるときの切り分け
- diffが大きすぎて拒否される: ブランチレビューは既定で最大500ファイル・8,000変更行までです。上限値は変わりうるため、実際のエラーメッセージに出る数値を見ます。拒否はセッション起動前なので無料枠は減りません。文言には、変更行数の多いファイルが並びます
- 差分の絞り込み方: 変更行の多くを
package-lock.jsonや生成物が占めているなら、近い比較先ブランチを渡す、または変更を小さなブランチに分けて個別にレビューします。PRも同じ上限で、PR #<N> is too large for ultrareviewという文言で止まります - マージ元が見つからない: 対象ブランチがベースと共通の履歴を持たないとき、完全なクローンだと確認できれば、リポジトリ全体を対象にしたレビューにフォールバックします。サイズ上限は通常のレビューと同じです。完全なクローンと確認できない場合は拒否され、
git fetch --unshallow originなどの案内が出ます - リポジトリの最初のコミット: 比較先が無いため、ダイアログで承認するとすべてのファイルがレビューされます。未追跡ファイルがあると拒否され、レビューしたいものを
git addするよう促されます。claude ultrareviewとclaude -pはこの確認を取れないので、対話セッションを使うよう案内されます。v2.1.277以降が必要です - 比較する差分が空: ベースとの差分が無いと、何もレビューせず終了します。ベースブランチ上にいる、ブランチのコミットがすべてベースに含まれている、といった状況に応じて、ブランチの切り替え・コミット・別ベースの指定が案内されます
- リポジトリが大きすぎてアップロードできない: ブランチをpushしてドラフトPRを作成し、PR番号を指定するPRモードに切り替えると解決します
core.ignoreCaseなどのgit設定で止まる:Not uploading this working treeで始まる文言で、ファイルをgitが保存前に変換する(暗号化するなど)設定が、アップロード側で再現できないと拒否されます。core.attributesFileとattr.treeでも同じ拒否が出ます。文言の最後に直し方が書かれているので、それに従います- 投稿したのにPRにコメントが付かない: セッションが指摘の到着前に終了すると投稿はされません。会話を再開しても後追いでは投稿されないため、投稿を選んだレビューはセッションを開いたまま待つ必要があります
公式ドキュメントの外で報告されているつまずき
anthropics/claude-codeリポジトリのissueには、無料枠が消費されたまま指摘が戻らなかった報告があります。
- issue #88595: CLIが30分の時点でクラウドレビューの失敗を宣言したが、実際にはまだ実行中だった。無料枠が消費され、指摘がCLIに届かなかった
- issue #92082: リモートタスクが空の出力で完了し、指摘が届かないまま無料枠が消費された
- issue #93661: デスクトップアプリのCodeタブから呼ぶと、ローカルのClaude Codeセッションでしか使えないというエラーになる
3件とも、issue上は未解決(Open)の報告です。終了コード1で戻ったときも、クラウド側でレビューが走り続けている場合があるため、打ち直す前にセッションの状態を見ておくと、同じレビューで無料枠を二重に使わずに済みます。
まとめ
ultrareviewは独立した検証を挟むぶん重い判断材料なので、日常の差分は/code-reviewで回し、取り返しのつきにくい変更のマージ直前に絞って使うと、一度きりの無料枠も使用量クレジットも無駄にしません。CIに入れるなら、claude ultrareviewに--timeoutと--json、PRコメントが要るなら--postを組み合わせます。呼び出し方の全体像はClaude Codeスラッシュコマンド一覧、レビュー以外のワークフローとの組み合わせ方はClaude Codeワークフローで扱っています。