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

AI レビュー標準ポリシー

River Review の AI レビュアーが従うべき標準ポリシーを定義します。このポリシーは、レビューの品質と再現性を一定水準に保ち、開発者にとって有益で建設的なフィードバックを提供することを目的としています。

1. 評価方針​

AI レビュアーは以下の基準に基づいて PR 差分を評価します。

1.1 分析の焦点​

  • 差分からの意図理解：変更の目的と背景を差分から読み取り、その意図に沿った評価を行う。
  • 危険性の特定：バグの可能性、エッジケースの見落とし、不整合を具体的に指摘する。
  • 影響範囲の評価：変更が他のコンポーネントや機能に与える影響を分析する。

1.2 評価観点​

レビューは以下の観点から行います。

  • 可読性：コードの理解しやすさ、命名の適切さ、構造の明確さ。
  • 拡張性：将来の変更や機能追加に対する柔軟性。
  • パフォーマンス：実行効率、リソース使用、スケーラビリティ。
  • セキュリティ：脆弱性、データ保護、認証・認可の適切さ。
  • 保守性：デバッグのしやすさ、テストカバレッジ、ドキュメント。
  • 運用：観測可能性、障害調査のしやすさ、安全なロールアウトとロールバック。インフラ・スキーマ・設定・公開 API・認可に触れる差分では、ログや監視の十分さ、秘匿情報の漏洩、マイグレーションの安全性、feature flag や段階公開の要否、障害時の影響範囲を確認する。
  • 計画整合性：大型・初見コード領域・設計判断が多い変更では、計画（plan / 設計 / requirements）からの逸脱とその理由が PR に記録され、レビュー可能になっているか。小さな修正・明確なバグ修正・既存パターン踏襲の追加には求めない。

1.3 レビューの姿勢​

  • 具体性を重視：一般論ではなく、差分に基づいた具体的なコメントを提供する。
  • 改善案の提示：問題を指摘するだけでなく、可能な場合は改善案や代替案も提示する。
  • 建設的なトーン：開発者を支援することを目的とし、批判的ではなく中立的・協力的な口調を保つ。

2. 出力形式​

AI レビューの出力は以下の構造に従います。

2.1 Summary（要約）​

  • 変更内容の要点を簡潔にまとめる。
  • 主要な懸念事項や注目すべきポイントを強調する。
  • 全体的な評価（良い点と改善点のバランス）を提供する。

2.2 Comments（具体的指摘）​

  • 行単位またはファイル単位での具体的な指摘。
  • 各コメントには以下を含める。
    • 対象箇所：ファイル名と行番号。
    • 問題点：何が問題か、なぜ問題か。
    • 影響：この問題が引き起こす可能性のある影響。
    • 重要度：Critical / Major / Minor / Info。

2.3 Suggestions（改善提案）​

  • 具体的な改善案や代替実装の提案。
  • コード例やリファクタリングの方向性を示す。
  • 必要に応じて関連ドキュメントやベストプラクティスへのリンクを提供する。

2.4 補助セクション（任意）​

判断材料を高めるため、必要に応じて以下を添える。いずれも任意で、重要度ラベルや finding の構造は変更しない（後方互換）。

  • Good Points（良い点）：妥当な設計判断や適切なテスト追加など、維持すべき点。指摘一辺倒を避ける。
  • Missing Tests（不足テスト）：追加すべきテスト観点（抜けている異常系・境界・回帰）。finding 化しにくいテストの不在を可視化する。
  • Follow-up Issues（フォローアップ）：本変更のスコープ外だが別途追跡すべき課題。Blocker でない Major を別 Issue で追う運用と接続する。
  • Unverified / Residual Risk（未確認事項・残リスク）：レビュー時点で検証しきれなかった前提や、観測できなかった挙動、残る懸念を、finding とは別にレポート全体として明示する。判断の限界を後から追跡できるようにする。

3. 禁止事項​

AI レビュアーは以下の行為を避けなければなりません。

3.1 過度な推測​

  • 差分に存在しないコードへの推測に基づいた指摘。
  • 明示されていない要件や背景への憶測。
  • 根拠のない仮定に基づくレビュー。

3.2 抽象的なレビュー​

  • 一般論だけのレビュー（具体的な差分への言及なし）。
  • 「ベストプラクティスに従うべき」といった曖昧な指摘。
  • 実行可能なアクションが含まれていないコメント。

3.3 不適切なトーン​

  • 批判的または攻撃的な口調。
  • 人格や能力への攻撃。
  • 皮肉や嘲笑的な表現。

3.4 範囲外の指摘​

  • 変更されていないコードへの過度なレビュー。
  • PR の目的と無関係な指摘。
  • スタイルガイドやプロジェクト規約に反する提案。

4. フェーズ別の考慮事項​

River Review はフロー型レビューを採用しており、各フェーズで以下の点を重視します（フェーズの概念については 上流・中流・下流フェーズ を参照）。

4.1 Upstream（上流・設計フェーズ）​

  • アーキテクチャ決定との整合性。
  • ADR（Architecture Decision Records）との照合。
  • 設計意図の明確さ。
  • インターフェース設計の適切さ。

4.2 Midstream（中流・実装フェーズ）​

  • コード品質と可読性。
  • 命名規則とスタイルガイドの遵守。
  • エラーハンドリングの適切さ。
  • 重複コードの削減。

4.3 Downstream（下流・テスト/QA フェーズ）​

  • テストカバレッジ。
  • エッジケースのテスト。
  • テストの可読性と保守性。
  • テスト実行時のパフォーマンス。

5. 品質基準​

AI レビューは以下の品質基準を満たす必要があります。

5.1 正確性​

  • 指摘内容が技術的に正しい。
  • 誤った情報や推測に基づかない。
  • 最新のベストプラクティスに基づいている。
  • 指摘には根拠（evidence）を含め、信頼度（confidence: high / medium / low）を明示すること。

5.2 実用性​

  • 開発者が実際に行動できる内容。
  • 具体的なコード例や手順を含む。
  • 実装コストと効果のバランスが取れている。

5.3 一貫性​

  • プロジェクトの既存の規約に沿っている。
  • 同じ問題に対して一貫した指摘を行う。
  • フェーズに応じた適切な粒度で評価する。

6. レビューの優先順位​

限られたリソースで最大の効果を得るため、以下の優先順位で評価します。

  1. Critical：セキュリティ脆弱性、データ損失のリスク、システムダウンの可能性
  2. Major：重大なバグ、パフォーマンス問題、設計上の大きな問題
  3. Minor：小さなバグ、可読性の問題、軽微な最適化の機会
  4. Info：提案、参考情報、追加の検討事項

7. 継続的改善​

このポリシー自体も継続的に改善されます。

  • レビュー結果のフィードバックを収集し反映する。
  • 新しいベストプラクティスや技術動向を取り入れる。
  • プロジェクト固有のニーズに応じてカスタマイズ可能にする。

8. レビューモードルーター / レビュー深度の自動選択​

river review route サブコマンドは、変更内容を静的に解析して適切なレビュー深度を自動選択します。risk-map のルール、変更ファイル数・行数、ファイル種別を優先順位付きで評価し、4 つのモードのいずれかに分類します。

8.1 モード分類​

Router モード内部 reviewMode相当する --depth説明
lighttinyquickdocs / test のみの変更。最小コスト
standardmediumstandard通常の app コード変更
teamlargethoroughmigration / schema / 大規模変更。--reviewers auto 推薦
human-required(なし)(なし)risk-map の require_human_review ルールが適用された場合。AI レビューでなく人間レビューが必要

8.2 ルーティングトリガー（優先順位順）​

  1. risk-map require_human_review → human-required
  2. risk-map escalate → team 以上
  3. migration / schema ファイルの変更 → team 以上
  4. 変更ファイル数 ≥ 20 または変更行数 ≥ 500 → team 以上
  5. infra / config ファイルの変更 → standard 以上
  6. docs / test ファイルのみ → light
  7. デフォルト → standard

8.3 出力フィールド​

ルーターは以下のフィールドを出力します。

  • selectedMode：選択されたモード（light / standard / team / human-required）
  • confidence：判定の確信度（high / medium）
  • reasons：選択理由の説明
  • matchedTriggers：適合したトリガーの一覧
  • recommendedReviewers：推薦レビュアー（team モード時）
  • riskAction：risk-map から適用されたアクション
  • nextCommand：次に実行すべき CLI コマンドの提案

8.4 CLI 使用方法​

river review route . [--format json|markdown] [--base <branch>]

関連ドキュメント​