blueprint-derive-tests

/blueprint:derive-tests

Git の履歴を分析して、対応するテストの変更がない修正コミットと機能コミットを特定し、優先順位付きテストバックログとして構造化されたテスト回帰計画（TRP）ドキュメントを生成します。

ユースケース：回帰テストなしでリリースされたバグ修正や機能をコミット履歴から抽出し、テストカバレッジの不足を体系的に解消します。

このスキルを使用する場面

このスキルを使用する場面	代替手段を使用する場面
バグ修正が回帰テストなしでリリースされている	既存のテストを実行する必要がある（/test:run）
履歴から優先順位付きのテストバックログを作成したい	特定の機能のテストを作成する（手動の TDD）
プロジェクトに参加し、テストの健全性を評価する	現在のテストカバレッジ指標を確認する
どの修正にテストカバレッジがないかを調べたい	テスト戦略を一から設計する（/test:architecture）

コンテキスト

• Git リポジトリ：!git rev-parse --git-dir
• Blueprint の初期化状態：!find . -path '*/docs/blueprint/*' -maxdepth 3 -name 'manifest.json' -type f
• コミット総数：!git rev-list --count HEAD
• テストフレームワーク：!find . -maxdepth 3 \( -name 'vitest.config.*' -o -name 'jest.config.*' -o -name 'pytest.ini' -o -name 'pyproject.toml' -o -name 'Cargo.toml' -o -name 'go.mod' \) -type f -print -quit
• テストファイル：!find . -maxdepth 4 -type f \( -name '*.test.*' -o -name '*.spec.*' -o -name 'test_*' -o -name '*_test.*' \) -print
• Conventional Commits のサンプル：!git log --format="%s" --max-count=10

パラメーター

$ARGUMENTS から次の項目を解析します。

• --quick：高速スキャン（直近 50 件のコミットのみ）
• --since DATE：指定した日付以降のコミットを分析します（例：--since 2024-06-01）
• --scope AREA：特定の領域／スコープに関係するコミットに絞り込みます（例：--scope auth）

フラグを指定しない場合のデフォルト動作：直近 200 件のコミットを分析します。

詳細なテンプレート、重大度マトリクス、テストのマッピング規則については、REFERENCE.md を参照してください。

実行

次のテスト回帰計画導出ワークフローを実行します。

Step 1：前提条件を確認する

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

1. Git リポジトリが空の場合 → エラー：「This directory is not a git repository. Run from project root.」
2. コミット総数が "0" の場合 → エラー：「Repository has no commit history.」
3. Blueprint の初期化状態が空の場合 → ユーザーに確認します：「Blueprint not initialized. Initialize now (Recommended) or continue without manifest tracking?」
   • 「Initialize now」の場合 → Task ツールを使用して /blueprint:init を呼び出し、その後続行します
   • 「Continue without」の場合 → Step 7 でマニフェストの更新をスキップします

Step 2：分析範囲を決定する

$ARGUMENTS から --quick、--since、--scope を解析します。

1. --quick の場合 → 範囲 = 直近 50 件のコミット
2. --since DATE の場合 → 範囲 = DATE から現在までのコミット
3. --scope AREA の場合 → AREA に一致するスコープを持つコミット、または AREA ディレクトリ内のファイルを変更したコミットに絞り込みます
4. それ以外の場合 → 範囲 = 直近 200 件のコミット

後続の手順で使用する git log コマンド用に、範囲パラメーターを保存します。

Step 3：テスト基盤を検出する

テストフレームワークと規約をスキャンします。

1. コンテキストからテストフレームワークを特定します（vitest、jest、pytest、cargo test、go test）
2. テストファイルの命名規則を検出します。
   • *.test.ts、*.spec.ts（JS/TS）
   • test_*.py、*_test.py（Python）
   • *_test.rs、tests/ ディレクトリ（Rust）
   • *_test.go（Go）
3. ソースディレクトリとテストディレクトリを対応付けます（例：src/ → tests/、src/ → src/__tests__/）
4. Step 5 で使うフレームワーク、命名パターン、ディレクトリの対応関係を記録します

テストフレームワークを検出できない場合 → ユーザーに警告し、ファイルベースの検出のみで続行します。

Step 4: コミットを分類し、カバレッジの不足を検出する

ヘルパーを実行します。分類の決定的な処理を担い、git log から fix:／feat: コミットを分類し、各コミットにテストファイルの変更が含まれていたかを検出（git show --name-only）して、固定マトリックスに基づいて重大度を割り当てます（fix: + インラインテストなし → CRITICAL、feat: + インラインテストなし → MEDIUM、テストを含むコミット → COVERED）。スキャン数を制限するには --limit を指定します（デフォルトは 200、--quick の場合は --limit 50 を指定します）。

bash "${CLAUDE_SKILL_DIR}/scripts/blueprint-derive-tests.sh" --home-dir "$HOME" --project-dir "$(pwd)"

出力から STATUS= と ISSUES: を解析します。FIX_COMMITS／FEAT_COMMITS は分類された件数、GAPS_CRITICAL／GAPS_MEDIUM／GAPS_TOTAL はカバレッジの不足件数です。各 coverage_gap issue には、TRP テーブルに使用する SHA=、TYPE=、SEVERITY=、SUBJECT= が含まれます。STATUS=ERROR は、CRITICAL（テストされていない修正）の不足が少なくとも 1 件あることを意味します。

スクリプトのインラインテスト検出と基本重大度（CRITICAL／MEDIUM）は、決定的な最低基準です。より詳細な High／Low の分類、近接するテストコミットによる重大度の緩和、または言語ごとのソースとテストの対応付けが必要な場合は、REFERENCE.md の補正ルールと、REFERENCE.md の対応付けルールを適用します。--since／--scope で絞り込む場合は、REFERENCE.md のコマンドで git の対象範囲を絞り込んでから、不足の一覧を確認します。

Step 6: TRP ドキュメントを生成する

TRP は docs/trps/ の最上位に配置します。docs/blueprint/trps/ ではありません。これは、同階層にある derive-* スキルの最上位レイアウトに合わせたものです。TRP を docs/blueprint/ 以下に作成してはいけません。このパスは Blueprint の仕組み専用です。

1. 出力ディレクトリを作成します：mkdir -p docs/trps
2. TRP ID を決定します：
   • マニフェストが存在する場合は、id_registry.last_trp を読み取り、1 を加算します
   • それ以外の場合は TRP-001 から開始します
3. 対象範囲または日付範囲からスラッグを生成します（例：regression-gaps-2024-q3）
4. REFERENCE.md のテンプレートを使って、TRP ドキュメントを docs/trps/{slug}.md に書き込みます

ドキュメントには以下を含めます：

• id、status: Active、scope、date_range、commits_analyzed を含む YAML フロントマター
• 重大度別の不足件数を示すエグゼクティブサマリー
• 詳細な不足テーブル：コミット SHA、件名、重大度、影響を受けるファイル、推奨テストタイプ
• 推奨するテスト作成順（まず Critical、次に High など）
• 不足ごとの推奨テストタイプ（REFERENCE.md を参照）

Step 7: マニフェストを更新する

Blueprint が初期化されている場合：

1. id_registry.last_trp を新しい TRP 番号に更新します
2. id_registry.documents にドキュメントを登録します：

   {
     "TRP-NNN": {
       "path": "docs/trps/{slug}.md",
       "title": "{TRP title}",
       "status": "Active",
       "created": "{date}"
     }
   }
   

3. タスクレジストリを更新します：

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

Step 8: 結果を報告し、次のアクションを提案する

概要を出力します：

Test Regression Plan Generated!

**Analysis Summary**
- Commits analyzed: {N} ({date_range})
- Fix commits found: {N}
- Feature commits found: {N}

**Coverage Gaps Found**
- Critical: {N} (fix commits with no tests at all)
- High: {N} (fix commits with stale test files)
- Medium: {N} (feature commits missing tests)
- Low: {N} (feature commits with nearby tests)

**Document**: docs/trps/{slug}.md (TRP-{NNN})

**Top Priority Gaps**
1. {commit subject} — {severity} — {affected file}
2. {commit subject} — {severity} — {affected file}
3. {commit subject} — {severity} — {affected file}

次のアクションをユーザーに確認します：

• 「優先度の高い不足に対する PRP を作成（推奨）」— Critical／High の不足に対する PRP ドキュメントを生成します
• 「TRP ドキュメントを確認」— 生成した TRP を開いて手動で確認します
• 「異なる対象範囲で再実行」— --since または --scope を指定して再実行します
• 「今回は終了」— ドキュメントを保存して終了します

エージェント向けの最適化

コンテキスト	コマンド
Fix コミットのみ	git log --format="%H %s" | grep -E "^[a-f0-9]+ fix"
コミット内のテストを確認	git diff-tree --no-commit-id --name-only -r {SHA} | grep -E "test|spec"
変更されたファイル	git diff-tree --no-commit-id --name-only -r {SHA}
高速スキャン	直近 50 件のコミットには --quick を使用します
対象範囲で絞り込み	特定の領域に限定するには --scope auth を使用します

---

詳細なテンプレート、重大度分類マトリックス、テスト対応付けルール、エラー処理については、REFERENCE.md を参照してください。