「Diff is too large for ultrareview」の対処 — Claude Code
Claude Codeで「Diff is too large for ultrareview」が出たときの上限値の意味と、ベースブランチの絞り込み・分割・ローカルレビューへの切り替えによる対処を確認します。
/code-review ultraまたはclaude ultrareviewを実行すると、クラウドのレビューが始まる前に拒否されることがあります。表示されるのは「Diff is too large for ultrareview」というメッセージです。ブランチとベースブランチの差分(未コミット・ステージ済みの変更を含む)が既定の上限を超えたときに出るエラーで、クラウドセッションは1つも起動しません。拒否された時点では無料枠も消費されず、使用量クレジットの請求も発生しません。
上限値とメッセージの読み方
上限はブランチレビューで変更ファイル数500・変更行数8,000です。この値は変わる可能性があり、エラーメッセージ自体がそのとき有効な上限値と、あなたの差分の実サイズ、そして変更行数が多いファイル上位を名指しします。
| 項目 | 既定の上限 |
|---|---|
| 変更ファイル数 | 既定の上限500 |
| 変更行数 | 既定の上限8,000 |
実際のメッセージは次のような形です。
Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.上位ファイルの内訳が出るのはブランチレビューの場合だけです。プルリクエストをレビューする形で同じ上限に触れると、メッセージは「PR #<N> is too large for ultrareview」で始まります。そのPRのファイル数と行数は名指ししますが、ファイル別の内訳は出ません。v2.1.216より前は、このメッセージは生の差分統計だけを表示しており、上限値や寄与ファイルの情報はありませんでした。
ベースブランチを近づけて再実行する
差分は現在のブランチとベースブランチの間で計算されます。既定のベースが遠く、無関係な変更まで差分に含まれているなら、近いブランチを明示的に渡すだけで上限内に収まることがあります。
/code-review ultra developベースブランチはローカルクローンに存在している必要はありません。Claude Codeがoriginから取得します。名前を打ち間違えた場合は、最も近い候補のブランチ名をエラーの中で提案します。非対話環境でclaude ultrareviewサブコマンドを使う場合も同じ絞り込みが効きます。
claude ultrareview develop --jsonこのサブコマンドは所見をstdoutに出力し、成功時は終了コード0、失敗時は1を返します。--timeout <minutes>で既定の30分から変更できます。ベースを近づけても上限を超える場合は、次の分割かローカルレビューへの切り替えを検討します。
変更を分割する
メッセージが名指しする「変更行数が多いファイル」は、しばしばレビューの本質とは無関係です。上の例ではpackage-lock.jsonとdist/bundle.jsが合計6万行を占めています。これらのような自動生成ファイル・ロックファイル・ビルド成果物を実装差分とは別のコミットやブランチに分けるだけで、残りの差分が上限内に収まることがよくあります。
生成物を切り離せない場合は、機能単位でブランチを分割し、それぞれを個別にレビューします。ultrareviewは1回のクラウドセッションで完結する設計のため、分割レビューを1本のPRにまとめて再統合すること自体は問題になりません。
上限のないローカル/code-reviewに切り替える
ultrareviewは大きめの変更を深く検証する分だけコストがかかります。無料枠(Pro・Maxで3回)を使い切った後は、使用量クレジットとして1回あたりおおむね5〜25ドルが請求されます。差分が大きすぎて何度も分割し直すくらいなら、引数なしの/code-reviewに切り替える方が早いことがあります。
ローカルの/code-reviewにはultrareviewと同じファイル数・行数の上限がありません。深さはlowからmaxまでの実行レベルで調整する設計で、レベルを上げるほど所要時間は伸びますが、対象の差分サイズそのものに上限はかかりません。数十秒から数分で終わる分、精度はultrareviewの多エージェント検証には及びませんが、レビューを完走できないよりは有効です。
/code-review high大きな変更を確実に検証したい場面では、2段階の使い方も選択肢になります。まずローカルの/code-review highで粗く洗って指摘を潰し、そのうえでベースブランチを絞ってultrareviewに回します。レビュー経路の全体像はClaude Codeコードレビュー — 4つの実行経路の使い分けにまとめています。
なぜこの規模の上限が引かれているのか
ローカルの/code-reviewと違い、ultrareviewは複数のレビューエージェントを並列に走らせ、報告する所見をそれぞれ独立に再現・検証したうえで返す設計です。差分が大きくなるほど、フリート内の各エージェントが検証すべき範囲は広がり、独立検証にかかる時間もサンドボックスの負荷も比例して増えます。500ファイル・8,000行という値は、その独立検証をおおむね5〜10分という所要時間の枠に収めるための実務的な線引きだと考えられます。検証の深さを保ったまま対象範囲だけを無制限に広げることはできない、という設計上のトレードオフが上限の背景にあります。
上限内でも起動前にコストと範囲を確認できる
差分が上限内に収まっている通常のケースでも、ultrareviewはクラウドセッションを起動する直前に確認ダイアログを表示します。ブランチレビューであれば対象のファイル数・行数、残っている無料枠の回数、見積もりコストが並びます。この確認は差分が大きいほど見積もりコストも上がるため、上限ぎりぎりの差分を無理に通そうとする前に、そもそも1回のレビューに見合う変更量かどうかを見直す材料にもなります。確認は会話ごとに1回求められる仕組みで、/clearで新しい会話を始めると次の有料レビューで再び確認が出ます。
変更行数を減らす具体的なテクニック
上限に近づきやすい原因は多くの場合、実装そのものより付随して変わる大きなファイルです。再実行のたびに手探りで削るより、事前に把握しておくと早く収まります。
- レビュー前に
git diff --stat <base>...HEADを実行し、変更行数の多いファイルを自分で先に確認する - ロックファイル・ビルド成果物・自動生成コードは、実装の変更と別コミット・別ブランチに分ける
- 大規模なリネームやフォーマッタの一括適用は、機能変更と混ぜずに単独のコミットにする(diffの計算はコミット単位でなく差分全体に対して行われるため、混ぜると同じ上限に一緒に加算される)
これらは差分そのものを小さくする工夫であり、ベースブランチを変える対処(前節)と組み合わせて使えます。
PRモードは同じ上限でも内訳の出方が違う
ブランチレビューはリポジトリの状態をバンドルしてリモートサンドボックスにアップロードするため、Claude Codeが差分の中身まで検査してファイル別の内訳を出せます。一方、PR番号を渡すPRモードではリモートサンドボックスがGitHub側から直接プルリクエストをクローンし、ローカルの作業ツリーは何もアップロードしません。同じ上限が適用されるのに、拒否メッセージがファイル数と行数だけで内訳を出さないのはこの経路の違いによるものです。PRのどのファイルが行数を押し上げているか分からないときは、ローカルでブランチとしてチェックアウトし直し、ブランチレビューの形でメッセージの内訳を確認するのが早い方法です。
ultrareviewが他のワークフロー機能とどう組み合わさるかはClaude Codeワークフロー — Ultraplan/Ultrareview/Checkpointingで扱っています。上限値やレビュー経路は今後の更新で変わる可能性があります。変更履歴はClaude Code v2.1.216 — サンドボックス分離を外す設定を追加し、無人と並列運用の不具合を修正のようなリリースノートでも追えます。
よくある質問
上限に触れてもレビューは失敗としてカウントされますか
されません。クラウドセッションが始まる前の拒否なので、無料枠は消費されず使用量クレジットも発生しません。安心して何度でも条件を変えて再実行できます。
/code-review ultraとclaude ultrareviewで上限は違いますか
違いません。どちらも同じファイル数・行数の上限を参照します。対話セッションかCI・スクリプトかという実行形態が違うだけです。
ステージしていない変更も差分に含まれますか
含まれます。未コミットの変更とステージ済みの変更はどちらも、ブランチとベースの差分に加算されて上限判定の対象になります。レビュー前にgit statusで意図しない変更が混ざっていないか確認すると、上限超過の原因を早く特定できます。
上限の500ファイル・8,000行という値自体は変わりますか
公式ドキュメントは「既定の値であり変わる可能性がある」としています。実際に有効な値は、拒否メッセージ自体が毎回名指しするので、そこで確認するのが確実です。
何度も分割し直すのが面倒なときの最短手順は何ですか
まずgit diff --statで最も行数の多いファイルを確認し、それが自動生成物やロックファイルなら別コミットに分離します。それでも上限を超えるなら、ベースブランチを近いものに変えて範囲そのものを狭めます。両方を試しても収まらない規模なら、無理にultrareview 1回で通そうとしないのが早道です。ローカルの/code-review highで先に粗く洗ってから機能単位で分割する方が、結果的に早く終わります。
レビューを見送って通常のコードレビューだけで済ませてもいいですか
差分が上限を超えるほど大きい変更は、レビュー手段を問わず1回で検証しきるのが難しい規模です。ultrareviewの上限は「多エージェントでの深い検証にはこのくらいが妥当」という設計上の線引きでもあります。上限に触れたこと自体を、変更をレビュー可能な単位に分割するサインとして受け止めるのも一つの考え方です。