本文へ移動
Tech

Claude Code ultrareview 設計ガイド - 深いPRレビューを安全に使う

nidoneko · · 16 min read
Claude CodeコードレビューAIエージェントセキュリティAIワークフロー設計
🔎

Claude Code で PR をレビューするとき、@claude review、local の /code-review、/code-review ultra、claude ultrareview のどれを使えばよいか迷いやすいです。名前は近いですが、実務での役割は違います。特に ultrareview は、普段の小さな差分へ毎回かける道具ではなく、merge 前に「ここだけは深く見たい」と決めた変更へ使う重いレビュー lane です。

この記事では、Claude Code ultrareview を重要 PR の深い pre-merge 確認として使う設計に絞ります。GitHub App で @claude review や REVIEW.md を運用する話は Claude Code code review 実践ガイド、issue や PR comment から実装を動かす話は Claude Code GitHub Actions 設計ガイド、Claude Code 全体の導入順は Claude Code の使い方 実践ガイド、Codex 側で差分を受け入れる前の確認は Codex レビュー完了ゲート設計ガイド に分けています。

今回の論点は、どの差分を ultrareview に出し、どの結果を merge 判断へ使い、どこで人間へ戻すかです。

先に結論: ultrareview は「普段使いのレビュー」ではなく深掘り枠

私なら、Claude Code のレビュー入口を次のように分けます。

目的使う入口判断
作業中に早く feedback が欲しい/code-reviewlocal session で短く回す
PR に通常の AI review finding を出したいCode Review / @claude reviewGitHub App のレビュー lane
大きめの変更を merge 前に深く見たい/code-review ultracloud sandbox の深掘り review
CI や script から深い review を待ちたいclaude ultrareviewnon-interactive lane

ultrareview は、Claude Code on the web の infrastructure 上で動く深い code review です。公式 docs では、local /code-review より広い reviewer fleet と独立検証を使い、通常の local review では見落としやすい bug を探すものとして説明されています。

だから、最初の設計は単純です。

claude_ultrareview_policy:
  default: do_not_run
  use_when:
    - auth_or_permission_change
    - payment_or_billing_change
    - migration_or_data_rewrite
    - security_boundary_change
    - large_refactor_before_merge
  avoid_when:
    - docs_only
    - copy_only
    - generated_files_only
    - formatter_or_lint_only

「全 PR に深い review をかける」ではなく、「深い review が必要な PR を選ぶ」方が運用に残ります。

/code-review と /code-review ultra を混ぜない

local の /code-review は、作業中の速い feedback に向いています。一方、/code-review ultra は remote sandbox で走り、時間も費用も重くなります。

項目/code-review/code-review ultra
実行場所local sessioncloud sandbox
対象working diff、PR、branch、pathworking diff または PR
速度数秒から数分目安 5〜10分
費用通常利用分free run 後は usage credits
向く場面実装中の早い確認merge 前の重要差分

実務では、まず local /code-review で雑な問題を潰します。そのあと、差分が固まった段階で ultrareview に出します。順番を逆にすると、まだ動いている PR に重い review をかけることになり、指摘も費用も増えます。

私なら、PR author へ次のような運用を置きます。

## Review order

1. Run tests and local checks.
2. Run `/code-review` if the diff is still changing.
3. Split the PR if the review surface is too large.
4. Run `/code-review ultra` only after the PR is close to merge.
5. Treat ultrareview findings as review input, not automatic merge blockers.

AI review を増やす前に、PR を小さくする方が先です。ultrareview は大きすぎる差分をごまかす装置ではありません。

branch review と PR review を使い分ける

/code-review ultra は、引数なしなら current branch と default branch の diff を見ます。

/code-review ultra

base branch を変えるなら、branch 名を渡します。

/code-review ultra develop

GitHub PR を直接見るなら、PR 番号を渡します。

/code-review ultra 1234

私なら、local branch review と PR review を次のように分けます。

状況選ぶ実行方法
まだ push 前で、手元の差分を確認したいbranch review
PR として議論中の差分を確認したいPR number
repository が大きく、bundle が厳しいdraft PR を作って PR mode
teammate の PR を merge 前に見たいPR number

公式 docs では、branch review では repository state を remote sandbox へ upload し、PR mode では remote sandbox が pull request を host から clone する形が説明されています。ここは権限設計として大事です。手元の未コミットファイルまで含めたいなら branch review、PR 上の公開された差分だけでよいなら PR mode と分けます。

差分が大きいときは PR を割る

ultrareview は、review 前に diff を確認し、対象外なら理由を返します。公式 docs では、branch review の既定上限として 500 changed files / 8,000 changed lines が示されていますが、実効値は変わり得ます。大事なのは数字を暗記することではなく、大きすぎる差分は深い review の前に分割することです。

私なら、ultrareview に出す前にこの基準で止めます。

pre_ultrareview_check:
  changed_files:
    ok: "<= 80"
    split: "> 80"
  changed_lines:
    ok: "<= 1200"
    split: "> 1200"
  generated_files:
    action: exclude_or_explain
  lockfiles:
    action: review_separately
  migrations:
    action: require_rollback_plan

公式上限より小さく置く理由は、review 結果を人間が読める状態に保つためです。8,000 行まで受け付けるから 8,000 行の PR でよい、という話ではありません。PR が大きいほど、AI も人間も「何が本質的な変更か」を見失います。

plain words は「レビュー観点メモ」として使う

Claude Code v2.1.218 以降では、/code-review ultra に短い自然文を付けられます。

/code-review ultra check my auth changes

この文は、review 対象を広げる魔法の指示ではなく、launch dialog に残るメモです。私は、次のように短く使います。

/code-review ultra focus on tenant isolation and rollback safety

避けるのは、長い prompt を付けることです。

/code-review ultra review everything, fix it, post comments, and approve if OK

これは review、fix、投稿、承認を混ぜています。ultrareview の目的は bug finding です。修正や承認は別の human gate に戻します。

--post は毎回の明示選択にする

ultrareview の結果は、GitHub PR へ plain comment として投稿できます。公式 docs では、interactive session なら launch dialog や /code-review ultra 1234 --post で投稿を選び、non-interactive な claude ultrareview では --post で投稿できると説明されています。

ただし、私は最初から --post を標準にしません。

段階投稿方針
導入初期terminal に出して人間が要約する
安定後重要 PR だけ手動で post を選ぶ
CI 化後claude ultrareview --post は限定 repo のみ

理由は、PR comment はチームの review record になるからです。未整理の AI finding をそのまま投稿すると、author は「どれを直すべきか」「誰が確認済みか」で迷います。

投稿するなら、先に triage します。

## Ultrareview triage

- Blocking:
  - [ ] finding id / file / reason
- Needs follow-up issue:
  - [ ] finding id / owner
- No action:
  - [ ] false positive / pre-existing / accepted risk

AI が見つけたことと、チームが merge 判断に使うことは別です。

claude ultrareview はCI gateではなく深掘りjobにする

script や CI から使うなら、claude ultrareview subcommand を使います。

claude ultrareview
claude ultrareview 1234
claude ultrareview origin/main

この subcommand は remote review が終わるまで待ち、結果を stdout に出します。--json、--timeout、--post、--no-post も使えます。

ただし、私はこれを最初から required check にしません。導入初期は workflow_dispatch か label 起動にします。

name: Claude Ultrareview

on:
  workflow_dispatch:
    inputs:
      pr:
        required: true
        type: string

permissions:
  contents: read
  pull-requests: read

jobs:
  ultrareview:
    runs-on: ubuntu-latest
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0
      - name: Run ultrareview
        run: claude ultrareview "${{ inputs.pr }}" --no-post --timeout 30

この例は概念用です。実際には認証、usage credits、対象 repository、ログ保存、失敗時の扱いを組織ごとに決めます。特に、paid review の確認や usage credits 設定が必要な場合、interactive な /code-review ultra と non-interactive subcommand では挙動が違います。

CI での判定は、最初はこうします。

ultrareview_gate:
  required_check: false
  trigger: manual_dispatch
  output:
    store: private_artifact
    post_to_pr: false
  human_decision:
    required_for:
      - blocking_findings
      - inconclusive_review
      - timeout

「AI review が成功したから merge 可」ではありません。成功は、読める finding が返ったという意味に留めます。

usage credits と free runs を導入条件に入れる

ultrareview は premium feature です。公式 docs では、Pro / Max に 3 free runs があり、それ以降は usage credits、Team / Enterprise は free run なしで usage credits と説明されています。費用は変更サイズに応じて変わり、通常は review 前の dialog に見積もりが出ます。

導入前に、費用の扱いを決めます。

ultrareview_budget:
  owner: engineering_manager
  allowed_repositories:
    - payment-api
    - identity-service
  monthly_review_limit:
    payment-api: 6
    identity-service: 4
  requires_reason:
    - "Why local /code-review is not enough"
    - "What merge decision this review supports"
  stop_when:
    - usage_credits_disabled
    - expected_cost_unknown
    - pr_is_still_churning

費用上限を決めないまま「重要そうな PR だから回す」と始めると、いつの間にか重い review が日常化します。free run は検証用であって、運用設計の代わりではありません。

結果は finding ではなく decision packet にする

ultrareview が返す finding は、そのまま merge 判断ではありません。私は、最後に decision packet へ変換します。

## Ultrareview decision packet

- Target:
- Command:
- Scope:
- Cost estimate:
- Review completed:
- Blocking findings:
- Non-blocking findings:
- False positives:
- Human decision:
- Follow-up owner:
- Merge condition:

この形式にすると、review 結果、費用、scope、人間判断が1か所に残ります。PR comment に投稿する場合も、この packet を添えると、AI が出した finding とチームの判断が分かれます。

特に重要なのは Merge condition です。

Merge condition:
- Fix finding U-3 before merge.
- Open follow-up issue for U-5.
- No action on U-8 because it is pre-existing and covered by existing test debt issue.

ultrareview の価値は「たくさん指摘すること」ではありません。merge 前に人間が見落としやすい bug を、判断できる形にして返すことです。

使わない方がよい場面

ultrareview を使わない判断も、運用ルールに入れます。

場面理由
docs / copy だけの PR深い bug review の価値が薄い
formatter / generated file だけCI と差分確認で足りる
まだ設計が揺れている PRreview 結果がすぐ古くなる
巨大 refactor の途中先に分割すべき
secret や未公開設定が手元に多い branch reviewPR mode へ寄せる

AI review は、使わない判断ができて初めて実務に入ります。毎回使うなら、レビュー基準ではなく儀式になります。

実務の導入手順

私なら、導入は3段階にします。

  1. 個人利用で /code-review ultra を 2〜3 回試す
  2. 重要 PR だけ PR number 指定で実行する
  3. claude ultrareview を manual workflow に入れる

最初の2週間は、次を記録します。

## Ultrareview rollout log

- PR:
- Reason:
- Command:
- Duration:
- Cost:
- Findings:
- False positives:
- Action taken:
- Would run again:

Would run again が半分を切るなら、対象選定が広すぎます。auth、permission、billing、migration、security boundary のような high-risk PR へ絞り直します。

まとめ

Claude Code ultrareview は、通常の code review を置き換えるものではありません。普段の実装中 feedback は /code-review、PR 上の通常 review は Code Review / @claude review、深い pre-merge 確認だけを /code-review ultra や claude ultrareview に寄せるのが安全です。

大事なのは、使う前に対象、費用、投稿、merge 判断を決めることです。PR がまだ揺れているなら local review で十分です。差分が固まり、auth、permission、billing、migration のような失敗コストが高いときだけ、ultrareview を深掘り枠として使います。

参考

WRITTEN BY nidoneko

Full-stack engineer with 8+ years of experience in TypeScript, React, Node.js, and cloud-native development across healthcare, finance, HR, and IoT domains.

View Profile →
// Related articles View All
🔀
Jev

Jevとは？TypeSafe AIの判断モデルとLLMの違い・使いどころ

·17 min read

TypeSafe AIのJevは、選択・評価・Yes/Noの判断を確率付きで返すモデルです。Structured Outputsとの違い、confidenceの意味、問い合わせ分類の実装例、速度・価格の評価条件を整理します。

Read More →
🔋
Codex

Codex usage reset 設計ガイド - banked reset・paid reset・creditsを混同しない

·16 min read

Codex の利用上限に達したとき、banked reset、paid weekly reset、credits、Luna Reserve、通常の自動リセットをどう使い分けるかを整理します。

Read More →
🔎
Codex

Codex web search 設計ガイド - cached / live / disabled を安全に切り替える

·16 min read

Codex CLI / IDE extension の web search を、cached / indexed / live / disabled のどれで使うべきか整理します。`--search`、`web_search`、prompt injection、evidence packet、profile分離まで実務目線で解説します。

Read More →