メインコンテンツまでスキップ

River Review とは

River Review は、チーム固有のレビュー判断を、要件・設計・計画・差分・レポートにまたがって実行できる OSS フレームワークです。

一般的な AI レビューツールは、PR diff を主な入力として扱います。River Review はそれだけではありません。AI エージェントが実装に入る前の要件・設計・計画もレビュー対象に含め、実装後の差分・テスト・完了レポートまで一貫して確認します。

このアプローチは Context Engineering（レビュー判断に必要な文脈を構造化して LLM へ渡す設計手法）とも呼ばれます。River Review は次の 3 つを中核に据えています。

  • capability pack: AI のレビュー能力を強化するスキル / エージェント定義のまとまり。
  • Skill Registry: チームの判断基準を versioned / repo-owned な Skill として共有資産化する仕組み。
  • レビュー用エージェントとレビューチーム: レビュー専用エージェントと、観点別レビュアーを並列実行する review team。

暗黙知を versioned / repo-owned な Skill へ落とし込み、共有資産として再利用する考え方は変わりません。3 つ目の軸は、その資産を「誰がどう動かすか」を担います。

一言で言うと​

River Review は、コードだけでなく、開発の流れそのものをレビューするためのフレームワークです。

  • 要件は、目的・成功条件・スコープが明確か
  • 設計は、既存アーキテクチャや制約と整合しているか
  • 計画は、作業分割・リスク・検証方針が揃っているか
  • 差分は、要件・設計・計画から逸脱していないか
  • レポートは、判断根拠・検証結果・未解決事項を残しているか

目的​

  • 実装前に、要件・設計・計画の曖昧さを減らす
  • 実装中・実装後に、計画と差分のズレを検出する
  • テスト/リリース前の回帰やカバレッジ漏れを抑える
  • レビュー判断をチーム所有の Skill として再利用可能にする
  • AI エージェントの作業結果を、チームの基準で監査できるようにする

位置付け​

River Review は人のレビューを置き換えるものではありません。スキル化されたチェックで抜け漏れを減らし、人間は意図・責任・事業判断・チーム固有の判断へ集中できるようにします。

また、PlanGate とも役割が異なります。

  • River Review: 要件・設計・計画・差分・レポートをレビューし、問題点・リスク・不足情報を指摘する
  • PlanGate: レビュー結果や計画情報をもとに、GO / NO-GO / NEEDS_REVISION のような進行可否を判定する

つまり、River Review は レビューする、PlanGate は 止める / 通す 役割を担います。

実行モデル（誰がレビューを実行するか）​

River Review のスキルは、River Review 自身が LLM を呼ぶための設定ではなく、**AI のレビュー能力を強化する capability pack（スキル / エージェント定義）**です。実行のされ方は 3 通りあり、LLM キーが必要かどうかは「実行面」ではなくこのモデルで決まります。

  1. AI エージェント駆動（主） — Claude Code / Cursor / Codex などのエージェントがスキル（skills/agent-skills/）やサブエージェント（agents/river-review.md）を読み込み、自身のモデルでレビューを実行する。エージェント自体が LLM なので、River Review 用の LLM キーは不要。/review-local、サブエージェント委譲、Agent Skills のロードなどがこれにあたる。
  2. 機械的チェック（heuristic / モデル不要） — 正規表現などで決定論的に判定できる観点は、LLM・API キーなしで動作する。対応観点（セキュリティ系）は、secret 直書き / eval・XSS / TLS 検証無効化 / 弱いハッシュ / コマンドインジェクション / GitHub Actions のリスク。品質・テスト系は、例外の握り潰し / debugger 残し / マージコンフリクト / 型チェック抑制 / テスト欠落 / フォーカス・無効化テスト。担当は security / logging / typescript / test 系の 5 スキルで、機械的に判定できる観点は今後さらに拡張できる。
  3. ヘッドレス LLM（GitHub Action / standalone river run） — 対話エージェントがいない環境では、River Review が自前で LLM を呼んでスキルを実行する。この経路だけ LLM キー（ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_API_KEY のいずれか）が必要になる（機械的チェック (2) はキー無しでも動く）。

まとめ: 通常の AI 駆動開発ではエージェントがスキルを適用するため LLM キーは不要です。LLM キーが要るのは GitHub Action / standalone CLI のヘッドレス実行で、かつ機械的チェック以外のスキルを動かす場合だけです。

レビュー用エージェントとレビューチーム​

River Review はスキルを束ねるだけでなく、それを動かすレビュー専用エージェントを備えています。これは上の実行モデルのうち「AI エージェント駆動」を具体化したものです。

  • レビュー専用エージェント — サブエージェント定義（agents/river-review.md）として配布され、/review-local などから呼び出せる。ホストのエージェントがこの定義を読み込み、自身のモデルでレビューを実行する。
  • 観点別レビュアーの並列実行とマージ（review team） — src/lib/reviewer-orchestrator.mjs が観点別レビュアーロールを並列に走らせ、各 finding を connected-components でマージする。ロールは bug-hunter / security-scanner / test-gap / dependency-reviewer / frontend-reviewer / ci-cd-reviewer の 6 種類。--reviewers auto なら差分内容に応じてロールが選ばれる。

ここでいう「マルチエージェント」は、1 つの orchestrator が観点別レビュアーのロールを並列に動かして結果をマージする仕組みです。完全に自律した独立エージェント群ではなく、あくまで観点別レビュアーの並列実行とマージを指します。

反復ループと判定素材の critic​

River Review は、generate → review → revise の反復ループの中で review ステージを担います。

  • ループの各周回で、レビュー結果を **判定素材（findings / verdict / suggestedLoopSignal）**として返す。
  • verdict はあくまで判定素材であり、GO / NO-GO・自動承認・自動マージを主張しない。反復を続けるか止めるかの判断は caller の責務である。
  • auto-approve のような仕組みも助言であり、人間の確認（HITL）をバイパスしない。崖では人間承認を必須とし、原っぱの自律継続はマージ権限ではない。

この契約と参照実装は、反復収束の契約 と、リポジトリ内の参照エージェント（examples/loop-reference-agent/）で定義しています。

フローの繋がり​

  • Upstream: 要件・設計・ADR・計画を確認し、後続フェーズのリスクを減らす。
  • Midstream: コードやPRをレビューし、設計意図と差分の整合を保つ。
  • Downstream: テスト、QA、完了レポート、リリース準備をチェックし、回帰と品質劣化を防ぐ。

詳しくは レビュー対象と使いどころ と 上流、中流、下流 を参照してください。