implementation-plan-review

実装計画のレビュー

このスキルでは、生成された実装計画を確立されたベストプラクティスに照らしてレビューし、品質、完全性、開発への準備状況を確認します。

前提条件

• 生成された milestones.yaml ファイル
• 関連する milestone-m*.tasks.yaml ファイル
• 任意：整合性チェック用のソース business-requirements.yaml および technical-requirements.yaml

レビュープロセス

フェーズ 1：構造の検証

すべての計画ファイルを読み込み、解析します。

1. ファイルの検索

   • milestones.yaml を探す
   • すべての milestone-m*.tasks.yaml ファイルを見つける
   • 参照されているタスクファイルがすべて存在することを確認する

2. スキーマの検証

   • YAML の構文を検証する
   • 必須フィールドが含まれていることを確認する
   • データ型と形式を検証する

3. 参照の整合性

   • マイルストーンの依存関係が存在することを検証する
   • タスクの依存関係が存在することを検証する
   • タスクファイルの参照がマイルストーンと一致することを確認する

フェーズ 2：ベストプラクティスへの準拠

組み込まれたベストプラクティスに照らしてレビューします。注： チェック項目の一部は対象読者によって異なります。

• AI 向け： 完全な TDD チェックリスト、ドリフトポリシー、明確な手順を期待します
• 人間向け： 高レベルの目標、制約、成功基準のみを期待します
• ハイブリッド向け： 重要なガイダンスを含む中程度の詳細さを期待します

指示の詳細度をレビューする際は、それに応じて期待値を調整してください。

対象読者の検証

• メタデータに target_audience が含まれている — milestones.yaml に meta.target_audience フィールドがある
• 対象読者の値が有効である — "ai"、"human"、"hybrid" のいずれか
• 指示の詳細度が対象読者に合っている — サンプルタスクをレビューして、次の内容を確認する：
  • AI：実装手順、TDD チェックリスト、明示的な制約、ドリフトポリシーが含まれている
  • 人間：目標、スタイルの手がかり、主要な要件、成功基準のみが含まれている
  • ハイブリッド：目標、スタイルの手がかり、実装方法、検証ガイダンスが含まれている
• タスク間で一貫性がある — すべてのタスクが同じ詳細度に従っている

タスクの概要

• task_summaries セクションがある — 各 milestone-m*.tasks.yaml の先頭に含まれている
• すべてのタスクに概要がある — tasks 配列内のすべてのタスク ID に対応する項目がある
• 概要が簡潔である — 20～300 文字で、通常は 1～2 文
• 平易な英語である — 技術用語や実装の詳細ではない
• 能動態である — "X を作成する" であり、"X が作成される" ではない
• 方法ではなく、何を／なぜに焦点を当てている
• 概要をざっと把握できる — 概要だけを読んでも、マイルストーンの範囲が分かる

スタイルの手がかり

• スタイルの手がかりが 2～3 個含まれている — 各マイルストーンのタスクファイル
• 具体的なファイルパスがある — 抽象的な説明ではない
• 具体的な行番号が記載されている
• 完全な例がある — 該当する場合、コード＋テスト＋README
• 現在のベストプラクティスを反映したパターンである
• 明確な説明がある — 例が示すパターンを説明している

タスクの規模（task-sizing.md に基づく）

• タスクごとに最低 30 分 — それより短い場合は理由を記載する
• ほとんどのタスクで最適な範囲は 30～150 分
• 最大 150 分（2.5 時間） — 超える場合は分割する
• 対象ファイルの範囲が限定されている — 1～3 ファイルが望ましく、5 ファイル超の場合は正当な理由が必要
• 各タスクの成果物が明確である
• 受け入れテストが定義されている

TDD の要件（AI 向けのみ）

• コードタスクに TDD チェックリストが含まれている — AI のみ
• テストファーストのアプローチが指定されている — AI のみ
• 検証コマンドが示されている — AI／ハイブリッド：明示的に記載、人間：一般的なガイダンス
• 期待される出力が記載されている — AI のみ
• テスト失敗時にテストを変更することが禁止されている — AI のみ

人間／ハイブリッド向けの場合は、規範的な TDD チェックリストを使わずに、成功基準にテスト要件が含まれていることを確認してください。

肯定的な指示

• 許可されている操作が明示されている（例：「X、Y、Z のみを使用する」）— AI／ハイブリッドのみ
• 制約が明確で実行可能である — すべての対象読者

ドリフト防止（AI 向けのみ）

• タスクの指示にドリフトポリシーが明記されている — AI 向けのみ
• 停止基準が明確である（予期しない依存関係、ファイル範囲の違反） — AI 向けのみ
• 差し戻しの指示が提示されている — AI 向けのみ
• インシデントの記録手順が指定されている — AI 向けのみ
• 許容される逸脱（フォーマット、空白）が理解されている — AI 向けのみ

人間／ハイブリッド向けの場合も制約は明確にする必要がありますが、明示的なドリフトポリシーは不要です。

品質ゲート

• コミット前フックが定義されている
• タスクごとに検証コマンドが指定されている
• 成功基準が測定可能である
• 失敗時の対応が文書化されている

プロンプトの配置

• タスクの指示の冒頭に重要な仕様がある
• タスク定義の早い段階にスタイルの指針がある
• 厳格なルールが末尾で再度示されている
• 要件が途中に埋もれていない

フェーズ 3：ドリフトポリシーへの準拠

埋め込まれたドリフトポリシーに照らして確認します。

停止・差し戻し基準の網羅性

タスクに次のガイダンスが含まれていることを確認します。

• 新しい依存関係の検出 — 未承認の依存関係を特定する方法
• ファイル範囲の違反 — 予期しないファイルが 3 件を超えて変更された場合の対応
• リンティング／型エラー — 解決できないエラーへの対応
• テストの失敗 — 実装を変更する場合と修正する場合の方針

即時対応の文書化

• 停止の指示が明確である — 「直ちに停止」という表現を使用している
• エラーメッセージの形式 — 逸脱を要約する方法
• 差し戻しの手順 — 差し戻すタイミングと方法
• インシデント記録の場所 — 記録先（docs/drift-incidents/）

学習内容の記録

• ルールの更新手順が記載されている
• 更新先（.cursor/rules/, CLAUDE.md）

許容される逸脱

• 軽微なフォーマット変更 — 許容されることを理解している
• 空白の編集 — レビューなしで許可される
• 1 行のリファクタリング — 範囲内で、型チェック済みである

フェーズ 4：タスクの規模分析

埋め込まれたタスク規模のガイドラインに照らして確認します。

所要時間の準拠

レポートを生成します。

task_sizing_report:
  total_tasks: [count]
  by_duration:
    too_small:  # < 30m
      - task_id: [id]
        estimate_minutes: [n]
        rationale: [why small]
        recommendation: [merge or accept]
    optimal:    # 30-150m
      count: [n]
      percentage: [%]
    too_large:  # > 150m
      - task_id: [id]
        estimate_minutes: [n]
        recommendation: [split into X, Y, Z]

ファイル範囲の分析

• 1～3 ファイルが望ましい
• 5 ファイル超の場合は正当な理由を示すか、分割する
• 各タスクに明示的なファイル一覧がある
• 変更のみのファイルが明確に示されている

タスク分解の品質

• 有用な最小限の成果物が定義されている
• タスクごとに明確な受け入れテストがある
• サンプルファイルが用意されている
• 各タスクの後にコミットする方針がある

大規模タスクの検出

分解が必要なタスクを特定します。

decomposition_needed:
  - task_id: [id]
    current_estimate: [minutes]
    suggested_split:
      - name: [subtask 1]
        estimate: [minutes]
      - name: [subtask 2]
        estimate: [minutes]
      - name: [subtask 3]
        estimate: [minutes]

フェーズ 5：完全性の確認

マイルストーンの構成

• すべてのマイルストーンに一意の ID がある
• 名前が明確で内容を表している
• 説明に成果物が記載されている
• 依存関係が正しい順序で並んでいる
• 循環依存がない
• 見積もり時間が現実的である
• タスクファイルが正しく参照されている
• 成功基準をテストできる

タスクの内訳

• すべてのタスクに一意の ID がある
• タスク名が内容を表している
• 説明が明確で実行可能である
• 見積もりが規模のルールに従っている
• 種別（コード／テスト／ドキュメント／設定）が指定されている
• 依存関係が明示され、正しい
• ファイル一覧が完全かつ正確である
• 指示が詳細で明確である

タスクの品質

• 目標が明確に記載されている
• 実装手順に番号が付けられている
• 制約が明示されている
• TDD チェックリストが含まれている（コードタスク）
• 検証コマンドが提示されている
• 期待される出力が文書化されている
• ドリフトポリシーが明記されている

フェーズ 6：整合性の確認

ビジネス要件（提示されている場合）

• すべての機能要件がタスクに割り当てられている
• 優先度がビジネス上の優先順位と一致している
• MVP の範囲が明確に定義されている
• 成功基準でビジネス目標を検証できる

網羅性マトリックスを生成します。

business_requirement_coverage:
  FR-1: [task-ids]
  FR-2: [task-ids]
  FR-3: [gap]  # Not covered

技術要件（指定されている場合）

• アーキテクチャ上の決定が反映されている
• 技術選定が遵守されている
• テスト戦略が実装されている
• セキュリティ要件に対処している
• パフォーマンス要件を考慮している

カバレッジマトリクスを生成します：

technical_requirement_coverage:
  architecture:
    - decision: [description]
      enforced_in: [task-ids]
  technology:
    - choice: [description]
      enforced_in: [task-ids]

フェーズ 7：依存関係の分析

クリティカルパス

• クリティカルパスが特定されている
• 所要時間が算出されている
• 並行して実施できる機会が記載されている
• 不要な依存関係が削除されている
• 依存関係が必要最小限かつ十分である

依存関係グラフを生成します：

dependency_analysis:
  critical_path:
    - [milestone-id]
    - [milestone-id]
  critical_path_duration: [time]
  
  parallel_opportunities:
    - can_parallelize: [[m1, m2], [m3, m4]]
      time_saved: [duration]
  
  dependency_issues:
    - task: [id]
      issue: [description]
      recommendation: [fix]

循環依存関係の確認

• マイルストーン間に循環依存関係がない
• タスク間に循環依存関係がない
• 依存関係グラフが DAG である

フェーズ 8：不足事項の特定

よくある不足事項

• インフラストラクチャ関連のタスクが含まれている（セットアップ、ツール）
• テストタスクが含まれている
• ドキュメント作成タスクが含まれている
• エラー処理タスクが含まれている
• 設定タスクが含まれている
• デプロイ／リリースタスクが含まれている
• 前提事項が文書化されている
• 新しいパターンのスタイルアンカーがある
• ファイルの境界が明確である
• コンポーネント間の統合タスクが含まれている

不足事項レポートを生成します：

gaps:
  missing_task_types:
    - type: [infrastructure/tests/docs/etc]
      importance: [high/medium/low]
      recommendation: [description]
  
  missing_requirements_coverage:
    - requirement: [id]
      category: [functional/non-functional]
      impact: [high/medium/low]
  
  undocumented_assumptions:
    - task: [id]
      assumption: [description]
      recommendation: [document explicitly]

ワイヤーフレームのカバレッジ（ソフトゲート）

タスクで .tsx／.jsx／.vue／.svelte ファイルが参照されている場合、または UI コンポーネント（フォーム、テーブル、ナビゲーション、モーダル、ページ、レイアウト）に言及している場合：

• ux/wireframe-spec.yaml が存在するか？
• UI タスクがあるすべてのページにワイヤーフレームのエントリーがあるか？
• 検出されたすべてのコンポーネントがワイヤーフレーム仕様に記載されているか？
• 主要なインタラクションのユーザーフローが文書化されているか？

これは WARN レベルのゲート（CRIT ではありません）です。 進行を妨げるものではありません。

ワイヤーフレームがない、または不完全な場合は、レビュー出力に次を追加します：

wireframe_coverage:
  ui_tasks_detected: [count]
  wireframe_spec_exists: [true/false]
  missing_pages:
    - page: [name]
      tasks: [task-ids]
  recommendation: "Consider running Step 6 (UX/Wireframe Planning) before development"

ユーザーには次のように表示されます：

「WARN-001：[n] 件の UI タスクにワイヤーフレームのカバレッジがありません。開発前にステップ 6 を実行することを検討してください。このまま続行しますか？（yes/no）」

フェーズ 9：スタイルアンカーの検証

• アンカーが既存のファイルを参照している（リポジトリが利用可能な場合）
• 行番号が正確である（検証可能な場合）
• パターンが正しく示されている
• 説明が役に立つ
• 新しい各パターンに十分なアンカーがある
• テストのアンカーが含まれている
• 該当する場合、README のアンカーが含まれている

フェーズ 10：品質ゲートの検証

• リンターのコマンドが指定されている — AI：明示的、 Human/Hybrid：一般的
• 型チェッカーのコマンドが指定されている — AI：明示的、 Human/Hybrid：一般的
• テストのコマンドが指定されている — AI：明示的、 Human/Hybrid：一般的
• コマンドを実行できる（指定されている場合）
• 期待される出力が定義されている — AI のみ
• 失敗時の処理が文書化されている — AI のみ

Human/Hybrid の対象者については、明示的なコマンド文を必須とせず、テスト／リンター／型チェックの実行に言及した成功基準があることを確認します。

レビュー出力

包括的なレビュー報告書を implementation-plan-review.yaml として生成します。

出力ドキュメントには、metadata（計画ファイル、レビュー日）、overall_scores（構造、ベストプラクティス、タスクの規模、完全性、整合性、開発準備度。それぞれ 1〜10）、critical_issues、high_priority_issues、medium_priority_issues、best_practices_violations（カテゴリ別）、gaps、strong_areas、optimization_opportunities、specific_recommendations、readiness_assessment が含まれます。

すべてのフィールド、問題 ID（CRIT-NNN／WARN-NNN／INFO-NNN）、採点基準を含むドキュメントの完全な仕様については、references/output-spec.md を参照してください。

完全な例については、references/example.yaml を参照してください。

使用方法

実装計画をレビューします：

/implementation-plan-review path/to/milestones.yaml

このスキルは次の処理を行います：

1. すべてのマイルストーンとタスクのファイルを読み込みます
2. 構造とスキーマを検証します
3. すべてのベストプラクティスへの準拠状況を確認します
4. タスクの規模と依存関係を分析します
5. 不足事項と問題を特定します
6. 包括的なレビュー報告書を生成します
7. 具体的な推奨事項を提示します

出力ファイル

以下を生成します。

• implementation-plan-review.yaml - 包括的なレビュー報告書
• task-sizing-analysis.yaml - 詳細なタスク規模の分析
• requirement-coverage.yaml - 要件とタスクの対応表
• dependency-graph.yaml - マイルストーンとタスクの依存関係

ベストプラクティスの参照

このスキルは、ベストプラクティスを直接組み込み、適用します。

1. 実装計画のベストプラクティス

基本原則：

モデルは局所的な最適化を行います。階層化された検証（プロンプト → IDE → コミット → CI → 実行時）によって、全体的な制約を適用します。

主なプラクティス：

• スタイルの基準： 正確なパスと行番号を示した、テンプレートとなる優れたファイルを常に2～3個含めます。具体的なリポジトリ内の例（コード＋テスト＋README）を優先します。早い段階で基準を適用し、アーキテクチャの逸脱を防ぎます。
• タスクの規模： 作業を30分～2.5時間の個別タスク（最適な範囲は30～150分）に分割します。対象を特定のファイルに限定します。各小タスクの完了後にコミットします。逸脱が生じたら、直ちに元に戻します。タスクが30分未満の場合は、見積もりを増やすか、理由を明記して分割します。
• 肯定的な指示： 許可する操作を明示します（例：「X、Y、Zのみを使用してください」）。否定的な表現は避けます。
• 階層化されたルール： グローバル（ユーザー設定）、プロジェクト（CLAUDE.md または .cursor/rules/ に永続的に記述）、コンテキスト対応（ディレクトリ／ファイルごと）。
• TDDを基準にする： 実装前にTDDチェックリスト（テスト → 最小限のコード → 追加のテスト → リファクタリング）を必須にします。テストが失敗した場合は、失敗した出力とともに、次の指示を返します。「以前に合格したすべてのテストを維持しながら、このテストに合格するよう実装を修正してください。テストは変更しないでください。依存関係を追加しないでください。」
• 逸脱への対処： 予期しない依存関係や見慣れないパターンがあった場合は、直ちに停止して元に戻します。作業の途中で修正しないでください。各セッション後に学んだことを記録し、永続的なルールを更新します。
• プロンプト内の配置： 重要な仕様、スタイルの基準、厳守すべきルールはプロンプトの冒頭に置き、最後にも繰り返します（要件を途中に埋もれさせないでください）。
• 外部データの検証： 外部データに対する型アサーションは決して使用しないでください。すべての外部入力を適切なエラー処理と検証によって検証します。

IDE／リンティング：

• 厳格なリンティングを適用します（go vet、golangci-lint、gofmt）
• レース検出を有効にしてテストを実行します
• 警告ゼロの方針

品質ゲート：

• コミット前：警告ゼロで make lint と make test を実行
• CI：違反数をカウントし、しきい値を超えた場合は失敗させる

2. 逸脱ポリシー

目的： モデルの編集がプロジェクトルールから逸脱した場合に、停止、元に戻す、記録するタイミングを定めます。

停止と元に戻す基準：

• 許可されたスタックに記載されていない新しい依存関係をモデルが導入した
• 指定された対象外のファイルが編集された（予期しないファイルが3個を超える）
• タスクの範囲内で解決できないリンティングエラーまたは型エラーが発生した
• テストが失敗し、モデルが合格させるためにテストの変更を提案した

直ちに行うこと：

1. モデルのセッションを停止し、逸脱の概要を示す明確なエラーメッセージを返す
2. 作業領域をタスク開始前の状態に戻す（適切な場合はgitを使用）
3. docs/drift-incidents/ にインシデント記録を作成する。記録には、発生したこと、変更されたファイル、新しい依存関係、是正手順を含める

学んだことの記録：

• 解決後、再発を防ぐために .cursor/rules/ または CLAUDE.md を新しいルールで更新する

許容される逸脱：

• 軽微なフォーマット変更（エディター設定）または空白のみの編集
• 対象ファイル内で、範囲内にあり型チェック済みの1行のリファクタリング

レビューと承認：

• 再実行の前に、元に戻す操作またはインシデント記録を人間のメンテナーがレビューする必要があります

3. タスクの規模設定に関するガイダンス

目的： モデルが指示に従って行う作業を予測可能でレビューしやすい単位に保ち、逸脱や想定外のスコープ拡大を抑えます。

ガイドライン：

• タスクの所要時間の目安：30分～2.5時間
• 可能な限り、変更対象を1～3ファイルに限定します
• 変更対象が5ファイルを超える場合、または所要時間が2.5時間を超える場合は、タスクを小さく分割します

プロセス：

1. 最小限で有用な成果物と、明確な受け入れテストを定義します
2. サンプルファイルと編集する正確なパスを提示します
3. 各タスクの完了後にテストを実行し、明確なメッセージを付けてコミットします

大規模タスクの分割：

• 次のように分解します：（a）テストと足場作り、（b）最小限の実装、（c）リファクタリングと仕上げ
• サブタスクと受け入れ基準を列挙した計画メモを作成します

例：

• 小規模：src/utils/parse.ts のバグ修正 — 30～60分
• 中規模：テスト付きで新しい API エンドポイント src/server/user.ts を追加 — 1～2.5時間
• 大規模：認証システムの移行 — 設計と段階的な PR に分割

意思決定の支援

レビュー後、推奨事項を提示します。

重大な問題が見つかった場合

「開発を妨げる重大な問題が [n] 件見つかりました。

1. [重大な問題 1]
2. [重大な問題 2]

推奨事項： 開発を始める前に、これらの問題を修正してください。

次のどれを選びますか？

1. 今すぐ問題を修正する（影響を受けるタスクを再生成します）
2. 問題を手動で確認する
3. 問題を認識したうえで進める（推奨しません）」

優先度の高い問題が見つかった場合

「対処すべき優先度の高い問題が [n] 件見つかりました。

1. [問題 1]
2. [問題 2]

推奨事項： 開発前、またはマイルストーン0の早い段階で対処してください。

次のどれを選びますか？

1. 今すぐ対処する（計画を更新します）
2. マイルストーン0での対応事項として記録する
3. 先に進み、必要に応じて対処する」

修正を加えれば準備が整う場合

「計画はおおむね準備できていますが、[n] 件の改善を推奨します。

優れている点：

• [計画がよくできている点]

推奨する改善：

• [改善点 1]
• [改善点 2]

スケジュールへの影響： [見積もり]

次のどれを選びますか？

1. 今すぐ改善を適用する
2. 実装時の対応事項として記録する
3. 現状のまま開発を始める」

開発の準備が整っている場合

「実装計画は開発を始められる状態です！

強み：

• [優れている点]
• [順守されているベストプラクティス]

軽微な最適化の機会：

• [最適化の機会 1]
• [最適化の機会 2]

推定所要期間： [期間] クリティカルパス： [期間]

安心して開発を始められます。」

統合

このスキルは、次のものと連携します。

• implementation-planner - このスキルが生成した計画をレビューします
• business-requirements-interview - ビジネスニーズとの整合性を検証します
• technical-requirements-interview - 技術仕様の網羅性を検証します

例

レビュー出力の完全なサンプルは、references/example.yaml を参照してください。