writing-plans

writing-plans スキルの概要

writing-plans スキルでできること

writing-plans は、機能仕様書や要件定義書を、実装に着手する前の詳細な実装計画へ落とし込むためのスキルです。主眼はアイデア出しではなく、実際に作れてレビューもしやすい計画を作ることにあります。実装担当者がコードベースの前提知識をほとんど持っていなくても進められるように、ファイル単位の指示、テスト手順、作業順序まで明確に示す前提で設計されています。

writing-plans を使うべき人

このスキルは、すでにスコープが定まった要件を持ち、次に Requirements Planning の実行計画を必要としているエンジニア、テックリード、エージェント主導のワークフローに向いています。特に、変更が複数ファイルにまたがる場合、テストやドキュメント更新も含む場合、あるいは仕様を書いた本人ではない人に実装を引き継ぐ場合に有効です。

このスキルが本当に解決する仕事

writing-plans の利用者が求めているのは、たいてい実装時の推測を減らすことです。価値があるのは単に「計画を書く」ことではなく、「隠れた前提なしで、一定の力量を持つエンジニアがそのまま進められる計画を作る」ことです。どのファイルを触るのか、どう小さな作業単位に分けるのか、何をテストするのか、実装前にどこでスコープを分割すべきかまで含めて整理します。

汎用プロンプトと違う点

writing-plans skill には、実務上効いてくる明確な設計思想があります。

• 分解に入る前にスコープ確認を促す
• タスクを書く前に、各ファイルの責務整理を必須にしている
• 大きな工程分けより、小さく検証可能な増分を優先する
• 実装者側のドメイン知識が薄い前提で組み立てる
• その計画が本当に実装可能かを確認するための reviewer prompt が含まれている

そのため、引き継ぎ品質を重視するなら、1行の「実装計画を書いて」という汎用プロンプトよりも writing-plans のほうが実用的です。

writing-plans が特にハマるケース

次のような状況なら writing-plans は相性が良いです。

• 仕様書、チケット、要件定義書がすでにある
• 実装の中身に意味のある複数ステップの変更がある
• コード、テスト、ドキュメントを横断して調整する必要がある
• リポジトリ内でファイル境界や作業順が重要になる

逆に、ざっくりしたアウトラインや粗い見積もりだけ欲しい場合は、少し重すぎるかもしれません。

writing-plans スキルの使い方

writing-plans のインストール前提

このスキル自体には専用のパッケージ単位インストーラは用意されていないため、実際の writing-plans install は親のスキルコレクションを追加して、その中から呼び出す形になります。

npx skills add https://github.com/obra/superpowers --skill writing-plans

もし環境側で別の skill loader を使っているなら、obra/superpowers コレクションを導入し、skills/writing-plans を選択してください。

まず読むべきファイル

手早く見極めたいなら、最初に確認すべきなのは次の2ファイルです。

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

SKILL.md には、実際の planning workflow が書かれています。plan-document-reviewer-prompt.md は、その計画が満たすべき品質基準を示してくれるので、本番運用に載せる前の判断材料として役立ちます。

writing-plans に必要な入力

writing-plans usage を活かすには、次の情報を渡すのが理想です。

• 元になる仕様書や要件
• 対象のリポジトリ、またはコードベース内の対象領域
• アーキテクチャ、ツール、締切、後方互換性などの制約
• デフォルト以外にしたい場合は、計画の出力先
• 作業を複数の独立した計画に分けるべきかどうか

実際の仕様書がないままだと、もっともらしい構造は出せても、実装の指示としては弱くなりがちです。

最初に必要なアナウンスを入れる

上流の指示では、エージェントが次の文言を明示するよう求めています。

I'm using the writing-plans skill to create the implementation plan.

これをエージェントのワークフローに組み込むなら、そのまま残すのがおすすめです。どの planning standard を適用しているかが明確になり、曖昧さを減らせます。

コードを書く前に、できれば専用 worktree で使う

このスキルは実装前の planning を前提にしており、上流では brainstorming workflow によって作られた専用 worktree 上で動かす想定です。完全に同じ構成を使わなくても、この意図は重要です。コード編集を始める前に隔離された文脈で計画を作ることで、その計画が「書きながらついでに出たメモ」ではなく、意図的な成果物になります。

曖昧な目的を強いプロンプトに変える方法

弱いプロンプト:

• “Make a plan for adding billing.”

より強いプロンプト:

• “Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

これが機能する理由:

• 仕様書を明示している
• 関係しそうなファイルやモジュールを示している
• 分解のしかたに影響する制約を伝えている
• 巨大な1本の計画に押し込まず、必要ならスコープ分割を促している

スキルが想定する planning sequence に従う

良い writing-plans guide は、リポジトリが前提としている順序に沿うべきです。

1. その仕様を複数の計画に分けるべきか確認する
2. タスク分解の前に、ファイルと責務の対応を整理する
3. 小さく進められる実装タスクを書く
4. テスト、ドキュメント、検証手順を含める
5. 完成した計画を仕様書に照らして見直す

ファイル構成の整理を飛ばすと、タスクが曖昧になるのが最もよくある失敗です。

良い出力に含まれるべきもの

writing-plans for Requirements Planning の良い計画には、通常次の要素が入ります。

• 計画の目的と関連する仕様書
• 作成または変更するファイル
• 各ファイルがなぜ必要なのか、何を変えるのか
• それぞれ独立して完了・検証できる粒度のタスク
• 単なるコーディング手順ではないテスト方針
• 必要に応じたドキュメント更新や migration 対応
• 別のエンジニアでも詰まらず進められるだけの具体性

もし出力が「backend」「frontend」「QA」のような大まかな工程分け中心なら、粒度が粗すぎる可能性が高いです。

デフォルトの保存先と上書きすべき場合

このスキルでは、計画の保存先として次を提案しています。

docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

ただし、リポジトリ側ですでに docs/plans/ や specs/implementation/ のような planning convention があるなら、そちらに合わせて上書きすべきです。大事なのは、後からレビュアーが迷わず見つけられる一貫した置き場所にすることです。

reviewer prompt の使い方

計画のドラフトを書いたら、plan-document-reviewer-prompt.md を2回目の見直し用テンプレートとして使います。レビュー基準はかなり実務的です。

• completeness
• spec alignment
• task decomposition
• buildability

ここは writing-plans skill の差別化ポイントでもあります。生成して終わりではなく、計画という成果物に対する軽量な acceptance check まで用意されています。

実務で回しやすい workflow

安定して使いやすい流れは次のとおりです。

1. 仕様書とリポジトリ文脈を集める
2. writing-plans を実行する
3. 計画の分割が適切か確認する
4. ファイル境界とタスク粒度を点検する
5. plan reviewer prompt を実行する
6. 実装着手前に計画を修正する

この流れにすると、writing-plans は単なる文書作成の補助ではなく、実装前の planning gate として最も価値を発揮します。

writing-plans スキル FAQ

writing-plans は初心者にも向いていますか？

はい、ある程度具体化された仕様書がすでにあるなら有効です。writing-plans は、ファイル単位の指示やテスト方針を明示させることで、コードベース文脈の不足を補ってくれます。逆に、本当の課題がまだ曖昧なプロダクト検討段階にあるなら、あまり向いていません。

AI に実装計画を書かせるのと何が違いますか？

汎用プロンプトだと、見た目は整っていても中身が浅い計画になりがちです。writing-plans は、ファイル単位の分解、テスト可能性、実装担当への引き継ぎ品質まで押さえるため、実際にはこちらのほうが役立ちます。結果として、実装開始後の手戻りも減りやすくなります。

writing-plans を使わないほうがいいのはどんなときですか？

次のようなケースでは見送って構いません。

• 変更が小さく、局所的である
• まだプロダクトのスコープを決めている段階である
• 実行計画よりもアーキテクチャ探索が必要である
• 実験的な作業で、すぐ内容が変わる前提である

こうした状況では、形式的な計画より軽いメモのほうが合うことがあります。

特定のスタックやフレームワークが必要ですか？

いいえ。これはフレームワーク依存のスキルではなく、プロセス重視のスキルです。焦点は分解、ファイル責務、テスト、レビューしやすさにあるため、スタックをまたいで使えます。

writing-plans は大きな仕様にも対応できますか？

はい。ただし、スコープ確認の工程を守ることが前提です。元の指示でも、独立した複数のサブシステムがあるなら通常は別々の計画にすべきだと明示されています。無理に巨大な1本へまとめると、タスク品質はたいてい落ちます。

Requirements Planning に writing-plans だけで十分ですか？

実装中心の Requirements Planning であれば、多くの場合は十分です。一方で、探索段階の要件定義には向きません。前提として、「何を作るべきか」はすでに分かっていて、その実装までの確実な道筋が必要な状況を想定しています。

writing-plans スキルを改善するには

リポジトリ文脈をもっと具体的に渡す

writing-plans の結果を最も手軽に改善する方法は、関係しそうなディレクトリ、モジュール、ファイルを明示することです。このスキルは早い段階でファイル責務を整理しようとするため、触りそうな箇所を渡しておくほど、出力は具体的になり、ありがちな一般論に寄りません。

独立したサブシステムは最初に分ける

仕様書の中に無関係な論点が混ざっているなら、最終計画を依頼する前に分割してください。例:

• auth changes
• billing changes
• admin UI changes

プロダクト上は一緒に出荷する変更でも、実装とテストを独立して進められるなら、計画は分けたほうがよいケースが多いです。

ファイル責務の整理を明示的に要求する

最初のドラフトが曖昧なら、次のように依頼します。

• “List each file to add or modify and state its responsibility before writing tasks.”

これはスキルの構造とよく噛み合っており、ぼんやりした分解を改善しやすい指示です。

タスク粒度をもっと小さくする

よくある失敗は、タスクが大きすぎて安全に実装できないことです。次の条件を明示すると改善しやすくなります。

• テスト可能な進捗を生むタスクにする
• 各タスクの境界を明確にする
• 主要な変更ごとに検証手順を明示する

writing-plans usage が特に良くなるのはこの点です。タスクが小さいほど、レビュー、アサイン、実行のどれもやりやすくなります。

テスト要件を具体化する

単に「テストを含めて」と頼むだけでは不十分です。代わりに、次の点を指定してください。

• どのレベルのテストが重要か
• 既存のどの test suite を更新すべきか
• migration、integration、regression の確認が必要かどうか

このスキルはもともとテストを重視していますが、制約が具体的なほど、計画の実用性は大きく上がります。

reviewer 主導の反復で初稿を改善する

reviewer template は最終ゲートとしてだけでなく、編集ツールとして使うと効果的です。最初の計画のあとで、次の観点を問い直してください。

• 仕様書に対して何が欠けているか
• どのタスクが実行可能な形になっていないか
• 実装担当がどこで詰まりそうか
• スコープの膨張が起きていないか

こうした問いを使うほうが、「計画を改善して」と広く頼むよりも、2稿目が鋭くなります。

よくある失敗パターンに注意する

writing-plans skill が弱くなりやすいのは、次のような場合です。

• 仕様書が不完全
• ファイル境界がリポジトリに基づかず推測になっている
• タスクが実装手順ではなく結果だけを述べている
• テストに触れてはいるが、コード変更と結び付いていない
• 巨大な1本の計画の中に、実は独立した成果物が複数埋もれている

こうした兆候が見えたら、スキルを責める前に入力条件を見直すべきです。

実装判断を左右する制約を加える

有効な制約の例:

• backward compatibility requirements
• performance expectations
• migration safety
• deployment order
• documentation obligations
• no-new-dependency rules

こうした情報があると、writing-plans for Requirements Planning は理想論ではなく、実際の運用環境に合った計画を出しやすくなります。

実際の引き継ぎ要件に照らして計画を評価する

品質判断の基準はシンプルです。文脈理解が浅い別のエンジニアが、この文書だけで繰り返し確認せずに実装できるかどうか。それが難しいなら、ファイル選定、タスク境界、検証手順が明示されるまで計画を改善する必要があります。

計画は DRY かつ実装中心に保つ

元のガイダンスでは、DRY、YAGNI、TDD、そして頻繁なコミットが重視されています。実務では、重複タスクを削り、投機的な作業を避け、すぐにコード化・検証できる小さな単位を優先する、という意味です。出力品質を上げるうえでは、説明文を増やすことより、こうした原則を守るほうが重要です。