document-review

ドキュメントレビュー

複数のペルソナによる分析を通じて、要件ドキュメントや計画ドキュメントをレビューします。専門のレビュアーエージェントを並行して起動し、品質上の問題を自動修正したうえで、ユーザーの判断が必要な戦略的な質問を提示します。

フェーズ 0：モードの検出

スキルの引数に mode:headless が含まれているか確認します。引数には、ドキュメントのパス、mode:headless、またはその両方が含まれる場合があります。mode: で始まるトークンはファイルパスではなくフラグです。これらを引数から取り除き、残ったトークン（あれば）をフェーズ 1 で使用するドキュメントのパスとします。

mode:headless が含まれている場合は、以降のワークフロー全体でヘッドレスモードを有効にします。

ヘッドレスモードでは、分類の基準ではなく、インタラクションモデルが変わります。ドキュメントレビューでは引き続き、明確な正解が 1 つある修正と、ユーザーの判断が必要な修正を同じ基準で見極めます。異なるのは、自動修正しない指摘の提示方法だけです。

• auto の修正は、対話モードと同様に通知せず適用されます
• present の指摘は、呼び出し元が処理できるよう構造化テキストで返されます。AskUserQuestion による質問や、対話形式での承認はありません
• フェーズ 5 は「レビュー完了」を返して直ちに終了します（改善するか完了するかの質問はありません）

呼び出し元には、元の分類を維持した指摘が返され、それをどう扱うかは呼び出し元が決定します。

呼び出し元は、スキルの引数に mode:headless を含めることで、ヘッドレスモードを呼び出します。例：

Skill("compound-engineering:document-review", "mode:headless docs/plans/my-plan.md")

mode:headless が含まれていない場合、スキルは既定の対話モードで動作し、動作に変更はありません。

フェーズ 1：ドキュメントの取得と分析

ドキュメントのパスが指定されている場合： そのドキュメントを読み、次に進みます。

ドキュメントが指定されていない場合（対話モード）： レビューするドキュメントを尋ねるか、ファイル検索／glob ツール（Claude Code の Glob など）を使って docs/brainstorms/ または docs/plans/ にある最新のドキュメントを見つけます。

ドキュメントが指定されていない場合（ヘッドレスモード）： エージェントを起動せず、次を出力します。"Review failed: headless mode requires a document path. Re-invoke with: Skill("compound-engineering:document-review", "mode:headless ")"

ドキュメントの種類を分類する

読み込んだ後、ドキュメントを分類します。

• 要件 -- docs/brainstorms/ にあり、何を、なぜ作るのかに焦点を当てたもの
• 計画 -- docs/plans/ にあり、実装の詳細を含め、どのように構築するかに焦点を当てたもの

条件付きペルソナの選択

ドキュメントの内容を分析し、どの条件付きペルソナを有効にするか判断します。以下のシグナルを確認してください。

product-lens — 何を、なぜ構築するのかについて、異論の余地がある主張がドキュメントに含まれている場合、または提案された作業が目の前の問題を超える戦略的な重要性を持つ場合に有効にします。システムのユーザーは、エンドユーザー、開発者、オペレーター、メンテナー、その他の対象者である可能性があります。判断基準はドメインに依存しません。以下のいずれかの要件を満たすか確認してください。

要件1 — 前提に関する主張： ドキュメントが、何を構築するか、またはなぜ構築するかについて、知識のある関係者が合理的に異議を唱え得る立場を示している場合。単にタスクを説明している場合や、既知の要件を言い換えている場合は該当しません。

• 既存の文脈から自明ではなく、明白とは言えないニーズを示す課題の捉え方
• 暗黙的か明示的かを問わず、実行可能な代替案が存在するソリューションの選択
• 構築するものと先送りするものを明示的に順位付けする優先順位の決定
• 制約を言い換えたり成果物を説明したりするのではなく、具体的なユーザーの成果を予測する目標の記述

要件2 — 戦略的重要性： 前提が妥当であっても、提案された作業がシステムの方向性、ユーザーの認識、または競争上の位置付けに影響を与える可能性がある場合。

• システムの認識のされ方や、何で知られるようになるかを左右する変更
• 導入、オンボーディング、認知負荷に影響する、複雑さとシンプルさに関する選択
• 将来の方向性を開く、または閉ざす作業（パス依存性、アーキテクチャ上のコミットメント）
• 機会費用への影響。つまり、これを構築することで別の何かを構築できなくなること

design-lens — ドキュメントに以下が含まれる場合に有効にします。

• UI／UXへの言及、フロントエンドコンポーネント、またはビジュアルデザインの表現
• ユーザーフロー、ワイヤーフレーム、画面／ページ／ビューへの言及
• 操作の説明（フォーム、ボタン、ナビゲーション、モーダル）
• レスポンシブな動作やアクセシビリティへの言及

security-lens — ドキュメントに以下が含まれる場合に有効にします。

• 認証／認可、ログインフロー、セッション管理への言及
• 外部クライアントに公開される API エンドポイント
• データの取り扱い、PII、決済、トークン、認証情報、暗号化
• 信頼境界への影響を伴うサードパーティとの統合

scope-guardian — ドキュメントに以下が含まれる場合に有効にします。

• 複数の優先順位層（P0／P1／P2、必須／推奨／あれば望ましい）
• 要件または実装単位の数が多い（8件超）
• ストレッチゴール、あれば望ましい項目、または「今後の作業」セクション
• 記載された目標と整合していないように見えるスコープの境界に関する記述
• 要件とのつながりが明確でない目標

adversarial — ドキュメントに以下が含まれる場合に有効にします。

• 6件以上の異なる要件または実装単位
• 明示された根拠を伴う、明確なアーキテクチャまたはスコープに関する決定
• 影響の大きい領域（認証、決済、データ移行、外部統合）
• 新しい抽象化、フレームワーク、または重要なアーキテクチャパターンの提案

フェーズ2：ペルソナの発表と割り当て

レビューチームの発表

どのペルソナがレビューを担当するか、その理由とともにユーザーに伝えます。条件付きペルソナについては、有効にする根拠も示してください。

Reviewing with:
- coherence-reviewer (always-on)
- feasibility-reviewer (always-on)
- scope-guardian-reviewer -- plan has 12 requirements across 3 priority levels
- security-lens-reviewer -- plan adds API endpoints with auth flow

エージェントリストの作成

常に以下を含めます。

• compound-engineering:document-review:coherence-reviewer
• compound-engineering:document-review:feasibility-reviewer

有効にした条件付きペルソナを追加します。

• compound-engineering:document-review:product-lens-reviewer
• compound-engineering:document-review:design-lens-reviewer
• compound-engineering:document-review:security-lens-reviewer
• compound-engineering:document-review:scope-guardian-reviewer
• compound-engineering:document-review:adversarial-document-reviewer

ディスパッチ

プラットフォームのタスク/エージェントツール（例: Claude Code の Agent ツール、Codex の spawn）を使用して、すべてのエージェントを並列でディスパッチします。ユーザーが設定した権限設定が適用されるように、mode パラメータは省略してください。各エージェントは、以下に示すサブエージェントテンプレートから構築されたプロンプトを受け取ります。このとき、以下の変数が埋め込まれます。

変数	値
{persona_file}	エージェントの markdown ファイルの全内容
{schema}	以下に示す findings スキーマの内容
{document_type}	フェーズ 1 の分類による「requirements」または「plan」
{document_path}	ドキュメントへのパス
{document_content}	ドキュメントの全文

各エージェントにはドキュメント全体を渡してください -- セクションに分割しないでください。

エラー処理: エージェントが失敗またはタイムアウトした場合は、完了したエージェントからの findings で続行します。失敗したエージェントはカバレッジセクションに記載してください。単一のエージェントの失敗でレビュー全体をブロックしないでください。

ディスパッチ制限: 最大（7 エージェント）であっても、並列ディスパッチを使用してください。これらは単一のドキュメントを読む、範囲が限定されたドキュメントレビュアーです -- 並列は安全かつ高速です。

フェーズ 3〜5: 統合、提示、次のアクション

ディスパッチされたすべてのエージェントが戻った後、統合パイプライン（検証、ゲート、重複排除、昇格、矛盾の解決、autofix クラスによるルーティング）、自動修正の適用、finding の提示、および次のアクションメニューについては、references/synthesis-and-presentation.md を読んでください。エージェントのディスパッチが完了する前にこのファイルを読み込まないでください。

---

含まれる参照

サブエージェントテンプレート

@./references/subagent-template.md

Findings スキーマ

@./references/findings-schema.json