write-blueprint

ブループリントスキルの作成

目的

各ステップが「構築・レビュー・検証」のサイクルに沿った、共同で実施する実装計画を文書として作成します。曖昧な機能リクエスト、アーキテクチャの変更、リファクタリングの目標を、人間またはエージェントが一つずつ実行できる具体的な順序付き計画に変換します。計画は対話として進めます。コードベースを調査し、ツールを見つけ、質問し、アプローチを比較し、複雑さを評価してから、計画を作成します。

作業量

タスクの複雑さに応じて調査の深さを調整しますが、常により徹底する方向に判断してください。範囲を絞る前に広く読み込みます。実行時に予想外のことが何も起きない計画を目指します。

計画の形式

計画は自己完結型のファイル（マイルストーン計画の場合はフォルダー）として記述します。形式によってファイル拡張子と、ステップ 4 で使用するステップのテンプレートが決まります。デフォルトは HTML です。非線形なステップ依存関係を示すインライン SVG の依存関係グラフ、execute-blueprint が進捗を正確に追跡するための構造化された data-status 属性、ステップ間のアンカーによる相互参照を利用できるためです。これらの機能は複数ステップの計画を大きく改善し、Markdown では表現できません。

監査スキルとは異なり、ブループリントの形式は必須条件ではありません。起動メッセージからユーザーの希望を判断し、それに従ってください。

• HTML のシグナル：HTML、html、「ウェブページとして」、「ブラウザーで表示可能」→ HTML を使用します。
• Markdown のシグナル：MD、md、Markdown、markdown、「プレーンテキストの計画」、「Markdown 形式で」→ MD を使用します。
• シグナルなし：何も伝えずに HTML をデフォルトで使用します。ディスク上のファイル拡張子（.html または .md）が選択した形式を示す正式なシグナルです。拡張子がすでに示している内容を繰り返すだけの「形式：HTML」という行を計画のヘッダーに追加しないでください。

起動メッセージから形式を本当に判断できない場合（例：シグナルが矛盾している、またはユーザーが「どの形式を使うべきですか？」と尋ねている場合）は、一度だけ確認してから進めてください。実際の曖昧さをデフォルトで解消した場合は、その判断を計画のヘッダーに簡潔に記載してください（例：「選択した形式：HTML — 起動メッセージのシグナルが矛盾していたため、デフォルトの HTML を選択」）。それ以外の場合は、形式の確認で計画の対話を中断しないでください。計画の進行には、ツールチェーン、確認事項、アプローチ、計画レビューといった必須の確認項目がすでに多くあります。

選択した形式は、実行中ずっと一貫して使用します。

形式	ステップのテンプレート	ファイル拡張子
HTML	references/step-template-html.md	.html
MD	references/step-template.md	.md

HTML の計画を作成する際は、references/step-template-html.md に記載されている HTML 固有の機能を、情報を加える場合に活用するツールとして扱ってください。これらの機能を使わず、Markdown の内容を HTML タグで囲むだけでは、HTML を選ぶ意味がありません。

アンチパターン：「計画するほどでもない」

1 行の変更であっても、どこに適用するのか、何に影響するのか、どう検証するのかという前提が伴います。「単純な」タスクこそ、検討されていない前提が無駄な手戻りを引き起こします。「構築・レビュー・検証」の構成によって、そうした前提が積み重なる前に見つけられます。計画は、受け入れ条件が 1 つの単一ステップでもかまいません。小規模な計画（2 ステップ以下）の迅速な進め方では、すでにオーバーヘッドを最小限に抑えています。アンチパターンは計画の規模ではなく、計画そのものを省略することです。

設計原則

コードより文章

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

コンテキストの管理（サブエージェント主導）

計画は意図的にサブエージェント主導で進め、メインの会話を無駄のない調整役に保ちます。最も多くのトークンを消費する2つの作業、つまり調査中のコードベースの一括読み込み（ステップ1）と、対立的な計画レビュー（ステップ5）はサブエージェントに任せ、サブエージェントから戻る際にコンテキストを回収します。メインの会話で保持するのは、要約された調査結果のみです。構造のマップ、確認済みのツールチェーン、確定した要件、レビュー報告を保持し、調査したすべてのファイルの生の内容は保持しません。これは、同じ理由から、すべてのビルド、レビュー、検証をサブエージェント内で行う execute-blueprint と同じ考え方です。コンテキストウィンドウを余裕のある状態に保つことで、両方のスキルを、大規模なコードベースや複数マイルストーンにわたる計画にも対応させ、品質を落とさずに規模を拡大できます。

ワークフロー

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

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

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

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

ファストパスのルール

狭い範囲の変更（設定変更、単一ファイルのリファクタリング、簡単な追加）を対象とする、ステップ数が2以下の計画はファストパスの対象となります。

• ツールの検出（ステップ1）： 独立した確認ゲートとしてではなく、生成した計画と併せて、検出したツールを提示します。計画のヘッダーには、引き続きツールチェーンの表を含めます。
• アプローチの提案（ステップ2）： 有力な戦略が1つしかない場合は、簡潔に説明して先に進みます。無理に別の案を作る必要はありません。
• 計画のレビュー（ステップ5）： サブエージェントへの委任は省略します。受け入れ条件の抜け、検証項目の不足、依存関係の問題がないかを簡潔に自己レビューします。計画を直接提示し、実行を開始するかユーザーに確認します。

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

1. コードベースを調査し、ツールを見つける

まず、コードベース全体を幅広く調査します。小規模なプロジェクトを超える規模の場合は、調査用サブエージェントを（Claude Code の Agent ツールを使って）並行して実行し、各領域を調べて、構造、エントリーポイント、データ層、規約、見つかったツールなどを整理した調査結果を返してもらいます。すべてのファイルをメインの会話に読み込むのではありません。コーディネーターはそれらの要約を統合し、計画のやり取りに必要な情報だけを残します。これにより、コンテキストウィンドウを小さく保てます。正確な確認質問をするために原文を直接見る必要がある、少数のファイルだけをメインの会話で直接読み込みます。

コードベース全体を調べ、次の項目を確認します。

• プロジェクト構成（ディレクトリ、モジュール、パッケージ）。
• エントリーポイント（メインファイル、ルート定義、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文で説明できる場合は、隣接するステップと統合します。独自のサブプランが必要な場合は、分割します。
• 自然なマイルストーンがあるかどうかを評価します（例：「まずデータレイヤー、次に API、最後に UI」）。
• ステップ数に応じて出力形式を選びます。
  • 5ステップ以下、単一の関心事：単一の計画ドキュメント。
  • 6～8ステップ、単一の関心事：見出しをグループ化した単一のドキュメント。
  • 複数のフェーズ、または9ステップ以上：マイルストーンフォルダーを作成し、マイルストーンごとに1つのファイルを用意します。
  • 判断が難しい場合：ユーザーに尋ねます。

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

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

4. 計画を生成する

上記の「計画形式」セクションで選択した形式に対応するテンプレートに従って、計画成果物を作成します。HTML 出力（デフォルト）には references/step-template-html.md、Markdown には references/step-template.md を使用します。各ステップには、Build、Adversarial Review、Verification の3つのフェーズすべてを含めます。

計画ヘッダー：タイトル、日付、目標の概要、確認済みのツールチェーンを含めます。ヘッダーの正確な表示形式は、選択したテンプレートの「Plan Document Structure」セクションに記載されています。Markdown のヘッダーは次のようになります。

# 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]

HTML のヘッダーでは、references/step-template-html.md に定義された <header class="plan-header"> と <section id="tool-chain"> の枠組みを使用します。HTML の計画では、<article class="step"> に必要な ID、クラス、data-* 属性は必須です。execute-blueprint は進捗を追跡するため、これらの属性を正確に変更します。

ステップ生成ルール：

• ステップには1から始まる連番を付けます。
• 成果物を示す、明確で具体的なタイトルを付けます（「ユーザー認証エンドポイントを追加する」など）。作業内容を示すタイトル（「認証に取り組む」など）は避けます。
• 受け入れ基準は具体的で、テスト可能なものにします。「コードがきれい」「パフォーマンスが良い」のような曖昧な基準は避けてください。「95パーセンタイルで応答時間が200ms未満」「すべての検証エラーがフィールド単位のメッセージとともに422を返す」など、測定可能な条件を使用します。
• フェーズ1（Build）では、文章を先に記述するアプローチに従って、実装の意図を説明します。作成、変更、テストする内容を具体的に指定します。該当する場合は、既存のコードパターンを参照します（「src/repos/product_repo.py の既存のリポジトリパターンに従います」など）。
• フェーズ2（Adversarial Review）では、失敗しやすい箇所を対象とした、ステップ固有のレビュー質問を記載します。また、より広範な統合に関する質問も含めます。この変更は既存のコードベースに自然になじんでいますか？確立された規約やパターンに従っていますか？直接の対象範囲外で、何かを破損させたり劣化させたりする可能性はありますか？レビューでは、受け入れ基準のチェックリストにとどまらず、作業内容を徹底的かつ批判的にコードレビューします。目標は、次に進む前にビルドフェーズで導入された問題をすべて取り除くことです。
• フェーズ3（Verification）では、確認済みのツールチェーンのコマンドを使った完全なチェックリストを含めます。標準的なチェックに加え、ステップ固有の検証項目も追加します。
• 実行を進める前に人による確認が本当に必要なステップ（レンダリングされたUI、実データを使ったマイグレーション、ツールでは判断できない承認など）がある場合は、その旨をステップのテキストに明記します。execute-blueprint は通常の指摘を自動で修正し、計画で人による確認を求めている場合にのみ一時停止します。そのため、明記されていないチェックポイントは発生しません。

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

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

• 選択した形式の拡張子を使用して、マイルストーンごとに1つのファイルを作成します。HTML の場合は 01_milestone-name.html、02_milestone-name.html など、Markdown の場合は .md を使用します。
• 各マイルストーンファイルは、選択したテンプレートに従い、同じ構造（ヘッダー、ツールチェーン、ステップ）にします。
• 計画フォルダーのルートに README（HTML の計画では README.html、Markdown の計画では README.md）を追加し、マイルストーンを順番に並べて、それぞれを1文で説明します。HTML 版では、references/step-template-html.md の <section id="milestones"> の枠組みを使用します。
• 各マイルストーンは3～5ステップにします。それを超える場合は、分割してください。
• 1つの計画フォルダー内で形式を混在させないでください。すべてのマイルストーンファイルと README で同じ拡張子を使用します。

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「複雑さの評価」を参照してください。HTML と Markdown のどちらを選ぶかについては、このスキルの冒頭にある「計画の形式」を参照してください。この2つの選択は独立しています。どのドキュメントレイアウトでも HTML または Markdown を使用できます。

単一ドキュメント

パス：docs/plans/YYYY-MM-DD-<topic>-plan.<ext>。<ext> は html（既定）または md です。

例（HTML）：docs/plans/2026-03-15-user-auth-plan.html 例（MD）：docs/plans/2026-03-15-user-auth-plan.md

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

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

内容（HTML、既定）：

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

内容（Markdown）：

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

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

計画の実行方法

ユーザーから実行を求められたら、blueprints:execute-blueprint を呼び出してください。これは、Git の処理と進捗管理を含むサブエージェントの完全なオーケストレーションを提供し、.md と .html の両方の計画形式に対応します。利用できない場合は、各ステップを1つずつ進め、次に進む前に3つのフェーズすべてを完了してください。完了したステップには計画の見出しにチェックマークを付け、フェーズ3のチェックボックスにチェックを入れてください（HTML 計画の場合は、ステップの <article> に data-status="complete" を設定し、ステータスバッジのテキストを更新し、ステップの見出しの先頭に ✅ を付け、検証用チェックボックスに checked を追加してください）。これにより、セッションをまたいで再開できます。計画の各ステップの各フェーズに含める内容については、references/step-template.md または references/step-template-html.md を参照してください。

スコープ変更への対応

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

追加リソース

詳細なガイダンスについては、次のリファレンスファイルを参照してください。

• references/step-template.md — フェーズごとのガイダンスと完全なステップ例を含む、Markdown のステップテンプレートです。選択した計画形式が Markdown の場合に、構成のリファレンスとして使用してください。
• references/step-template-html.md — 必須の骨組み、構造上の契約（ID／クラス／data-* 属性）、HTML 固有の利便機能に関するガイダンス、および完全なステップ例を含む、HTML のステップテンプレートです。選択した計画形式が HTML（デフォルト）の場合に、構成のリファレンスとして使用してください。
• references/tool-discovery.md — エコシステム全体でプロジェクトのツールを検出するための、言語ごとの参照表です。ステップ1でコードベースを調査する際に参照してください。
• references/plan-review-subagent.md — ステップ5で実行する敵対的計画レビューのサブエージェント向けプロンプトテンプレートです。計画の生成後にレビュー用サブエージェントを実行する際は、原文のまま使用してください。