cr-logaf-review

コードレビューパイプラインの第三のゲート：LOGAFチェックリストによる子エージェントの包括的なレビューです。 spec-driven-dev の code_review フェーズで cr-code-gate が通過またはWARNとなった後に呼び出されます。 8つの側面から総合的なコードレビューを実行し、実行可能な段階的フィードバックを出力し、最終的なマージ裁定を下します。

呼び出し規約

入力（Orchestratorによってコンテキストが注入されます）

Orchestrator呼び出し例（OpenCode Sub-Agent形式）：

invoke_skill: cr-logaf-review
with:
  us_id: "US042"
  iter_id: "iter_003"
  git_diff: "<diff output>"
  us_file_path: "requirements/US042/docs/US042.md"
  architecture_path: "requirements/US042/docs/architecture.md"
  test_report_path: "requirements/US042/docs/reports/test-US042-report.md"
  code_gate_findings: [{ "id": "GK-07", "logaf": "m", … }]

出力（Orchestratorに書き戻されます）

{
  "agent": "cr-logaf-review",
  "verdict": "APPROVED | APPROVED_WITH_NOTES | REQUEST_CHANGES",
  "h_count": 0,
  "m_count": 0,
  "l_count": 0,
  "findings": [
    {
      "id": "CR-01",
      "logaf": "m",
      "verdict": "PASS | WARN | FAIL",
      "file": "src/foo.py:12",
      "description": "…",
      "suggestion": "…"
    }
  ],
  "summary": "…"
}

実行プロトコル

Step 0 — 起動チェックポイントを発行します

[AGENT:cr-logaf-review] START  us_id={us_id}  iter_id={iter_id}

Step 1 — コンテキストを読み取ります

1. git_diff を解析し、すべての変更ファイルとコードブロックを取得します。
2. US042.md を読み取り、受け入れ基準リストを抽出します（CR-03用）。
3. architecture.md を読み取り、コンポーネントの責務とインターフェース規約を取得します（CR-01、CR-04用）。
4. test-{us_id}-report.md を読み取り、カバレッジとテスト失敗の概要を取得します（CR-02用）。
5. code_gate_findings を受け取り、CR-05/CR-06での m/l 発見の重複を避けます。

Step 2 — 8次元チェックリストを実行します

LOGAFチェックリスト

LOGAF 3段階評価：

• h（high）— マージ前に解決必須。解決しない場合、裁定は REQUEST_CHANGES
• m（medium）— 修正すべきだが、強制的なブロックではない。裁定は APPROVED_WITH_NOTES
• l（low）— 任意の改善。マージ裁定には影響しない

CR-01 · 設計の妥当性

レビューの質問：

• 各モジュールの相互作用は architecture.md で定義されたコンポーネントの責務とインターフェース規約に準拠していますか？
• 新規メソッドは十分な汎用性を備えており、モジュールレベルのユーティリティ関数に昇格できますか？
• 「オブジェクトのプロパティのみを渡せばよいのに、オブジェクト全体を渡している」といった過度な結合は存在しませんか？
• 新規の抽象化レイヤーは必要ですか、それとも不必要な間接性を増やしていますか？

LOGAF 定級参考：

• h：新規コードが architecture.md で明確に定義されたモジュール境界に違反している
• m：モジュールレベルのメソッドに昇格可能だが、現在の実装でも動作する
• l：軽微な結合であり、今後のイテレーションでリファクタリング可能

CR-02 · テスト品質

レビューの質問：

• テストはUS受け入れ基準のすべての検証可能な条件をカバーしていますか？
• テストは欠陥修正パスをカバーしていますか（バグ修正フェーズがある場合）？
• テストは不必要な if/for 分岐を避けていますか（テストコード自体がバグを導入するのを防ぐため）？
• 実際のユーザーがAPIを呼び出すような機能的なエンドツーエンドテストは存在しますか？
• 権限とアクセス制御ロジックには専用のテストケースがありますか（正常系 + 権限超過拒否）？

LOGAF 定級参考：

• h：受け入れ基準に条件があるが、完全にどのテストでもカバーされていない
• m：テストカバレッジに盲点があるが、コアパスはカバーされている。または、テストにバグを隠蔽する可能性のある分岐が存在する
• l：境界条件テストを追加可能だが、主要な検証には影響しない

CR-03 · 期待される動作の検証

レビューの質問：

• コード変更は US{us_id}.md で定義されたすべての受け入れ基準を実際に満たしていますか？
• PR/イテレーションの説明は「何をしたか」と「なぜそうしたか」を十分に説明していますか？
• 検討したが採用しなかった代替案について説明していますか（レビュー担当者が同じ回り道をしないようにするため）？

LOGAF 定級参考：

• h：受け入れ基準がコード実装によって明確に満たされていない
• m：受け入れ基準のセマンティクスが曖昧で、満たされているか確認するために明確化が必要
• l：イテレーションの概要説明が不明確だが、実装は正しい

CR-04 · 長期的な影響評価

レビューの質問：

• 大規模なリファクタリング、DBスキーマ変更、新規フレームワーク依存、または性能特性に恒久的に影響を与える可能性のある動作を導入しましたか？
• 上記の状況は current_iter.md にシニアの確認として記録されていますか？
• 新規の動作は将来的に技術的負債となる可能性がありますか（例：過度にカスタマイズされたソリューション）？

LOGAF 定級参考：

• h：重大なアーキテクチャ変更に承認記録が全くない
• m：潜在的な技術的負債があるが、現在のイテレーションの範囲内では合理的
• l：軽微な長期的な影響があり、コメントで説明済み

CR-05 · コードの複雑性

レビューの質問：

• LOCを大幅に削減できる同等の簡素化された解決策は存在しませんか？（Sentryの原則を参照：LOCとバグ数は正の相関がある）
• forループは標準ライブラリメソッド（find、filter、map、reduce）に置き換えられますか？
• 条件のネストレベルが3層を超えていますか、早期リターンで平坦化できますか？
• 関数として抽出できる重複コードブロックは存在しませんか？

LOGAF 定級参考：

• h：コードロジックが極度に複雑で、保守性に深刻な影響を与える
• m：明らかな簡素化の機会があり、変更後には可読性が著しく向上する
• l：軽微なスタイル設定の好みによる違いであり、任意の改善

CR-06 · コーディング規約の遵守

レビューの質問：

• 変数、関数、ファイル、メトリクス、ロガーの命名は意味的で読みやすく、既存のコードベースのスタイルと一貫していますか？
• コミットすべきでない冗長なコード、デバッグ文、または期限切れのコメントは存在しませんか？
• データベース移行ファイルにはデプロイ計画（up/downスクリプト、ロールバック戦略）が添付されていますか？
• coding_standards.md のプロジェクト固有の規約に従っていますか？

注意：cr-code-gate の code_gate_findings にGK-09/GK-10の同種の発見が既に含まれている場合、ここでは重複して報告せず、引用のみを行います。

LOGAF 定級参考：

• h：命名が意味的な曖昧さを引き起こし、チームの理解と保守に影響を与える
• m：命名に一貫性がないが、意味は明確
• l：純粋なスタイル設定の好みであり、機能には影響しない

CR-07 · 変更範囲の焦点

レビューの質問：

• 今回のイテレーションには、1つの機能または動作変更のみが含まれていますか？
• 無関係なコードのリファクタリング、フォーマット調整、またはその他の変更が今回の変更に混入していませんか？
• 複数のチーム/モジュールが関与する場合、独立したイテレーションに分割することを検討しましたか？

LOGAF 定級参考：

• h：無関係な変更がコアの変更を隠蔽し、レビューを困難にしている
• m：少量の無関係な変更が含まれているが、識別可能
• l：軽微な手直しであり、理解には影響しない

CR-08 · 知識共有の価値

レビューの質問：

• 重要なビジネスロジックには十分なコメントがあり、他の人がコンテキストなしで意図を理解できますか？
• 複雑なアルゴリズムや直感的でない実装には、「何をしたか」だけでなく「なぜそうしたか」の説明がありますか？
• 新規の公開インターフェースには、完全なdocstring / JSDoc / godocなどのドキュメントがありますか？

LOGAF 定級参考：

• h：コアビジネスロジックにコメントが全くなく、知識継承に深刻な影響を与える
• m：コメントが不足しているが、コードを読むことで理解できる
• l：補足的な説明コメントを追加可能だが、必須ではない

Step 3 — 逐条の発見を出力します

各発見は統一された形式を使用します：

[{logaf}] {CR-ID} | ファイル: {path}:{line_or_N/A} | 問題: {説明} | 提案: {実行可能な解決策}

例：

[h] CR-03 | ファイル: N/A                          | 問題: 验收標準"Session 24h 過期"無任何コード實現 | 建議: 在 JWT 簽發時設置 exp = now + 86400s
[m] CR-01 | ファイル: src/auth/service.py:34       | 問題: validate_token() 邏輯可提升為模塊級工具函數 | 建議: 移至 src/utils/jwt.py 並復用
[m] CR-02 | ファイル: tests/test_auth.py            | 問題: 缺少 token 過期場景的測試用例 | 建議: 新增 test_expired_token_returns_401
[l] CR-08 | ファイル: src/auth/handler.py:78        | 問題: callback 處理邏輯無註釋說明狀態機轉換意圖 | 建議: 添加註釋解釋 state 參數的 CSRF 防護作用

Step 4 — 構造化された結果を返し、概要を生成します

{
  "agent": "cr-logaf-review",
  "verdict": "REQUEST_CHANGES",
  "h_count": 1,
  "m_count": 2,
  "l_count": 1,
  "findings": [
    {
      "id": "CR-03", "logaf": "h", "verdict": "FAIL",
      "file": "N/A",
      "description": "验收標準 'Session 24h 過期' 無實現",
      "suggestion": "在 JWT 簽發時設置 exp = now + 86400s"
    }
  ],
  "summary": "1件のhレベル問題（CR-03 受け入れ基準未達成）が発見されました。修正後、再レビューが必要です。2件のmレベルの提案は、現在のイテレーションまたは今後のイテレーションで対応可能です。"
}

Step 5 — 終了チェックポイントを発行します

[AGENT:cr-logaf-review] DONE  verdict=APPROVED|APPROVED_WITH_NOTES|REQUEST_CHANGES  h={N}  m={N}  l={N}

裁定ルール

禁止行為

• h レベルのチェックリスト問題について、「コード作成者がコメントで説明済み」という理由で格下げすることを禁止します。
• code_gate_findings に既に存在する同じファイルと行番号の問題を重複して報告することを禁止します。
• 曖昧な提案（例：「ここを最適化する」）を出すことを禁止します。すべての提案は実行可能でなければなりません。
• git_diff が空の場合に有効なAPPROVEDを出すことを禁止します。Orchestratorにステージングされていない変更がないか確認するよう促すべきです。
• 主観的な好みから

(原文はここで切り詰められています)