plan-review

Plan Review Skill

目的

技術計画、提案、設計書について、実装前に構造化された監査を実施します。コードを書く前に、リスク、誤った前提、不足している要素、スコープの問題を明らかにすることが目的です。この段階であれば、軌道修正にかかるコストを最小限に抑えられます。

このスキルは読み取り専用です。コードを変更することはありません。重大度のタグが付いたレビュー文書を作成し、最終的にリリース／再検討／却下の判定を示します。

ステップ 0 — モードの選択

AskUserQuestion を使って、ユーザーに次の質問を 1 つだけします。

どの観点でレビューしますか？（1）プロダクト — スコープ、ユーザーへの影響、ビジネスとの整合性。 （2）エンジニアリング — アーキテクチャ、障害モード、テスト戦略、パフォーマンス。 （3）統合（デフォルト） — 両方の観点を組み合わせます。

回答を受け入れて、次に進みます。追加の設定に関する質問はしないでください。

また、計画からスコープの規模を評価します。

• 小規模な変更（単一ファイル、約 100 行以下）：4 セクションに圧縮したレビュー — スコープ、リスク、不足事項、判定 — を提示します。複数セクションからなる完全なテンプレートは使用しません。
• 標準的な変更：以下の完全なレビュー手順を実施します。

完全なレビュー手順

1. 計画の理解

計画を最初から最後まで読みます。理解を確認する 2～3 文の要約を提示します。以下を明示的に列挙します。

• 明記された目標 — 計画が達成するとしていること。
• 対象外の事項 — 明示的にスコープ外とされていること。
• 制約 — 言及または暗示されている予算、期間、互換性、チーム規模、技術上の制約。

要約に誤りがある場合、ユーザーはここで訂正できます。それ以降のレビューが誤った前提に基づいて進むことを防ぎます。

2. 前提への検証

暗黙の前提をすべて抽出します。それぞれについて、次の表を作成します。

前提	誤っていた場合の影響	裏付けとなる証拠	何があれば誤りだとわかるか

検証すべき一般的な前提のカテゴリは次のとおりです。

• データの入手可能性と形式
• サードパーティ API の安定性とレート制限
• 選択したツールに対するチームの習熟度
• 依存関係のパフォーマンス特性
• 下位互換性の要件
• デプロイ環境の能力

3. リスクと障害のマッピング

計画内の各コンポーネントまたはサブシステムについて、障害モードの表を作成します。

コンポーネント	障害モード	影響範囲	復旧戦略

さらに、データフローのシャドーパスも特定します。これには、本番環境で実行されるものの、正常系の処理経路には含まれない副作用、非同期コールバック、イベント伝播、キャッシュ無効化の連鎖などが含まれます。

3 つ以上のコンポーネントが相互に関係する計画では、見えにくいデータフローや障害の伝播を ASCII 図で説明します。

4. コンポーネントごとのレビュー（エンジニアリング観点）

主要な各コンポーネントについて、以下を評価します。

• エラー処理戦略 — エラーは分類され、レジストリを介して処理されますか。それとも、一括処理するハンドラーによって黙って無視されますか。
• データ整合性の不変条件 — どの不変条件を維持する必要がありますか。どのように保証されますか。破られた場合、どうなりますか。
• 並行性と競合状態 — 共有状態、ロックの取得順序、楽観的戦略と悲観的戦略、冪等性の保証。
• 負荷時のパフォーマンス — 現在の規模の 10 倍における予想スループット、レイテンシ予算、リソース消費。
• テスト戦略の妥当性 — コンポーネントに対する単体、統合、エンドツーエンドのテストカバレッジ。テストできないものと、その理由。

このセクションは言語やフレームワークに依存しません。ユーザーの技術スタックがわかっている場合は、フレームワークに応じた例として references/project-detection.md を参照します。

プロダクト観点のみのモードでは、このセクションを省略します。

5. スコープと優先度の評価（プロダクトの観点）

• 必須か、あると便利か — 明示された目標に不可欠な機能はどれですか？ 憶測に基づくものはどれですか？
• 後回しにできる候補 — リスクを増やさずに、後続のリリースに回せるものは何ですか？
• 過剰な設計の兆候 — 現在の要件では求められていない抽象化、設定可能性、拡張性はありますか？
• ユーザーへの影響 — その複雑さに見合う価値をユーザーにもたらしますか？

エンジニアリングの観点のみでレビューを実行する場合は、このセクションを省略してください。

6. 統合レビュー

コンポーネント同士、および外部システムとの接続方法を確認します。

• API コントラクト — モジュール間のリクエスト／レスポンスの形式、バージョン管理、エラーコード。
• 境界をまたぐ状態管理 — 状態の所有者は誰ですか？ どのように同期しますか？ 部分的な障害が発生した場合、どうなりますか？
• 移行とデプロイの順序 — どのコンポーネントを先にデプロイする必要がありますか？ システムに一貫性がなくなる中間状態はありますか？
• ロールバックの互換性 — 各デプロイ手順を個別に取り消せますか？ 元に戻せないデータはありますか？

7. 不足している点

計画で扱われていないものの、扱うべき項目：

• 監視と可観測性（メトリクス、ログ、アラート、ダッシュボード）
• 最初の再試行以降のエラー復旧手順
• 想定される正常系以外のエッジケース
• セキュリティ上の考慮事項（認証、認可、入力検証、シークレット管理）
• 負荷とスケールの影響（コネクションプール、キューの深さ、ストレージの増加）
• インシデント対応の運用手順書

8. 実行計画の評価

提案された実装順序を評価します。

• 依存関係の順序 — 依存先より先に前提条件が実装されていますか？
• 並行作業の機会 — 相互依存がなく、同時に進められるタスクはどれですか？
• リスク優先か、価値優先か — 計画はリスクが最も高い未知の要素に早期に取り組んでいますか？ それとも後回しにしていますか？
• プロトタイプの候補 — 本格的な実装に着手する前に、どのコンポーネントを試作すべきですか？

9. 判定

以下から必ず1つだけ選んでください。

判定	意味
リリース可	計画はしっかりしています。記載どおりに進めてください。
変更を加えてリリース可	実現可能ですが、先に進むには、以下に記載する具体的な修正が必要です。
再検討	根本的な構造上の問題があるため、計画の立て直しが必要です。変更すべき点を列挙してください。
却下	計画は実現不可能です。その理由と、検討すべき代替案を説明してください。

判定の理由を1段落で記載してください。

簡易レビュー（小規模な変更）

変更範囲が小さい場合（単一ファイル、約100行）は、以下の4つのセクションのみを提示します。

1. スコープ — 変更内容とその境界。
2. リスク — 障害モードと影響範囲（簡潔な表）。
3. 不足している点 — この規模でも対応すべきギャップ。
4. 判定 — リリース可／変更を加えてリリース可／再検討／却下。

対話プロトコル

• AskUserQuestion は一度に1つの問題について使用してください。複数の質問を1つのプロンプトにまとめないでください。
• 重大度が HIGH の指摘事項は、次のセクションに進む前にすぐに提示し、続行するか、議論のために一時停止するかを尋ねてください。
• このスキルは読み取り専用です。ファイルの作成、変更、削除は行いません。
• 障害の伝播や統合トポロジーを明確にする場合は、ASCII 図を使用してください。

出力形式

以下を含む、構造化されたレビュー文書：

• 上記の順序に一致する番号付きセクション
• すべての指摘事項に重大度タグを付与：[HIGH]、[MEDIUM]、[LOW]
• 重大度別に分類したすべての指摘事項の概要表を末尾に記載
• 理由を添えた最終判定