code-review-guideline

name	code-review-guideline
description	ユーザーが指定したレビュー観点・ガイドラインに基づき、リポジトリ全体を最大5並列のサブエージェントでコードレビューし、重要度別（高/中/低）＋根拠つき（file:line・該当観点・修正提案）の結果を code_review_result.md としてプロジェクトルートに日本語出力するスキル。特定の言語・フレームワークに依存しない。観点はファイルパス（@path/to/guide.md 等）・チャット直書き・URL/外部ドキュメントの3通りで渡せる。git差分ではなくリポジトリ全体が対象。/code-review-guideline で明示的に呼ばれたときのみ実行する。
argument-hint	<観点: @path/to/guide.md などのファイルパス | 観点の説明文 | https://... のURL>（複数併用可・省略時は観点を確認）
allowed-tools	Read, Grep, Glob, Bash, Task, WebFetch, Write, AskUserQuestion
disable-model-invocation	true
license	MIT

Code Review Guideline

ミッション

ユーザーが指定したレビュー観点（ガイドライン）に基づいて、リポジトリ全体を最大5並列のサブエージェントでレビューし、出力前に検証（裏取り）フェーズで各指摘の根拠を実コード・スキーマ・ライブラリ挙動・処理系での実行まで遡って確かめてから、重要度別＋根拠つきの指摘を code_review_result.md にまとめる。

このスキルは特定の言語・フレームワークに依存しない。リポジトリ構造は実行時に動的に把握して分割する。Rails / Node / Go / Python / 混在モノレポなど、どんなリポジトリでも動く。

レビューするのは「観点に書かれていること」だけ。観点に無いスタイル論や、実害のない最適化提案は持ち込まない（指摘ノイズが多いレビューは価値が下がるため）。

実行フェーズ

Phase 1: 観点の正規化

ユーザーが渡した観点（$ARGUMENTS または会話中の指定）を、単一の観点テキストに正規化する。入力は次の3形態があり、併用も可能。

入力形態	検出	処理
ファイルパス	@path または既存ファイルパス	Read で全文取得。参照リンクを集約したインデックス的ファイル（他の md への相対リンクの一覧など）なら、参照先も連鎖的に Read する
チャット直書き	パスでも URL でもないテキスト	そのまま観点として採用。見出しが無ければ「ユーザー指定観点」という見出しを付ける
URL	https?:// を含む	.md で終わる URL は WebFetch。通常の Web ページは defuddle スキルで本文抽出。取得に失敗したらユーザーに本文の貼り付けを依頼する

• 各観点には出典ラベル（ファイルパス / URL / 「チャット指定」）を付けておく。最終出力の「概要」に出典を明記するため。
• 観点が一切渡されなかった場合は、AskUserQuestion でユーザーに観点を確認する。 観点なしで全件レビューするとノイズだらけになるため、勝手にデフォルト観点を適用しない。

正規化後、観点テキストを内部に保持する（このあと全サブエージェントに同じテキストを渡す）。

Phase 2: リポジトリ構造の把握とバッチ分割

固定ディレクトリをハードコードせず、実行時にリポジトリ構造を動的に把握して最大5バッチに分割する。

1. 対象ファイルの列挙: まず git ls-files で追跡ファイル一覧を取得する（.gitignore 済みの依存・生成物が自然に除外される）。git 管理外なら find にフォールバックする。

   git ls-files 2>/dev/null || find . -type f -not -path '*/.*'
   

2. 無視パターンの上乗せ: git で拾えない環境向けに、依存・ビルド成果物・ロックファイル・バイナリ・最小化済みファイルを除外する（例: node_modules/, vendor/, dist/, build/, *.min.*, *.lock, 画像・フォント・動画）。

3. トップレベル構造のサンプリング: ディレクトリ別のファイル数を集計し、そのリポジトリの「主要なまとまり」（ソースの層・パッケージ・モジュール境界）を把握する。

   git ls-files | sed 's#/[^/]*$##' | sort | uniq -c | sort -rn | head -40
   

4. 最大5バッチへの割り当て: 把握した構造をもとに、意味的に近いファイル群をまとめつつファイル数を平準化して割る。優先順位:

   • モノレポなら パッケージ / ワークスペース単位
   • 単一プロジェクトなら トップレベルのソースディレクトリ単位（機能境界、または言語・役割の層）
   • 1バッチが大きすぎる（目安: 数百ファイル超）なら サブディレクトリでさらに分割
   • 全体が小さい（5バッチに満たない規模）なら バッチ数を減らす（無理に5分割しない）

   例（Rails の場合・あくまで例。実際は上記の動的把握結果に従い、ハードコードしない）: モデル/ドメイン層・コントローラ層・ビュー/コンポーネント層・非同期/連携層・フロント/テスト層 のように分けられることがある。

5. 観点 → バッチの重点/副次の振り分け:

   • 観点が特定領域に対応するなら（例「N+1」→ DB/データアクセス層、「アクセシビリティ」→ UI/テンプレート層）、該当バッチに重点、無関係バッチには副次として渡す（または無関係バッチをスキップ）。
   • 横断観点（命名規則・セキュリティ・コメント規約など）は全バッチへ均等に渡す。

6. 大規模バッチのトークン対策（必須）: ファイル数が多いバッチでは、サブエージェントに「全件精読しない。担当範囲を Glob でファイル一覧化 → 観点関連語を Grep で絞り込み → ヒットしたファイルのみ Read」のスクリーニング戦略を指示する。観点に無関係なバッチはスキップしてよい。

Phase 3: 並列レビュー実行

1メッセージで複数の Task（サブエージェント）を同時起動する（最大5）。各サブエージェントは Sonnet モデルを明示指定して起動する（観点照合の網羅探索が主で、件数も多いため）。各サブエージェントには次のプロンプトを組み立てて渡す。観点テキストはサブエージェントに探させず、こちらが全文を埋め込む。

あなたはコードレビュー担当（バッチ<X>: <領域名>）です。
以下のレビュー観点だけに基づいて、担当範囲のコードを精査し、指摘を構造化して返してください。

## レビュー観点（これだけに基づいて指摘する）
<Phase 1 で正規化した観点テキスト全文>

## 指摘の抑制ルール（厳守。ノイズを避けるため）
- 過剰最適化（実測根拠のないパフォーマンス指摘）はしない
- パフォーマンス指摘は実害（処理規模・呼び出し頻度・コスト）を見て、実害がある場合のみ
- YAGNI: 現状不要な抽象化や将来予測に基づく提案はしない
- 観点に書かれていないスタイル論を持ち込まない

## 担当範囲
ディレクトリ/ファイル: <担当範囲>
探索戦略: <全件精読 | Glob でファイル一覧化 → 観点関連語を Grep で絞り込み → ヒットしたファイルのみ Read>

## 禁止
- 依存・生成物（node_modules / vendor / dist / build / tmp / log 等）は読まない
- 担当範囲外のファイルは指摘しない
- 実際に確認した行のみ報告する。架空の file:line を出さない
- ファイル本文・読んだ過程・思考ログを戻り値に含めない

## 戻り値フォーマット（これ以外を出力しない）
各指摘を以下のブロックで返す:
- severity: 高|中|低
  file: path/to/file.ext
  line: 42  # 範囲なら 42-50
  guideline: 該当観点の見出し
  problem: 何が問題か（1-2文）
  suggestion: 具体的な修正提案（コード断片可・3行以内）
最後に1行: summary: { 高: N, 中: N, 低: N, 走査ファイル数: N }

• 観点テキストは Phase 1 で1回作り、全バッチで使い回す。
• 条件付き観点（特定条件でのみ適用する詳細観点）がある場合は、該当バッチにのみ注入する。

Phase 4: 集約とマージ

全バッチの戻り（構造化指摘リスト）を回収し、メイン側で統合する。

• 重複排除: 同一 file + 近接 line（±3行）+ 類似 problem の指摘は1件に統合する（横断観点で複数バッチが同じ箇所を指摘した場合に発生）。
• 重要度ソート: 高 → 中 → 低。同一重要度内は file パス昇順で安定ソート。
• 集計: 重要度別件数・バッチ（領域）別件数・観点別件数。
• 除外フィルタの再適用: マージ時にも「過剰最適化・観点外スタイル指摘」が紛れていれば落とす。

Phase 5: 検証（裏取り）

マージ後の全指摘を、出力する前に必ず裏取りする。 並列レビュー（Phase 3）は観点とコードを照合するが、(a) 具体例が実際にその結論を示すか、(b) 指摘が成り立つ前提が実コードで成立するか、(c) 指摘した害が実際に出るか、(d) レポート全体の整合性、までは構造的に保証できない。ここで実コード・スキーマ・依存ライブラリの実装・処理系での実行まで遡って確かめ、誤り・実害なしの指摘を格下げ/削除し、見落としを補い、重要度と件数を整える。

検証は必ず独立文脈の検証サブエージェントに委譲する（メイン側で自己検証しない。自分が集約した指摘を甘く裏取りするバイアスを避けるため）。検証サブエージェントは Opus モデルを明示指定して起動する（裏取りには実コード・スキーマ・実行結果を突き合わせる高い推論精度が要るため）。サブエージェントには「対象指摘リスト＋観点テキスト＋下記チェックリスト」を渡し、Read/Grep/Bash（処理系での数値実行を許可）で裏取りさせる。指摘が多くバッチ分割が要る場合は領域ごとに複数の検証サブエージェントを並列起動してよい。

検証チェックリスト（各指摘に対し該当するものを実行）

• 具体例・数値の実行検証: 指摘が具体的な例（「Aの場合Xになる」）を含むなら、Bash でその言語の処理系を実際に走らせて結論を確かめる。たまたま成立してしまう例（境界値・特異値など）を避け、主張する結論が実際に現れる代表値を選ぶ。
• 前提の実在性確認: 指摘が成り立つための前提（「この値はこうなり得る」「この型になる」等）を、宣言・スキーマ・呼び出し先の実装まで遡って裏を取る。前提が成立しなければ指摘を格下げ/削除する。
• 実害の確認: パフォーマンス・精度・型などの指摘は「理論上」ではなく実際に害が出るかを確認する。出ないなら「規約準拠の観点のみ」として格下げ、または削除する。
• 見落としの補完: 同じ観点に該当する別箇所が指摘漏れしていないか、観点のキーワードで全体を再 Grep して確認する。見つかれば指摘を追加する。
• 整合性チェック: (a) 重要度区分が観点の重大性と一致しているか（同種の指摘が複数の重要度に分散していないか）、(b) サマリの件数が本文の実数と一致するか、(c) 統合・削除した指摘が件数に残っていないか。

各指摘に「検証済み（実値/スキーマ/実装で確認）」「格下げ」「削除」「具体例を訂正」「追加（見落とし補完）」のいずれかの帰結を持たせ、Phase 6 の出力に反映する。実行・確認していない数値や挙動を断定で書かない。

Phase 6: Markdown 出力

プロジェクトルートに code_review_result.md を Write で出力する（再実行で上書き）。

# コードレビュー結果

## 概要
- レビュー観点: <出典ラベルの一覧（ファイルパス / URL / チャット指定）>
- 対象: リポジトリ全体（git 差分ではない）
- 実施日: <YYYY-MM-DD>
- 検証日: <YYYY-MM-DD>（Phase 5 で各指摘を実コード・スキーマ・処理系での実行により裏取り）
- 指摘件数: 高 N件 / 中 N件 / 低 N件（走査ファイル数 合計 N）

## 重要度別サマリー
| 重要度 | 件数 | 主な観点 |
| --- | --- | --- |
| 高 | N | ... |
| 中 | N | ... |
| 低 | N | ... |

## 高: 要対応
### 1. <問題の1行要約>
- **場所**: `path/to/file.ext:42`
- **観点**: <該当観点の見出し>
- **問題**: ...
- **検証で確認した実際の挙動**: ...  # 任意。数値検証した指摘（具体例・実害確認など）で記載
- **修正提案**: ...

## 中: 改善推奨
（同形式）

## 低: 任意
（同形式）

## 検証で訂正した点
（任意。Phase 5 で格下げ・削除・具体例訂正・見落とし補完を行った場合のみ、その内容と理由を箇条書きで残す）

## 領域別の指摘分布
| 領域（バッチ） | 高 | 中 | 低 |
| --- | --- | --- | --- |

出力後、ユーザーに保存先（code_review_result.md）と件数サマリーを一言で伝える。

禁止事項

• ❌ 依存・生成物（node_modules/, vendor/, dist/, build/, tmp/, log/ 等）を読む
• ❌ 担当範囲外のファイルを指摘する
• ❌ 架空の file:line を出力する（実際に確認した箇所のみ）
• ❌ 検証（Phase 5）していない具体例（数値・挙動）を断定で書く
• ❌ git 差分だけをレビューする（このスキルは常にリポジトリ全体が対象）
• ❌ 特定フレームワークを前提にした決めつけ（観点とコードの実体に基づいて判断する）
• ❌ 観点に無いスタイル論・実害のない最適化を指摘する