概要
writing-plans スキルでできること
writing-plans スキルは、プロダクト仕様書や技術要件ドキュメントを、誰もコードに触る前に「実装可能な計画」に落とし込むためのものです。複数ステップがある機能追加や変更をリリースしたいときに、事前知識のないエンジニアでも迷わず進められる、分解済みの計画を作る用途に向いています。
writing-plans を使うと、次のような計画を生成できます:
- 実装者は十分な開発スキルはあるが、あなたのコードベースやドメインには不慣れであることを前提にします。
- 作業の各パートごとに、どのファイルを新規作成・変更するかを明示します。
- 必要な テスト・ドキュメント更新・手動確認 を洗い出します。
- 作業を 小さく、出荷可能なタスク に分割し、境界をはっきりさせます。
これにより、作業の引き継ぎや計画レビューが容易になり、スコープの膨張や見落としを防ぎやすくなります。DRY や YAGNI、TDD、こまめなコミットといったプラクティスを踏まえつつも、焦点はコード生成ではなく、プロジェクト計画とタスク分解 にあります。
writing-plans の対象ユーザー
writing-plans スキルは、次のような場合に利用を検討してください。
- 機能開発やリファクタリングに対して、再現性のある計画プロセスが必要な テックリードやエンジニアリングマネージャー。
- リスクの高い変更や横断的な変更の前に、自分の方針を明確にしておきたい 個人開発者。
- サブエージェントや分散した開発チーム で、メンバー間の連携に明確な文書化された計画が必要なチーム。
特に適しているケース:
- 機能追加・移行・外部サービス連携などのための 仕様書や要件定義 がある。
- 作業が 複数のファイル・コンポーネント・サービス にまたがる。
- 他のメンバーが、頻繁に質問しなくても 実装を進められるようにしたい。
逆に、あまり向いていないケース:
- まだ 課題や解決策をブレインストーミングしている最中（まずはアイデア出し用のスキルを利用してください）。
- タスクが ごく小さい（例: 1 行だけの修正）ため、正式な計画が不要な場合。
- 目的が コードレビューやコード生成 であり、計画やタスク分解ではない場合。
ワークフロー上での位置づけ
リポジトリでは、writing-plans はブレインストーミングのフェーズが終わり、プロジェクトのための 専用 worktree で利用される想定になっています。典型的な流れは次のとおりです。
- 仕様のブレインストーミングと整理（このスキルの外側で実施）。
- 対象機能用の専用 worktree を作成または開く。
- writing-plans スキルを実行し、実装計画を生成する。
- 生成した計画を、デフォルトでは次のいずれかに保存する:
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md- もしくは、好みの計画ファイル保存先。
- 実装に入る前に、テンプレートを使って plan document reviewer サブエージェント を走らせ、計画の妥当性を確認することもできます。
使い方
インストールとセットアップ
1. writing-plans スキルをインストールする
スキルは obra/superpowers リポジトリから直接インストールできます:
npx skills add https://github.com/obra/superpowers --skill writing-plans
このコマンドで、writing-plans のスキル定義と関連プロンプト一式が取り込まれ、あなたのプロジェクトで利用できるようになります。
2. コアファイルを確認する
インストール後、ワークフローを理解・調整するために次の主要ファイルを確認してください:
skills/writing-plans/SKILL.md– スキルの振る舞いに関するメインの説明。スコープ、計画の構造、エンジニアに関する前提などが含まれます。skills/writing-plans/plan-document-reviewer-prompt.md– 完成した計画をレビューするサブエージェント用の再利用可能なプロンプトテンプレート。
ローカル環境でのパスは、リポジトリの vendoring やミラーの方法によって変わる場合がありますが、ファイル名は同じです。
writing-plans 実行の準備
3. 仕様とスコープを確定する
writing-plans を使う前に、次の点を満たしていることを確認してください:
- 対象の機能や変更内容についての 明確な仕様書または要件定義。
- 主要なコンポーネント、連携先、制約条件が分かる程度の詳細さ。
スキルには Scope Check のステップが含まれています。仕様書が複数の独立したサブシステムにまたがっている場合、ブレインストーミング段階でそれぞれを別のサブプロジェクト仕様に分割済みであることを期待します。もしまだであれば、次のように進めてください:
- サブシステムごとに作業を分割し、別々の計画 を作成する。
- それぞれの計画が、それ単体で 動作するテスト可能なソフトウェア を生み出せるようにする。
これにより、1 つの計画が巨大になりすぎることを防ぎ、デプロイ単位に沿った形で作業を整理できます。
4. worktree と計画ファイルを準備する
アップストリームのガイダンスでは、次のような前提で利用することを推奨しています:
-
機能ごとに 専用の worktree で作業する（ブレインストーミング時にセットアップ）。
-
生成された実装計画を次の形式で保存する:
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
チームで別のディレクトリ構造（例: docs/plans/ や planning/）を使っている場合は、この場所を上書きして構いません。重要なのは、計画が バージョン管理に含まれ、コードと一緒に履歴が残り、後から簡単に見つけられることです。
スキルを実行して計画を書く
5. 計画セッションを宣言して開始する
スキルを呼び出すとき、または計画作成の対話を始めるときは、意図を明示することが推奨されています:
"I'm using the writing-plans skill to create the implementation plan."
こうすることで、目的がデザイン検討やコード生成ではなく、構造化された実装計画の作成 であることが明確になります。
6. まずファイル構成をマッピングする
タスク列挙に入る前に、writing-plans は ファイル単位での分解 を重視します:
- どの ファイルを新規作成・変更するか を洗い出す。
- 各ファイルに 単一で明確な責務 を与える。
- インターフェースと境界が明確 な単位として設計する。
この段階で計画は次の問いに答えられる必要があります:
- 新しいロジックはどこに置くのか?
- どの既存ファイルに手を入れるのか、その理由は何か?
- それらのファイルは高いレベルでどう連携するのか?
早い段階で妥当なファイル構成を固めておくと、その後のタスク分解・レビュー・リファクタリングがぐっとやりやすくなります。
7. 作業を小さなタスクに分割する
ファイルマップができたら、writing-plans を使って仕様を 小さく、独立して理解可能なタスク の列に変換していきます。アップストリームのガイダンスでは次の点が強調されています:
- 各タスクには 明確な目的 があり、具体的に行動可能であること。
- 頻繁なコミット が可能になる程度の粒度に小分けすること。
- 計画は DRY（指示の重複を避ける）であり、YAGNI（不要な先回り作業をしない）であること。
各タスクには、少なくとも次を含めるとよいでしょう:
- そのタスクで触るファイル。
- 高いレベルで見たときに、どのコードや設定をどう変更するか。
- どのテストを追加・更新するか。
- 更新が必要なドキュメントがあるかどうか。
ゴールは、ほとんど背景知識のないエンジニアでも、任意の単一タスクを拾って自信を持って完了できる状態にすることです。
8. テストとドキュメントを計画に組み込む
writing-plans では、テストとドキュメント を計画の中に直接組み込むことを前提としています:
- 追加・更新が必要な ユニットテスト・結合テスト・E2E テスト を特定する。
- 必要に応じて、テストの実行方法（コマンドやエントリポイント）を明記する。
- README の該当セクション、ユーザーガイド、API ドキュメントなど、必要な ドキュメント更新 を指定する。
これにより、品質と保守性が「あとから考える事項」ではなく、計画の中心要素として扱われるようになります。
計画のレビューとブラッシュアップ
9. plan document reviewer テンプレートを使う（任意だが推奨）
plan-document-reviewer-prompt.md は、plan document reviewer サブエージェント 向けの構造化されたプロンプトを提供します。目的は次のとおりです:
- 計画が 仕様と照らして十分に網羅されているか を確認する。
- タスク分解 が現実的で、実行可能な粒度か検証する。
- エンジニアが計画に従って実装を進めたときに、行き詰まらずに完走できるか をチェックする。
テンプレートでは、レビュアーが確認すべき観点として次のカテゴリを挙げています:
- Completeness – 重要な要件について、TODO・プレースホルダ・抜け落ちたステップが残っていないか。
- Spec Alignment – 計画が仕様をカバーしつつ、大きなスコープ逸脱がないか。
- Task Decomposition – タスクの境界が明確で、実装可能な単位に分かれているか。
- Buildability – 有能なエンジニアであれば、計画に沿って最初から最後まで実装できるか。
レビュアーには、表現の細かさやスタイルの好みではなく、実装上の問題につながる懸念点 にフォーカスするよう指示しています。
このレビューステップは CI やレビューフロー、手動レビューに組み込むことができます。
10. フィードバックを反映して更新する
レビュアー（人間でもサブエージェントでも）が、要件漏れ・矛盾したステップ・抽象的すぎるタスクなどの問題を見つけた場合は、次のように対応します:
- 計画ファイルを修正し、問題点を解消する。
- 必要であれば、レビュアーを再実行または再依頼する。
- 計画が承認されたら、それを実装の 単一の信頼できる情報源 (source of truth) として扱う。
チーム向けに writing-plans をアレンジする
11. 構造と運用ルールをカスタマイズする
アップストリームのスキルは明確なデフォルト挙動や構造を定義していますが、次のようにチームに合わせてカスタマイズできます。
- リポジトリ構成に合わせて 計画ファイルの保存場所 を変更する。
- セキュリティレビューやパフォーマンステストなど、チーム固有の チェックリスト を繰り返し現れるタスクとして組み込む。
- タスクをチケットに対応づけて、issue トラッカー（例: Jira, GitHub Issues, Linear）と連携させる。
writing-plans が扱うのは主に 構造化されたワークフローとプロジェクトマネジメント なので、言語やフレームワーク、ドメインが変わっても応用しやすいのが特徴です。
FAQ
writing-plans スキルはいつ使うべきですか？
複数ステップの機能開発・リファクタリング・外部サービスとの連携 があり、ある程度はっきりした仕様が存在するときに、他のエンジニアでも前提知識なしで実行できる実装計画を用意したい場面で writing-plans を使うと効果的です。特に、複数のファイルやサブシステムにまたがる複雑な変更に着手する前に、有用性が高くなります。
writing-plans が向かないのはどんなときですか？
次のような状況では writing-plans は最適とはいえません:
- まだ 解決策を模索していて、仕様が固まっていない。
- 作業が非常に小さく、正式な計画を立てる方がオーバーヘッドになる。
- 目的が コード生成 や コードレビュー であり、タスク分解やプロジェクト計画ではない。
そのような場合は、ブレインストーミング・設計・コーディングに特化した別のスキルを使うことをおすすめします。
docs/superpowers/plans/ のデフォルトパスは必ず使う必要がありますか？
いいえ。アップストリームのガイダンスでは、計画ファイルの保存場所として次を推奨しています:
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
ただし、ユーザー側で好みの保存場所を優先してよい とはっきり明記されています。リポジトリやドキュメントポリシーに合う任意のディレクトリ・命名ルールで計画ファイルを管理できます。
コード以外のプロジェクトにも writing-plans を使えますか？
このスキルは、ファイル構成やテストを伴う ソフトウェアプロジェクトやコードベース を主な対象として設計されています。ただし、「作業を小さなタスクに分解する」「責務をマッピングする」「抜け漏れをチェックする」といった中核の考え方は、他の技術的なワークフローにも応用可能です。少なくとも、何らかのファイルやテスト、ドキュメントを更新する概念があるプロジェクトで最も効果を発揮します。
writing-plans はオンボーディングや引き継ぎにどう役立ちますか？
writing-plans は、実装者が コードベースの文脈をほとんど知らず、センスも怪しい という前提で計画を作るよう促します。そのため、次のような効果があります:
- コードをどこに置くべきか、なぜそこなのかを明示する。
- テストとドキュメントを明確に書き出す。
- タスクから曖昧さを排除する。
これにより、新メンバーや外部パートナー、サブエージェントへの作業引き継ぎがスムーズになります。彼らは仕様書の意図を逆算するのではなく、計画そのものに沿って実装を進められます。
writing-plans はプロジェクト管理ツールとどう関係しますか？
writing-plans はプロジェクト管理ツールの代わりではなく、それらを補完する存在です:
- 仕様をコードやファイルレベルでどう実装するかを説明した 構造化された文章の計画 を提供します。
- その後で、計画内のタスクを Jira や GitHub Issues、Linear などのツール上のチケットにマッピングできます。
このスキルは、プロジェクトマネジメント・ワークフローテンプレート・技術的なレポート執筆 の交差点に位置しており、実装計画を一貫したパターンで作成するための再利用可能な仕組みを提供します。
reviewer 用プロンプトだけを単体で使うことはできますか？
はい。plan-document-reviewer-prompt.md は、あらゆる「計画文書」に対する レビュー用テンプレート として単体で利用できます。サブエージェントへのプロンプトとして使い、次のような用途に活用できます:
- writing-plans で作成した計画のレビュー。
- 他のプロセスやツールで作成された計画文書のチェック。
ただし、計画の作成とレビューの両方を writing-plans のワークフローに沿って行うことで、最も一貫性のある結果が得られます。