blueprint-derive-plans

/blueprint:derive-plans

既存プロジェクトの Git 履歴、コードベースの構造、既存ドキュメントを分析し、Blueprint ドキュメント（PRD、ADR、PRP）を遡って生成します。

ユースケース：PRD／ADR／PRP ドキュメントは存在しないものの、実装履歴がある既存プロジェクトを Blueprint Development システムにオンボーディングします。

このスキルを使用するタイミング

次の場合にこのスキルを使用します…	次の場合は代替手段を使用します…
プロジェクトに Git 履歴はあるものの、PRD／ADR／PRP がない	履歴のないまっさらなプロジェクトを開始する
既存プロジェクトを Blueprint にオンボーディングする	ユーザーのガイダンスを受けながら新しい PRD を一から作成する
コミット履歴から機能を抽出する必要がある	従来のコミット形式や明確な履歴がない
アーキテクチャ上の決定を遡って記録する	決定がすでに完全に文書化されている

コンテキスト

• Git リポジトリ：!git rev-parse --git-dir
• Blueprint の初期化状態：!find . -path '*/docs/blueprint/*' -maxdepth 3 -name 'manifest.json' -type f
• コミット総数：!git rev-list --count HEAD
• 最初のコミット：!git log --reverse --format=%ai --max-count=1
• 最新のコミット：!git log --max-count=1 --format=%ai
• プロジェクトの種類：!find . -maxdepth 1 \( -name 'package.json' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' -o -name 'pom.xml' \) -type f -print -quit
• ドキュメントファイル：!find . -maxdepth 2 \( -name "README.md" -o -name "ARCHITECTURE.md" -o -name "DESIGN.md" \)

パラメーター

$ARGUMENTS から次の内容を解析します。

• --quick：簡易スキャン（直近 50 件のコミットのみ）
• --since DATE：指定した日付以降のコミットを分析します（例：--since 2024-01-01）

フラグを指定しない場合のデフォルトの動作：標準分析（直近 200 件のコミットとスコープの推定）。

詳細なテンプレート、マニフェスト形式、レポート例については、REFERENCE.md を参照してください。

実行

次の遡及的なドキュメント生成ワークフローを実行します。

ステップ 1：前提条件を確認する

上記のコンテキスト値を確認します。

1. Git リポジトリ = "NO" の場合 → エラー："このディレクトリは Git リポジトリではありません。プロジェクトのルートから実行してください。"
2. コミット総数 = "0" の場合 → エラー："リポジトリにコミット履歴がありません"
3. Blueprint の初期化状態 = "NO" の場合 → ユーザーに確認します："Blueprint が初期化されていません。今すぐ初期化（推奨）しますか、それとも最小限のインポートのみ行いますか？"
   • 「今すぐ初期化」の場合 → Task ツールを使用して /blueprint:init を呼び出し、このステップ 1 を続行します
   • 「最小限のインポートのみ」の場合 → 最小限のディレクトリ構造を作成します：mkdir -p docs/prds docs/adrs docs/prps

ステップ 2：分析範囲を決定する

$ARGUMENTS に含まれる --quick または --since を解析します。

1. --quick フラグがある場合 → 範囲 = 直近 50 件のコミット
2. --since DATE がある場合 → 範囲 = DATE から現在までのコミット
3. それ以外の場合 → ユーザーに選択肢を提示します。
   • 簡易スキャン（直近 50 件のコミット）
   • 標準分析（直近 200 件のコミット）
   • 全履歴の分析（すべてのコミット）
   • カスタムの日付範囲

選択した範囲を、以降のすべての Git 分析に使用します。

ステップ 3：Git 履歴の品質を分析する

対象範囲のコミットについて、次の内容を計算します。

1. コミット総数を数える：git log --oneline {scope} | wc -l
2. Conventional Commits の数を数える：git log --format="%s" {scope} | grep -cE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)\(?.*\)?:" || echo 0
3. 割合を計算し、品質スコアを割り当てます（REFERENCE.md を参照）。

次のように報告します："Git 履歴の品質：{score}/10（Conventional Commits の割合：{percentage}%）"

ステップ 4：機能とアーキテクチャ上の決定を抽出する

REFERENCE.md の手法を使用します。

1. Conventional Commit のスコープから機能の境界を抽出します
2. アーキテクチャ上の決定を特定します（マイグレーション、主要な依存関係、破壊的変更）
3. イシューへの参照と今後の作業項目（TODO、スキップされたテスト）を見つけます
4. Git タグからリリースの境界を特定します

ユーザーに確認してもらうため、調査結果を構造化された形式でまとめます。

ステップ 5：コードベースと既存ドキュメントを分析する

1. Explore エージェントを使ってアーキテクチャを分析します。ディレクトリ構造、コンポーネント、フレームワーク、パターン、エントリーポイント、データレイヤー、API レイヤー、テスト構造を確認します
2. マニフェストファイル（package.json、pyproject.toml、Cargo.toml、go.mod など）から依存関係を抽出します
3. 既存のドキュメント（README.md、docs/、ARCHITECTURE.md、DESIGN.md、CONTRIBUTING.md）を読み、内容を抽出します
4. 今後の作業を検出します。コード内の TODO、未解決の GitHub イシュー、スキップされたテストを確認します

ステップ 6：ユーザーにプロジェクトの背景を確認する

AskUserQuestion を使って確認事項を質問します。質問テンプレート全体 （問題の説明、対象ユーザー、プロジェクトのフェーズ、ステークホルダーの規模）については、 REFERENCE.md を参照してください。

1. プロジェクトの目的（README から明確でない場合）：推測した説明を提示して確認するか、ユーザーに説明を求めます
2. 対象ユーザー：開発者、エンドユーザー、または両方 — PRD の構成に反映されます
3. プロジェクトのフェーズ：MVP／開発中／メンテナンス／大規模な変更の計画中 — 機能と安定性のどちらを重視するかを決めます
4. ステークホルダー：規模（個人／小規模チーム／大規模組織／OSS コミュニティ）→ PRD のステークホルダーマトリクスの詳細度を決めます（REFERENCE.md を参照）
5. 機能の確認：git から抽出した {N} 個の機能を提示し、確認と優先順位付けを依頼します
6. アーキテクチャの根拠：特定した各決定について、主な判断要因を質問します
7. 生成の確認：以下の概要を提示し、生成を開始してよいか尋ねます

確認の際は、以下を提示します。

• Git 履歴の品質：{score}/10
• 特定した機能：{N} 個
• アーキテクチャ上の決定：{N} 件
• 今後の作業項目：{N} 件
• 作成予定のドキュメント：PRD（ステークホルダーマトリクスを含む）、{N} 件の ADR、{N} 件の PRP

ステップ 7：ドキュメントを生成する

ディレクトリ構造を作成します：mkdir -p docs/prds docs/adrs docs/prps

各ドキュメント種別について、REFERENCE.md のテンプレートとパターンを使います。

1. PRD を生成し、docs/prds/project-overview.md として保存します

   • REFERENCE.md のセクションと構成を使います
   • 抽出した機能を優先度と情報源とともに含めます
   • 各セクションに確信度スコアを付けます

2. ADR を生成し、docs/adrs/{NNNN}-{title}.md として保存します（決定ごとに 1 件）

   • REFERENCE.md の ADR テンプレートを使います
   • Git の根拠（コミット SHA、日付、変更されたファイル）を含めます
   • 確信度スコアを付けます
   • 競合と置き換えの確認：ADR の作成後、/blueprint:adr-relationships を実行して同じドメイン内の競合を検出し、/blueprint:adr-validate を実行して双方向の置き換えの整合性を確認します。 競合のスコアリングをここで再実装しないでください。スコアリングはこれらのスキルが担当します。

3. ADR インデックスを作成し、docs/adrs/README.md に保存します

   • すべての ADR をステータスと日付とともに表にまとめます
   • 新しい ADR 用の MADR テンプレートへのリンクを含めます

4. PRP を生成し、docs/prps/{feature}.md として保存します（今後の作業項目ごとに 1 件）

   • REFERENCE.md の PRP テンプレートを使います
   • 情報源への参照と確信度スコアを含めます
   • コードベースのパターンに基づいて実装を提案します

ステップ 8：マニフェストを更新して結果を報告する

1. docs/blueprint/manifest.json を更新し、インポートのメタデータ（タイムスタンプ、分析したコミット、確信度スコア、生成した成果物）を記録します

ステップ 8.5：生成したドキュメントに関する GitHub イシューの作成を提案する（任意）

生成した PRD（および任意で各 PRP）について、AskUserQuestion を使って 進捗管理用の GitHub イシューを作成するかどうかを尋ねます。プロンプトのテンプレートと gh issue create コマンドについては、REFERENCE.md を参照してください。ユーザーが承諾した場合：

1. タイトルを [{PRD-NNN}] {Project Name} としてイシューを作成します。
2. イシュー番号をドキュメントの github-issues frontmatter に追加します。
3. マニフェストの id_registry（documents[ID].github_issues と github_issues マップ）に記録します。

gh リモートが設定されていない場合、またはユーザーが辞退した場合は、何も通知せずにスキップします。

ステップ 9：タスクレジストリを更新する

docs/blueprint/manifest.json のタスクレジストリ項目を更新します。

jq --arg now "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --arg sha "$(git rev-parse HEAD 2>/dev/null)" \
  --argjson analyzed "${COMMITS_ANALYZED:-0}" \
  --argjson created "${DOCS_GENERATED:-0}" \
  '.task_registry["derive-plans"].last_completed_at = $now |
   .task_registry["derive-plans"].last_result = "success" |
   .task_registry["derive-plans"].context.commits_analyzed_up_to = $sha |
   .task_registry["derive-plans"].context.commits_analyzed_count = $analyzed |
   .task_registry["derive-plans"].stats.runs_total = ((.task_registry["derive-plans"].stats.runs_total // 0) + 1) |
   .task_registry["derive-plans"].stats.items_processed = $analyzed |
   .task_registry["derive-plans"].stats.items_created = $created' \
  docs/blueprint/manifest.json > tmp.json && mv tmp.json docs/blueprint/manifest.json

2. 次の内容を含むサマリーレポートを作成します：

   • 分析対象のコミットと日付範囲
   • Git の品質スコア
   • 生成したドキュメント（PRD、ADR の数、PRP の数）
   • レビューが必要なセクション（信頼度 < 7）
   • 推奨される次のステップ

3. 次のアクションをユーザーに尋ねます：

   • ドキュメントをレビューして改善する
   • PRD からプロジェクトルールを生成する
   • ワークフローコマンドを生成する
   • 終了する（ドキュメントは保存済み）

エージェントの最適化

コンテキスト	コマンド
git のステータスを確認	git rev-parse --git-dir 2>/dev/null && echo "YES" || echo "NO"
コミット数をカウント	git rev-list --count HEAD 2>/dev/null || echo "0"
Conventional Commits の数	git log --format="%s" | grep -cE "^(feat|fix|docs)" || echo 0
スコープを抽出	git log --format="%s" | grep -oE '\([^)]+\)' | sort | uniq -c
高速分析	直近 50 件のコミットのみを対象にするには --quick フラグを使用します

---

詳細なテンプレート、Git 分析パターン、ドキュメント生成例、エラー処理のガイダンスについては、REFERENCE.md を参照してください。