blueprint

Blueprint Skill

目的

共同で実装計画を作成し、成果物として記述します。すべてのステップで、構築・レビュー・検証のサイクルに従います。曖昧な機能リクエスト、アーキテクチャの変更、リファクタリングの目標を、人間またはエージェントが手順に沿って実行できる、具体的で順序立てられた計画に変換します。計画は対話として扱います。コードベースを調査し、ツールを確認し、質問し、アプローチを比較し、複雑さを評価したうえで、計画を生成します。

作業の労力レベル

タスクの複雑さに応じて調査の深さを調整しますが、常により徹底する方向を選んでください。範囲を絞り込む前に幅広く読み込みます。目標は、実行時に想定外の問題が一切発生しない計画です。

アンチパターン：「計画を立てるほどではない」

1行の変更であっても、どこに適用するのか、何に影響するのか、どのように検証するのかという前提が伴います。「単純な」タスクこそ、未検討の前提が無駄なやり直しを招きます。構築・レビュー・検証の構成によって、そうした前提が問題を広げる前に見つけられます。計画は、受け入れ基準を1つ設けた単一ステップでもかまいません。小規模な計画（≤2ステップ）向けの簡易手順では、すでにオーバーヘッドを最小限に抑えています。アンチパターンは計画の規模ではなく、計画そのものを省くことです。

設計原則

コードより文章

計画のステップでは、意図を文章で説明します。インターフェースのシグネチャ、設定キー、スキーマの形式を除き、コードブロックを含めないでください（ポリシーの全文は references/step-template.md を参照）。フェーズ3のチェックリストにあるツールコマンドは運用上の指示であり、コードではないため、常に使用できます。

ワークフロー

流れ： コードベースの調査 → ツールチェーンの確認（必須ゲート） → 要件の明確化（必須ゲート） → アプローチの提案 → 複雑さの評価 → 計画の生成 → 敵対的レビュー → 計画の完成。

計画の生成前に、2つの必須ゲートがあります。

1. ツール確認ゲート（ステップ1の後）：ツールチェーンのみを提示し、確認を待ちます。明確化の質問やほかの出力と組み合わせてはいけません。
2. 準備完了ゲート（ステップ1bの後）：明確化の過程で明らかになった、すべての重要な曖昧さを解消します。異なる解釈を採用すると計画の構成、ステップ数、または選択するアプローチが変わる曖昧さは、重要とみなします。

両方のゲートを通過せずに進めると、推測に基づく計画が作られてしまいます。

簡易手順のルール

限定的な変更（設定変更、単一ファイルのリファクタリング、単純な追加）を扱う2ステップ以下の計画は、簡易手順の対象となります。

• ツールの調査（ステップ1）： 発見したツールを、独立した確認ゲートではなく、生成した計画に含めて提示します。計画のヘッダーには、引き続きツールチェーンの表を含めてください。
• アプローチの提案（ステップ2）： 信頼できる戦略が1つしかない場合は、簡潔に説明して先へ進みます。無理に別の選択肢を作らないでください。
• 計画のレビュー（ステップ5）： サブエージェントへの依頼は省略します。受け入れ基準の漏れ、検証項目の不足、依存関係の問題がないか、簡単に自己レビューします。計画をそのまま提示し、ユーザーに実行を開始するか尋ねます。

3ステップ以上の計画、またはアーキテクチャ、複数のモジュール、横断的な懸念事項に触れる計画では、例外なく、すべてのステップで完全なワークフローに従ってください。

1. コードベースを調査し、ツールを特定する

まず、コードベースを広く読みます。以下を調べてください。

• プロジェクト構造（ディレクトリ、モジュール、パッケージ）。
• エントリーポイント（メインファイル、ルート定義、CLI コマンド）。
• データ層（モデル、スキーマ、マイグレーション、リポジトリ）。
• 設定（設定ファイル、環境変数、機能フラグ）。
• 既存のテスト（テスト構造、フィクスチャ、ファクトリー、カバレッジ）。
• ドキュメント（アーキテクチャドキュメント、ADR、セットアップ手順を記載した README）。

調査中に、プロジェクトのツールを特定してください。 ツールの特定は独立したフェーズではなく、コードベースの調査中に自然に行われます。設定ファイル、CI パイプライン、ロックファイルを確認しながら、それらから判明するテストランナー、リンター、フォーマッター、型チェッカー、パッケージマネージャーを記録してください。言語ごとの完全な参照表と検出方法については、references/tool-discovery.md を参照してください。CI パイプラインのコマンドと設定ファイルのコマンドが異なる場合は、実際に実行されるコマンドを反映している CI のコマンドを優先してください。

**このステップでは、ツールの確認のみを行います。それ以外は行いません。** 調査後、特定したツールチェーンをユーザーに提示し、確認を待ってください。この応答では、確認の質問をしたり、アプローチを提案したり、ほかの作業を行ったりしないでください。ツールチェーンの確認は必須のゲートです。ユーザーがツールを確認、追加、削除、または並べ替えてから、要件の明確化に進んでください。

ツールチェーンは、特定した根拠を括弧内に添えた番号付きリストで示してください。例：

Discovered tools for this project:

1. Package manager: uv (from uv.lock)
2. Test runner: pytest (from pyproject.toml [tool.pytest])
3. Linter: ruff check . (from pyproject.toml [tool.ruff])
4. Formatter: ruff format --check . (from pyproject.toml [tool.ruff.format])
5. Type checker: mypy . (from pyproject.toml [tool.mypy])

Add, remove, or reorder? (or confirm to proceed)

ファストパス： 2 ステップ以下の計画では、独立した確認ゲートを設けず、計画とともにツールを提示してください（「ファストパスのルール」を参照）。

1b. 要件を明確にする

ユーザーがツールチェーンを確認したら、要件を明確にする質問をしてください。以下を重視してください。

• ユーザーが実際に求めていること（ユーザーの言葉どおりとは限りません。意図が異なる場合があります）。
• コードからは把握できない制約。
• この作業の完了とみなす基準。
• この変更に対応すべき、関連する変更が予定されているかどうか。

理解を深めてください。これまでに得られた情報を要約し、不明点を示したうえで、追加の質問をしてください。重要度の高い計画では、2～3 回のやり取りを通じて要件を明確にするのが通常です。単純で明確なタスクであれば、1 回で十分な場合もあります。

計画に、図やアプローチの視覚的な比較が役立つアーキテクチャ上の判断が含まれる場合は、superpowers プラグインのビジュアルコンパニオンでブラウザー上に表示できます。この機能を使うには、superpowers プラグインがインストールされている必要があります。インストールされていない場合の代替手段はありません。

2. アプローチを提案する

タスクとツールが明確になったら、計画の構成を確定する前に、実装候補となるアプローチを 2～3 個提示してください。それぞれについて、1～2 文でアプローチを説明し、主なトレードオフ（何を優先するか、何を犠牲にするか、どのようなリスクがあるか）を示してください。まず推奨する戦略を提示し、その理由を説明してから、ユーザーが十分な情報をもとに選べるよう、ほかの選択肢を提示してください。複雑さの評価と計画の作成に進む前に、ユーザーがアプローチを選ぶのを待ってください。

ファストパス： 信頼できる戦略が 1 つしかない場合は、それを簡潔に述べて先に進んでください（「ファストパスのルール」を参照）。

3. 複雑さを評価する

アプローチを選択したら、計画の範囲を決定します。

• 想定されるステップ数を数えます。各ステップは、1つの論理的な作業単位を表す必要があります。些細な設定変更より大きく、機能全体より小さい単位にします。1文で説明できる場合は、隣接するステップと統合します。独自のサブ計画が必要な場合は、分割します。
• 自然なマイルストーンがあるかどうかを評価します（例：「まずデータレイヤー、次に API、最後に UI」）。
• ステップ数に基づいて出力形式を選択します。
  • 5ステップ以下で、単一の関心事：単一の計画ドキュメント。
  • 6～8ステップで、単一の関心事：見出しをグループ化した単一のドキュメント。
  • 明確なフェーズがある場合、または9ステップ以上の場合：マイルストーンごとに1ファイルを含むマイルストーンフォルダー。
  • 判断が曖昧な場合：ユーザーに尋ねます。

ステップの規模に関するガイダンス：

• 各ステップは独立して検証できる必要があります。今後のステップが完了していなくても、すべてのテストが通る必要があります。
• ステップは順次積み上がるようにします。後続のステップは先行するステップに依存してもかまいませんが、その逆は避けてください。
• 純粋に構造上の作業（「ディレクトリを設定する」など）は避けます。ただし、既存の構造がプロジェクトにない場合は除きます。構造上の作業は、最初の機能的なステップに含めます。

4. 計画を作成する

references/step-template.md で定義されている構成に従い、計画成果物を作成します。各ステップには、Build、Adversarial Review、Verification の3つのフェーズすべてを含めます。

計画のヘッダー：タイトル、日付、目標の概要、および確認済みのツールチェーンを記載します。

# Plan: [Feature/Change Title]

**Date**: YYYY-MM-DD
**Goal**: [1-2 sentence summary of what this plan achieves]

## Tool Chain

| Category | Tool | Command |
|---|---|---|
| Test runner | [discovered] | `[test command]` |
| Linter | [discovered] | `[lint command]` |
| Type checker | [discovered] | `[type-check command]` |
| Formatter | [discovered] | `[format command]` |

## Steps

[Steps follow here, each using the 3-phase template]

ステップ作成ルール：

• ステップには1から順に番号を付けます。
• 成果物を表す、明確で具体的なタイトルを付けます（「ユーザー認証エンドポイントを追加する」など）。作業内容を表すタイトル（「認証に取り組む」など）は避けます。
• 具体的でテスト可能な受け入れ基準を記載します。「コードがきれいである」「パフォーマンスが良好である」など、曖昧な基準は避けます。「95パーセンタイルの応答時間が200ms未満」「すべての検証エラーがフィールド単位のメッセージとともに422を返す」など、測定可能な条件を使います。
• フェーズ1（Build）では、文章優先のアプローチに従って、各作業の意図を記述します。作成、変更、テストする内容を指定します。該当する場合は、既存のコードパターンを参照します（「src/repos/product_repo.py で使用されているものと同じリポジトリパターンに従う」など）。
• フェーズ2（Adversarial Review）では、発生しやすい障害に焦点を当てた、そのステップ固有のレビュー質問を記載します。また、より広範な統合に関する質問も含めます。この変更は既存のコードベースに自然に適合しているか。確立された規約やパターンに従っているか。直接の対象範囲外の部分を破損させたり、品質を低下させたりする可能性はないか。レビューでは、受け入れ基準を確認するだけでなく、実施した作業を徹底的かつ批判的にコードレビューします。目的は、次に進む前に、Build フェーズで導入されたすべての問題を取り除くことです。
• フェーズ3（Verification）では、確認済みのツールチェーンのコマンドを含む完全なチェックリストを記載します。標準チェックに加えて、各ステップに固有の検証項目も追加します。

依存関係の追跡：あるステップが前のステップの成果物に依存する場合は、目的にその依存関係を明記します。例：「ステップ2（ユーザーリポジトリ）に依存します。そこで定義された UserRepository インターフェースを使用します。」

マイルストーンフォルダーの作成（該当する場合）：

• マイルストーンごとに1ファイルを作成します：01_milestone-name.md、02_milestone-name.md など。
• 各マイルストーンファイルは、同じ構成（ヘッダー、ツールチェーン、ステップ）に従います。
• 計画フォルダーのルートに README.md を追加し、マイルストーンを順番に並べて、それぞれを1文で説明します。
• 各マイルストーンは3～5ステップにします。それより多くなる場合は、分割します。

5. 敵対的な計画レビュー

計画をディスクに書き込んだ後、サブエージェントを割り当て、計画全体を敵対的な視点からレビューさせます。サブエージェントは計画コンテキストに引きずられることなく、ディスクから新たに計画を読み込みます。実行を始める前に弱点を見つけることだけを目的とする、批判的な第二の目として機能します。

サブエージェントを使う理由：計画を作成したエージェントは、自身の推論に引きずられています。計画時の会話履歴をすべて持たない新しいサブエージェントは、実行者の視点で計画を読み、作成者が見落としている曖昧さ、抜け、論理的な欠陥を見つけます。サブエージェントには、ユーザーの意図全体に計画が対応しているかを確認できるよう、簡潔な範囲の要約（下記の {{PLANNING_CONTEXT}} を参照）のみを渡します。計画時の会話全体は渡しません。

**簡易ルート：**ステップが2つ以下の計画ではサブエージェントを省略し、代わりに簡単なセルフレビューを行います（簡易ルートのルールを参照）。

レビューサブエージェントの割り当て：Claude Code の Agent ツールを使って、計画レビュー用サブエージェントを割り当てます。正確なプロンプトテンプレートについては references/plan-review-subagent.md を参照してください。割り当てる前にプレースホルダーを置き換えます。

• {{PLAN_PATH}} — 計画ファイルまたはマイルストーンフォルダーの絶対パス。
• {{PROJECT_ROOT}} — プロジェクトルートの絶対パス。
• {{PLANNING_CONTEXT}} — 次の内容を5～10文で簡潔にまとめます。ユーザーが最初に依頼した内容、確認のやり取りで決定した主な制約と判断、合意したスコープの境界、明示的に対象外とした事項（「Xは扱わないことに合意した」など）。これにより、サブエージェントは Goal ヘッダーに記載された内容だけでなく、ユーザーの意図全体に計画が対応しているかを確認できます。

references/plan-review-subagent.md のサブエージェント用プロンプトには、網羅性、依存関係、規模、基準の品質、フェーズの品質、文章要件への準拠、アーキテクチャ、リスクを含む、レビュー方法の全容が記載されています。

サブエージェントからの応答後：

• レビューで問題が見つからなかった場合：計画が敵対的レビューに合格したことをユーザーに伝え、実行を開始するか尋ねます。
• レビューで問題が見つかった場合：サブエージェントの報告全文とともに、すべての指摘事項をユーザーに提示します。変更が必要か、計画をそのまま受け入れるかはユーザーが判断します。
  • ユーザーが変更を希望する場合：計画に要望された変更を加えてから、更新した計画の敵対的レビューを再実行するか尋ねます。ユーザーは、もう一度レビューを行うか、レビューを辞退して実行に進むかを選べます。ユーザーが納得するまで、このレビューと変更のサイクルを繰り返します。
  • ユーザーが計画に問題はないと判断した場合：実行を開始するか尋ねます。

上記の簡易ルートを除き、計画レビューを省略してはいけません。ユーザーの意向を確認せずに指摘事項を自動で解決してはいけません。計画レビューは必須の関門です。このステップを通過するまで、計画は完成したものと見なされません。

承認後：計画ファイルを git にコミットし、セッションをまたいで保持し、チェックマークによる進捗管理に利用できるようにします。この手順を省略してはいけません。コミットしないと、セッションをまたいだ再開ができなくなります。

出力形式

ステップ数に応じてどの形式を選ぶかは、ステップ3（複雑さの評価）を参照してください。

単一ドキュメント

パス：docs/plans/YYYY-MM-DD-<topic>-plan.md

例：docs/plans/2026-03-15-user-auth-plan.md

マイルストーンフォルダー

パス：docs/plans/YYYY-MM-DD-<topic>/

内容：

docs/plans/2026-03-15-user-auth/
  README.md
  01_data-layer.md
  02_api-endpoints.md
  03_frontend-integration.md

README.md には、マイルストーンの概要を添えた順序付きリスト、確認済みのツールチェーン、およびすべてのマイルストーンに適用される横断的な懸念事項を記載します。

計画の実行

ユーザーから実行を依頼されたら、blueprint:execute を呼び出します。これにより、バッチ処理、git の処理、進捗管理を含む、サブエージェントのオーケストレーション全体が提供されます。利用できない場合は、各ステップについて3つのフェーズをすべて完了してから、次のステップに進みます。セッションをまたいだ再開ができるよう、完了したステップの見出しにチェックマークを付け、フェーズ3のチェックボックスにチェックを入れます。計画ステップの各フェーズに含める内容については、references/step-template.md を参照してください。

スコープ変更への対応

• 実行中のスコープ変更により、残りの計画の半分を超える部分が無効になる場合は、古くなった前提に基づく計画を修正するのではなく、最初からやり直すことを推奨してください。
• 実行中に新たなステップが必要になった場合は、同じ3フェーズ構成（構築、敵対的レビュー、検証）で提案し、計画内の適切な位置に挿入してください。

追加リソース

詳細なガイダンスについては、以下の参照ファイルをご覧ください。

• references/step-template.md — フェーズごとのガイダンスと完全なステップ例を含む、ステップの完全なテンプレートです。すべての計画のすべてのステップで、構成の参考として使用してください。
• references/tool-discovery.md — さまざまなエコシステムにおいて、プロジェクトのツールを検出するための言語別検索表です。ステップ1でコードベースを調査する際の参考として使用してください。
• references/plan-review-subagent.md — ステップ5で実行する敵対的計画レビュー用サブエージェントのプロンプトテンプレートです。計画の生成後にレビュー用サブエージェントを実行する際は、この内容を一字一句そのまま使用してください。