blueprint

blueprint skill の概要

blueprint ができること

blueprint skill は、1行の目標を複雑なエンジニアリング作業向けの段階的な構築計画に落とし込みます。複数セッション・複数PRにまたがる作業を前提に設計されており、新しく入ったエージェントでも推測に頼らず続きを進められるだけの文脈を持てるのが特長です。Project Setup の blueprint、移行ロードマップ、依存関係を含むリファクタ計画が必要な場合に、特に相性のよい skill です。

どんな人に向いているか

セッションをまたいで作業を引き継ぐことが多い場合、並行するサブタスクを調整する必要がある場合、あるいはコンテキスト消失が起きても崩れない計画が欲しい場合は、blueprint の導入候補です。とくに既存 repo の中で作業するエージェントに向いており、アイデア出しよりも、安全な順序で進めること自体が難所になるケースで力を発揮します。

何が違うのか

一般的な prompt と違って、blueprint にはトリガールール、依存関係の順序付け、並列化できる工程の検出、批判的に見直す review gate、そして計画を更新していくための mutation protocol が最初から組み込まれています。重要なのは、主なリスクがコードを書くことそのものではなく、順番を誤ること、工程の粒度が粗すぎること、あるいはロールバック経路を見落とすことにある場面で、この構造化が効くという点です。

blueprint skill の使い方

正しくインストールし、適切なタイミングで呼び出す

blueprint skill は、ディレクトリ標準の skill installer で導入し、タスクが本当に多段階であるときだけ起動してください。この repository の trigger rule は意図的に狭く作られています。使うべきなのは、作業が複数セッションまたは複数PRにまたがりそうな plan・blueprint・roadmap を作るときです。1回で終えられる小さな変更には使わないでください。

入力に必要な情報をきちんと渡す

Blueprint は、目的、対象 repo、制約、done の定義が入力に含まれていると最も効果を発揮します。弱い prompt は「plan the refactor」です。より良い例は次のようなものです。「Create a blueprint for Project Setup: move config loading into a shared module, keep backward compatibility for two releases, and separate UI changes from backend migration.」スコープが具体的であるほど、依存関係グラフの精度と各ステップの粒度が良くなります。

まず読むべきファイル

最初に SKILL.md を読み、そのうえで workflow、conventions、既存 plans を説明している repo 内ドキュメントを確認してください。この repository では skill 本体が自己完結しているため、特に押さえるべきなのは research、design、review、mutation rules から成るパイプラインです。対象 codebase に memory files、architecture docs、過去の migration notes があるなら、blueprint の出力品質はそれによって大きく上がります。

より良い出力につながる進め方

blueprint は 3 パスで使うのが効果的です。まず計画を生成し、次に各ステップが本当に独立して実行可能かを確認し、最後に依存関係の抜けや危険な並列実行がないかを見直して修正します。同じファイル、共有状態、あるいはリリース順序に依存するステップには特に注意してください。見た目は整っていても、実行段階で破綻しやすいのはこうした箇所です。blueprint のよい使い方は「とにかく詳細にすること」ではなく、「初見でも実行できるだけの文脈を保ちつつ、順序を正しく設計すること」です。

blueprint skill FAQ

blueprint は大規模プロジェクト専用？

はい、基本的にはそうです。この skill は、単一の PR には収まらない作業や、計画なしで進めると危険な作業向けに作られています。タスクが小さい、単純、あるいは数回の tool call で終わるなら、通常の prompt のほうが速いことがほとんどです。

blueprint は普通の prompt と何が違う？

普通の prompt でも計画は依頼できますが、blueprint ではステップ間の依存関係、並列実行の検出、ロールバックの観点、そして弱い前提を見つけにいく review layer が追加されています。Project Setup の blueprint のように、順序や引き継ぎ品質が結果を左右するタスクでは、この違いが信頼性に直結します。

blueprint は初心者にも向いている？

はい。プロジェクトを扱いやすいフェーズに分解する考え方を学ぶ目的なら有用です。ただし、「そもそも何をやるべきか」から固まっていない段階ではあまり向きません。この skill は、制約と完了までの道筋を持つ、実在するエンジニアリング上の目標があることを前提にしています。

blueprint を使わないほうがいいのはいつ？

作業がそのまま着手して完了できるほど小さいとき、ユーザーが明確に「just do it」と言っているとき、あるいはタスクに意味のある依存構造がないときは使わないでください。そうしたケースでは、計画を立てるオーバーヘッドだけが増え、結果の改善につながらないことがあります。

blueprint skill を改善するには

スコープの境界を明確にする

優れた blueprint は、何を変えるべきか、何を安定のまま保つべきか、何を対象外にするか、そして何を成功とみなすかが明確なときに生まれます。Project Setup の blueprint が欲しいなら、repo の bootstrapping を変えるのか、environment config を見直すのか、CI setup を含めるのか、あるいはその全部なのかを明示してください。スコープが曖昧だと、広すぎるか浅すぎる plan になりやすくなります。

依存関係の手がかりを最初に渡す

Blueprint は、どの要素が他をブロックするのかを把握できていると強いです。migrations、shared modules、feature flags、API contracts、release order、さらに別のステップ開始前に必ず入っていなければならない要素があれば、最初に伝えてください。そうすることで、単なるバラバラのタスクリストではなく、使える依存関係グラフを出しやすくなります。

実行可能な粒度のステップを求める

blueprint skill の出力品質を上げたいなら、新しいエージェントが初見でそのまま実行に移れるステップを求めてください。各ステップには、repo 全体を読み直さなくても進められるだけの文脈、期待される結果、リスクのメモが必要です。これはマルチエージェントで進める作業で特に重要で、曖昧なステップ名は手戻りの原因になります。

最初の計画を前提に磨き込む

最初の blueprint は draft と考え、制約の抜け、衝突する並列作業、大きすぎて 1 つの PR に収まらないステップがないかを確認したうえで引き締めてください。計画が広すぎるなら分割し、細かすぎるなら重複する準備作業をまとめます。目指すべきなのは見栄えのよいアウトラインではなく、実行リスクを下げられる blueprint です。