Deep Review — マルチパースペクティブ × 業界ベストプラクティス分析

指定されたドキュメント・ワークフロー・設定ファイルを 複数の専門家視点 と 業界ベストプラクティス の両面からレビューし、改善提案を優先度付きで提示する。 コードレビューではなく、プラクティス・プロセス・設計方針 のメタレビュー。

スコープの明確化

このスキルは 設計判断・プラクティス選択・構造 のレビューに集中する。

• 対象: ワークフロー設計、アーキテクチャ構成、プロセス定義、ツール選定、ベストプラクティス適合性
• 対象外: コードの構文・ロジックの正しさ（それは通常のコードレビューの領域）

例: .github/workflows/ci.yml をレビューする場合、YAML の構文エラーやアクションのバージョン指定ミスは指摘しない。ワークフローの設計（ジョブ分割戦略、キャッシュ戦略、テスト並列化、デプロイ承認フロー等）を評価する。

いつ使うか

• プロジェクトのワークフロー定義・Agent 定義・CI/CD 設定などを「今の業界水準と比べてどうか」検証したいとき
• ドキュメントや設計方針を改善したいが、何を改善すべきか分からないとき
• 新しいツールやフレームワークのプラクティスを自分のプロジェクトに取り込みたいとき

入力

ユーザーから以下を受け取る（不足している場合は AskUserQuestion で確認する）:

1. レビュー対象: ファイルパス、ディレクトリ、または「このプロジェクトの CI 設定」のような概念的な指定
2. 比較対象のドメイン（任意）: 「AI Agent オーケストレーション」「モバイル CI/CD」「コードレビュー自動化」など。指定がなければ対象ファイルの内容から推定する
3. 重視する観点（任意）: 「再現性」「開発速度」「品質」など

実行モード

実行開始時に AskUserQuestion でモードを選択する:

モード	実行 Phase	推奨モデル	想定コスト	用途
Quick	Phase 1 → 4 → 5 → 6	Sonnet	低（50-100K トークン）	小規模対象、素早くギャップだけ知りたい
Full	Phase 1 → 2 → 3 → 4 → 5 → 6 → 7 → 見直しループ（任意）	Opus	高（300-500K トークン）	重要な設計判断、網羅的なレビューが必要

Quick モードでは Phase 2（業界調査）、Phase 3（マルチペルソナ）、Phase 7（実装+レビューループ）をスキップする。Phase 4 のギャップ分析はオーケストレーター自身の知識で実施する。

モデル選択の根拠: Full モードは Web 調査→多段ギャップ分析→トレードオフ評価と、多段推論・情報統合が中心のタスクであり Opus が優位。Quick モードは構造化分析・ドキュメントレビューが中心であり、Sonnet で十分な品質が得られる。Phase 3 の sub-agent は分析対象が明確なため Sonnet で起動する。

実行手順

進捗表示ルール

各 Phase 開始時に以下を出力すること:

[Phase {Phase名} ({進行番号}/{総数})] {1行の説明}

Full 例: [Phase 3: マルチパースペクティブレビュー (3/7)] 4名のペルソナで並列レビューを実行中... Quick 例: [Phase 4: ギャップ分析 (2/4)] オーケストレーター知識でギャップを特定中...

Phase 間データフロー

各 Phase の入出力を明示する。途中再開時はディスク上の成果物ではなく、前 Phase の出力を引き継ぐ。

Phase 1 → 出力: 対象サマリー(5-10行) + ファイル内容（または要約）
Phase 2 → 入力: 対象サマリー / 出力: 業界ソーステーブル + パターン箇条書き
Phase 3 → 入力: 対象サマリー + ファイル内容 + Phase 2 出力 / 出力: 視点横断マトリクス + ペルソナ別サマリー
Phase 4 → 入力: Phase 1-3 の全出力 / 出力: ギャップ一覧(欠落/乖離/過剰/強み)
Phase 5 → 入力: Phase 4 出力 / 出力: 改善提案テーブル + 提案詳細
Phase 6 → 入力: Phase 5 出力 / 出力: 採否決定リスト
Phase 7 → 入力: Phase 6 の採用提案 / 出力: 実装済みファイル一覧 + レビュー結果
見直しループ → 入力: 前回のギャップ一覧 + Phase 7 出力 / 出力: 差分サマリー（解消/未解消/新規）
  └→ 継続する場合: Phase 1 に戻る（2周目以降は Quick 相当で実行）

Phase 1: 対象の理解

1. レビュー対象のファイルをすべて Read で通読する（ファイル数が多い場合は Glob で一覧を取得してから読む）
2. 対象の構造・目的・主要な設計判断を 5-10 行で要約する
3. 関連ファイル（対象から参照されているファイル）も特定し、必要に応じて読む

Phase 2: 業界調査

1. 対象ドメインに関連する業界標準・ツール・フレームワーク・方法論を WebSearch で調査 する
2. 目標: 3 つ以上 の異なるソース（OSS プロジェクト、企業のエンジニアリングブログ、ツール公式ドキュメント等）を参照する。ただし、ニッチなドメインで質の高いソースが 3 つ集まらない場合は、集まった分のソースで進める。 不足分はオーケストレーター自身の知識で補完し、「業界ソース N 件 + オーケストレーター知識で補完」とユーザーに明示する
3. 各ソースから抽出したパターン・プラクティスを箇条書きでまとめる

調査の観点（対象ドメインに応じて取捨選択）:

• 構造: 業界標準のディレクトリ構成、ファイル分割、命名規約
• プロセス: ワークフローのステップ、承認ゲート、フィードバックループ
• 品質保証: テスト戦略、レビュー方式、自動検証
• スケーラビリティ: 大規模化した場合の課題と対策
• エラーハンドリング: 障害時のリカバリ、エスカレーション経路
• 開発者体験: オンボーディング、ドキュメント、ツール統合

Phase 3: マルチパースペクティブレビュー

対象の性質に応じて 3〜5 名のペルソナ を選定し、複数視点でレビューを実行する。単一視点では見えない死角を構造的に炙り出すのが目的。

Phase 3 開始時に references/persona-catalog.md を Read し、カタログ・選定ルール・プロンプトテンプレートに従って実行する。

実行方法（環境に応じた分岐）

Claude Code 環境（Task ツールが利用可能な場合）: 選定したペルソナごとに Task ツール（subagent_type: general-purpose, model: sonnet） を並列起動する。

重要: sub-agent はプロジェクト CWD 外のファイルを Read できない制約がある。オーケストレーターが Phase 1 で読んだファイル内容をプロンプトに直接埋め込むこと。ファイルが 3000 行を超える場合は要約（構造・主要セクション・設計判断）を埋め込む。

Claude.ai 環境（Task ツールが利用不可の場合）: sub-agent は使えないため、以下のフォールバックを適用する:

• ペルソナ数を 2〜3 名に削減（必須枠のみ、または必須枠 + 補完枠 1 名）
• 各ペルソナの視点で 逐次レビュー を実行する（ペルソナを明示的に切り替えながら分析）
• 出力フォーマットは同一（視点横断マトリクス + ペルソナ別サマリー）

結果の集約

全ペルソナの結果を 視点横断マトリクス に統合する。複数ペルソナが同じ問題を指摘した場合は重複を除去し、指摘数を記録する（複数視点からの指摘 = 優先度が高い根拠になる）。 フォーマットの詳細は references/output-templates.md の「視点横断マトリクス」セクションを参照。

Phase 4: ギャップ分析

対象ファイルと業界調査の結果を突合し、以下の観点でギャップを特定する。Full モードでは Phase 2（業界調査）+ Phase 3（マルチペルソナ）の結果を統合する。Quick モードではオーケストレーター自身の知識で分析する:

• 欠落: 業界では標準的だが対象に存在しないもの
• 乖離: 存在するが業界標準と異なるアプローチを取っているもの
• 過剰: 業界標準では不要とされるが対象に含まれているもの
• 強み: 業界標準を上回っている、または独自の有効なアプローチ（これも報告する）

Phase 5: 改善提案

Phase 5 開始時に references/output-templates.md を Read し、フォーマットに従って改善提案を出力する。

ギャップごとに改善提案を作成し、優先度・ギャップ種別・指摘元・視点数を含む提案テーブルと、各提案の詳細（選択肢比較テーブルまたは単一アプローチの説明）を出力する。

Phase 6: ユーザーとの合意

提案はユーザーが 判断材料を見て自分で選ぶ ためのもの。「これを採用すべき」ではなく「こういう選択肢がある」というスタンスで提示する。

1. 提案一覧を提示し、AskUserQuestion で採否を確認する（一括または個別）
2. 選択肢比較がある提案は、ユーザーがどの案を採用するか選べるようにする
3. ユーザーが追加の判断材料を求めた場合（「もっと詳しく比較して」「他のツールではどうしてる？」等）、Phase 2 に戻って追加調査する
4. 採用が決まった提案について、実装の進め方を相談する（この場で実装する / 別タスクとして切り出す / 検討のみ）
5. 実装する場合は Phase 7 へ進む

Phase 7: 実装 + マルチ AI レビューループ

採用された提案を実装し、複数の視点でレビューして品質を担保する。

7-1. 実装

対象ファイルを編集して変更を適用する。変更が複数ファイルにまたがる場合は、全ファイルの整合性（クロスリファレンス、用語統一、参照パス）を確認してからコミットする。

7-2. セルフレビュー

実装完了後、変更した全ファイルを通読し以下を確認する:

• 変更箇所間の整合性（同じ概念が複数箇所に記述されている場合の同期）
• 元の文脈を壊していないか（変更の前後を含めた文脈確認）
• 提案の意図と実装の一致

発見した問題は即座に修正する。

7-3. 外部 AI レビュー（セカンドオピニオン）

異なる AI モデルによるレビューで、自分のバイアスを補完する。以下の方法を 上から順に試行 し、最初に利用可能な方法を使う:

方法 1: プロジェクトのレビュースキル プロジェクトに /review や /codex-review スキルがある場合、それらを活用する。

方法 2: Codex CLI

codex --approval-mode full-auto \
  "以下のファイルの変更をレビューしてください。整合性の問題、改善点、見落としを指摘してください: <ファイルパス一覧>"

方法 3: Codex MCP MCP ツール経由で Codex にレビューを依頼する。プロンプトには変更対象ファイルのパスと変更の意図を含める。

方法 4: 別の Claude インスタンス（Claude Code 環境のみ） Codex が利用不可の場合、Bash で claude -p を使い別の Claude インスタンスにレビューを依頼する:

claude -p "以下のファイルの変更をレビューしてください。整合性の問題、改善点、見落としを指摘してください: <ファイルパス一覧>"

方法 5: セルフレビューのみ 上記いずれも利用不可の場合、セルフレビューのみで完了し、その旨をユーザーに通知する。

なぜ外部レビューか: 自分（Claude）が書いた変更を自分でレビューすると、同じバイアスで見落とす傾向がある。異なるモデルや異なるインスタンスのレビューは、異なるコンテキストからの指摘を得られるため補完性が高い。

7-4. 指摘のトリアージと修正

セルフレビューと外部レビューの指摘を統合し、対応する:

指摘の種類	対応
整合性の問題（矛盾、参照切れ）	即修正
内容の改善提案	ユーザーに提示し、採否を確認
スタイル・表現の好み	軽微なものは修正、主観的なものはスキップ
誤検出（的外れな指摘）	スキップ（理由をユーザーに説明）

7-5. 再レビュー（必要に応じて）

修正が多い場合（整合性の問題 3 件以上）、修正後にもう 1 ラウンドのセルフレビューを実行する。外部 AI レビューの再実行はユーザーに確認してから行う（コストがかかるため）。

ループ終了条件（いずれか満たせば終了）:

• セルフレビューで新規指摘 0 件 → 完了
• 外部レビューの Critical/High 指摘 0 件 → 完了
• 3 ラウンド到達 → 未解決指摘をユーザーに一覧提示し、AskUserQuestion で「承認して完了」or「手動対応に切り替え」を選択

見直しループ

Phase 7 完了後（または Quick モードの Phase 6 後にユーザーが手動で変更を適用した後）、全体を再レビューして改善が十分か確認するループ。

トリガー

Phase 7 完了後、AskUserQuestion で確認する:

見直しをもう一周しますか？ 改善した対象を Phase 1 から再レビューし、ギャップが埋まったか・新たな問題がないかを確認します。

• 「はい」 → 再レビューへ進む
• 「いいえ」 → レビュー完了

Quick モードの場合は Phase 6 の末尾で案内する: 「変更を適用したら、再レビューを依頼できます」

再レビューの進め方

2 周目以降は Quick 相当（Phase 1 → 4 → 5 → 6）で軽く回す。初回の Full モードで得た Phase 2（業界調査）・Phase 3（マルチペルソナ）の結果は引き継ぐため、再調査は不要。

再レビュー時の Phase 4（ギャップ分析）では、前回のギャップ一覧を参照し 差分サマリー を作成する:

• 前回指摘のギャップが 解消 されたか
• 未解消 のギャップはどれか
• 変更により 新規 のギャップが生まれていないか

出力フォーマットは references/output-templates.md の「差分サマリー」セクションを参照。

再レビューで採用提案が出た場合

Phase 6 でユーザーが提案を採用 → Phase 7 で実装 → 再び見直しループのトリガーに戻る。

ソフトリミット

3 周目に到達した場合、AskUserQuestion で念押しする:

3 周目に入ります。 残存ギャップ: {件数}。このまま続けますか、それとも残りは手動対応に切り替えますか？

これはハードリミットではなく、ユーザーが続行を選べばループを継続する。

優先度の定義

優先度	基準
P1	品質・安全性に直接影響する欠落。放置するとバグ・手戻り・セキュリティリスクにつながる
P2	開発効率・保守性に影響する乖離。改善すると明確なメリットがあるが、緊急ではない
P3	ベストプラクティスとの微差。改善は推奨だが、現状でも問題は生じない

フォールバック

Phase の実行中にエラーが発生した場合の対処:

障害	対処
WebSearch 失敗（ネットワーク/タイムアウト）	Phase 2 をスキップ。Phase 4 のギャップ分析はオーケストレーター自身の知識で実施
WebSearch の結果が不十分（質の高いソースが目標数に満たない）	集まったソースで続行し、不足分はオーケストレーター知識で補完。「業界ソース N 件 + オーケストレーター知識で補完」とユーザーに明示
sub-agent タイムアウト/エラー	取得済みの結果のみで集約。最低 2 ペルソナの結果があれば続行、1 名以下なら Phase 3 を再試行（1回のみ）
Task ツール利用不可（Claude.ai 環境等）	ペルソナ数を 2-3 名に削減し逐次実行。Phase 3 の「実行方法」セクション参照
sub-agent がファイル読み取り不可	プロンプトにファイル内容を埋め込み済みなら問題なし。埋め込み漏れの場合は再起動
外部 AI レビューツールが利用不可	Phase 7-3 の優先順位リストを順に試行。すべて利用不可ならセルフレビューのみで完了
コンテキスト超過の兆候	Phase 5 の提案詳細を簡略化（選択肢比較テーブルを省略、1提案2-3行に圧縮）

フォールバック発生時は、スキップした Phase とその理由をユーザーに明示すること。

注意事項

• コードの構文・ロジックの正しさは対象外（それは通常のコードレビューの領域）。設計判断・プラクティス選択・構造のレビューに集中する
• 業界調査は最新情報を優先する（WebSearch で現在の年を含めて検索する）
• 「業界標準」は銀の弾丸ではない。プロジェクトの文脈に合わない提案は出さない
• 強みも報告する。すべてを変えるべきという前提に立たない