AIコードレビューはPRだけ見ていていいのか？ 開発の流れ全体をレビューするOSS「River Review」を作った
AIエージェントを使うと、実装速度はかなり上がります。
Claude Code、Codex、GitHub Copilot などを使っていると、以前なら半日かかっていた実装が数十分で形になることもあります。これはかなり大きな変化です。
一方で、実務で使うほど別の問題も目立つようになりました。
- 実装は速いが、設計意図から少しずつズレる
- PRレビューが「差分の指摘」に寄りすぎる
- テスト観点や運用リスクが後回しになる
- レビューで得た知見が次回に活かされない
- AIに同じ指摘を何度もしている
AIによってコードを書く速度が上がるほど、レビューは単なるチェックではなく、開発全体を支える仕組みである必要があります。
そこで作っているのが River Review です。
River Review は、PR差分だけを見るのではなく、要件・設計・実装・テスト・運用という開発の流れ全体をレビュー対象にする OSS のAIレビューフレームワークです。
この記事で伝えたいこと
この記事で伝えたいことは1つです。
AIコードレビューは、PRの差分だけを見ていても足りない ということです。
もちろん、PR差分レビューは重要です。バグ、型の不整合、セキュリティ上の問題、不要な変更などを見つけるには有効です。
ただ、AI開発では実装速度が上がるぶん、次のようなズレも起きやすくなります。
- そもそも要件と合っていない
- 設計方針と違う方向に進んでいる
- 既存のADRやチームルールを無視している
- テストが実装の勢いに追いついていない
- リリース後の運用リスクが見落とされている
これは「コード差分だけを見れば解ける問題」ではありません。
開発の上流から下流まで、流れ全体を見る必要があります。
なぜ River Review を作ったのか
AIコーディングによって、実装そのものは速くなりました。
しかし、自分の開発フローでは次のような課題が残りました。
1. レビュー観点がその場限りになる
AIにレビューを依頼すると、その場では有用な指摘をしてくれます。
ただし、次のセッションでは同じ前提を忘れます。
毎回、次のような説明をしていました。
- この領域では後方互換性を重視している
- このAPI変更ではテストケースを必ず追加する
- このリポジトリでは生成コードを直接信用しない
- 高リスクな変更では人間の確認を挟む
これはプロンプトで毎回説明するより、レビュー観点として残したほうがよいと考えました。
2. PRレビューだけでは設計のズレを拾いにくい
PR差分を見るだけだと、変更そのものは正しく見えることがあります。
しかし、要件や設計と照らすと、実は違う方向に進んでいることがあります。
たとえば、実装はきれいでも、次のような問題はPR差分だけでは見落としやすいです。
- もともとの計画にない責務が追加されている
- 別レイヤーに置くべき処理が混ざっている
- 既存の設計判断と矛盾している
- テストケースが仕様変更を十分に表現していない
AI開発では実装が速いので、このズレも速く広がります。
3. レビューコメントが資産になりにくい
レビューコメントには、チームの知識が詰まっています。
- この設計は避けるべき
- この領域は障害につながりやすい
- この変更ではテストが漏れやすい
- このパターンは過去に問題になった
しかし、多くのレビューコメントは、そのPRの中で消費されて終わります。
次のレビューでは、また同じ指摘をします。
これを、再利用できる形にしたかったというのが River Review の出発点です。
River Review とは
River Review は、開発を「流れ」として捉える AI レビュー基盤です。
コンセプトは次の通りです。
Review that Flows With You.
開発には、上流・中流・下流があります。
- Upstream: 要件、仕様、設計、計画
- Midstream: 実装、PR、コード変更
- Downstream: テスト、QA、リリース、運用
River Review は、これらを分断せず、流れとしてレビューします。
一般的なAIコードレビューが Midstream、つまりPR差分レビューに寄りやすいのに対して、River Review は Upstream / Midstream / Downstream を明示的に分けます。
これにより、レビュー観点を「今どの段階を見るべきか」に合わせて切り替えられます。
River Review の中核: Skill Registry
River Review の中心にあるのは Skill Registry です。
レビュー観点を、その場限りのプロンプトではなく、再利用可能な「スキル」として定義します。
たとえば、次のようなレビュー観点をスキル化できます。
- API変更時の後方互換性レビュー
- 認可・認証まわりのセキュリティレビュー
- テスト不足の検出
- エラーハンドリングの確認
- 設計方針やADRとの整合性チェック
- PlanGate の plan / todo / test-cases との整合性確認
レビュー観点をスキルとして持つことで、レビューは属人的なコメントではなく、チームの知識として蓄積できます。
Skill は何を持つのか
River Review の Skill は、単なるプロンプト断片ではありません。
実装上は、Skill ごとに次のような要素を持たせる想定です。
skills/
└── upstream/
└── rr-upstream-plangate-plan-integrity-001/
├── SKILL.md
├── prompt/
│ ├── system.md
│ └── user.md
├── fixtures/
├── golden/
└── eval/
└── promptfoo.yaml
重要なのは、レビュー観点だけでなく、入力例・期待結果・評価設定も一緒に残せることです。
これにより、次のような改善サイクルを作れます。
- AIレビューが指摘する
- 人間が採用・却下を判断する
- 判断理由をスキルやルールに反映する
- 次回レビューで同じ観点を再利用する
このサイクルを回すことで、レビューが少しずつチーム固有のものになります。
Artifact を入力として扱う
River Review では、レビュー対象をコード差分だけに限定しません。
たとえば、次のような artifact を入力として扱います。
plandifftest-casesjunitcoverage
これにより、単に「このコードはよいか」ではなく、次のようなレビューができます。
- plan に書かれた目的と diff が一致しているか
- test-cases が変更内容を十分にカバーしているか
- junit の失敗が既知の問題なのか、新しい問題なのか
- coverage の低下がリスクとして許容できるか
AIレビューをPRコメント生成だけで終わらせず、開発プロセス上の成果物を横断して確認するための設計です。
3つのレビュー段階
Upstream: 要件・設計を見る
Upstream では、実装前の文脈を確認します。
- 要件は明確か
- スコープが広がっていないか
- 設計方針と矛盾していないか
- ADRや既存ルールと整合しているか
- PlanGate の plan / todo / test-cases が自然につながっているか
AI開発では、実装が速いため「そもそも作るべきものが正しいか」を確認する重要性が上がります。
ここを見ずにPRレビューだけを強化すると、間違った方向にきれいなコードを書いてしまう可能性があります。
Midstream: 実装・PRを見る
Midstream では、コード差分をレビューします。
- 実装が目的に合っているか
- 不要な変更が混ざっていないか
- 既存設計を壊していないか
- セキュリティや保守性に問題がないか
- テスト追加が変更内容に追従しているか
ここは一般的なAIコードレビューに近い領域です。
ただし River Review では、Upstream の文脈を踏まえてレビューできる点が重要です。
Downstream: テスト・QA・運用を見る
Downstream では、変更後の品質を確認します。
- テスト観点は十分か
- 異常系や境界値が確認されているか
- リリース時のリスクはないか
- 運用時に監視すべき点はあるか
- 変更によってドキュメント更新が必要か
AIが生成したコードは、一見きれいでもテストや運用観点が弱いことがあります。
Downstream のレビューを入れることで、実装後の品質を補強できます。
GitHub Actions での利用イメージ
River Review は GitHub Actions から使えるようにしています。
最小構成のイメージは次のようになります。
name: River Review
on:
pull_request:
permissions:
contents: read
pull-requests: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: s977043/river-review/runners/github-action@v0.28.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
phase: midstream
dry_run: true
env:
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
最初からコメント投稿まで自動化する必要はありません。
まずは dry_run: true やコスト見積もりを使って、出力内容を確認してから段階的に有効化するのが安全です。
また、PlanGate 連携のような上流レビューを試す場合は phase: upstream の Skill として扱います。
小さく始めるなら
最初から全部のレビュー観点を入れる必要はありません。
自分なら、まず次の順番で始めます。
1. テスト不足チェック
AIが生成した実装では、正常系だけテストされていて、異常系や境界値が抜けることがあります。
まずは Downstream のテスト観点から入ると、効果が見えやすいです。
2. API変更チェック
API変更は影響範囲が広くなりやすいです。
後方互換性、既存利用箇所、ドキュメント更新の有無をレビュー観点にすると、実務で使いやすいです。
3. 設計方針チェック
チームでADRや設計ルールを持っている場合は、それを Upstream / Midstream のレビュー観点にできます。
「このリポジトリではこう判断する」という知識をスキル化できると、レビューの再現性が上がります。
Human-in-the-Loop を前提にする
River Review は、AIにすべてを任せるためのものではありません。
むしろ、人間の判断をレビュー運用に残すことを重視しています。
AIレビューで重要なのは、単にコメントを自動生成することではありません。
- どの指摘を採用したか
- なぜ無視したか
- 次回からどの観点を追加すべきか
- どの判断をチームルールにするか
こうした判断を積み重ねることで、レビューは改善されます。
AIに任せる部分と、人間が判断する部分を分けることが重要です。
River Review が目指しているもの
River Review が目指しているのは、単なるAIレビュー自動化ではありません。
目指しているのは、レビューをチームの知識資産に変えることです。
従来のレビューコメントは、そのPRの中だけで消費されがちでした。
しかし実際には、レビューコメントにはチームの重要な知見が含まれています。
- この設計は避けるべき
- このAPI変更には注意が必要
- この種類の変更ではテストが漏れやすい
- この領域は運用リスクが高い
River Review では、こうした知見をスキルやルールとして扱い、次回以降のレビューに活かせるようにしたいと考えています。
向いているチーム
River Review は、特に次のようなチームに向いています。
- AIコーディングを導入している
- PRレビューの観点が人によってばらつく
- レビュー指摘が毎回似ている
- テストレビューや設計レビューも仕組み化したい
- チーム固有のレビュー知識を蓄積したい
逆に、単発のコードレビューだけをしたい場合は、既存のAIコードレビューでも十分かもしれません。
River Review は、継続的にレビュー品質を育てていきたいチーム向けです。
今後やりたいこと
今後は、以下を強化していく予定です。
- Riverbed Memory の実装
- レビュー結果の蓄積
- スキル改善フロー
- 評価基盤の強化
- ダッシュボード
- 自動Issue生成
- 複数AIエージェント対応
特に、レビュー結果を次のスキル改善につなげる仕組みを強化したいです。
まとめ
River Review は、AIにレビューを丸投げするためのツールではありません。
むしろ逆で、AI開発時代において「人間が何をレビューすべきか」「どの判断を知識として残すべきか」を整理するためのフレームワークです。
ポイントは次の3つです。
- PR差分だけでなく、開発の流れ全体を見る
- レビュー観点を Skill として定義し、再利用可能にする
- 人間の判断をレビュー運用の中に残す
AIで実装速度が上がるほど、レビューはボトルネックになります。
River Review は、そのボトルネックを単に自動化するのではなく、レビューをチームの知識資産に変えることを目指しています。
FAQ
River Reviewは既存のAIコードレビューと何が違いますか？
既存のAIコードレビューは、PR差分に対する指摘が中心になりやすいです。
River Reviewは、PR差分だけでなく、要件、設計、実装、テスト、運用までを開発の流れとして扱うことを重視しています。
最初からUpstream、Midstream、Downstreamを全部入れる必要がありますか？
ありません。
最初は、テスト不足チェックやAPI変更チェックのように、効果が見えやすい観点から小さく始めるのがよいです。
PlanGateとはどう組み合わせますか？
PlanGateは、AIが実装を始める前に計画を作り、人間が承認するための仕組みです。
River Reviewは、その前後を含めてレビュー観点をSkillとして育てる仕組みです。PlanGateで実装前に止め、River Reviewでレビュー観点を継続的に改善する、という組み合わせを想定しています。