spec-driven-planning

仕様駆動型計画スキル

目的

機能計画を次のいずれかのモードで進めます。

• Quick モード — 細かいタスクを記載した単一の docx/features/[NN-name]/plan.md を作成します。EARS も RGR もありません。個人作業、3 日以内、コンプライアンスや引き継ぎが不要な場合に適しています。superpowers の writing-plans パターンをもとにしています。
• Full モード — 3 つの承認ゲートと、後続工程での TDD の徹底を伴う 3 つのファイル（EARS 形式の requirements.md、design.md、tasks.md）を作成します。チーム作業、複数週間にわたる作業、コンプライアンスや監査、ステークホルダーによるレビューが必要な場合に適しています。

このスキルはモードを選択し（判断が難しい場合は質問します）、選択したモードに対応する手順を実行します。

有効化のトリガー

次の場合、このスキルを有効にします。

• ユーザーが「新しい機能を作成して」「機能を計画して」「[X] を作る必要がある」と言った場合
• ユーザーが「要件」「仕様」「アーキテクチャ」「技術設計」に言及した場合
• ユーザーが /dev-workflow:spec コマンド（任意のサブ引数）を使用した場合

---

モードの選択（必ず最初に行う）

何かを書く前に、Quick と Full のどちらにするかを決めます。

次の条件をすべて満たす場合は Quick を自動選択します。

• 想定作業量が 3 日以内、またはタスク数が 8 件以内
• 個人開発者による作業で、ステークホルダーの承認が不要
• コンプライアンス、監査、規制上の要件がない
• 重大なアーキテクチャ上の決定（「X と Y のどちらか？」というトレードオフ）がない
• ユーザーの依頼から要件が明確
• チーム間の引き継ぎがない
• ユーザーが「quick」「lightweight」「simple plan」または /dev-workflow:spec quick と指定した

次のいずれかに該当する場合は Full を自動選択します。

• 作業量が 1 週間を超える、またはタスク数が 15 件を超える
• エンジニア以外のステークホルダーによるスコープの承認が必要
• コンプライアンス／監査／規制要件に関するトレーサビリティが必要
• 長期的な影響を伴うアーキテクチャの選択がある
• 要件が曖昧で、聞き取りが必要
• 複数の開発者が関与する、または引き継ぎの可能性が高い
• ユーザーが「full spec」「EARS」「requirements doc」または /dev-workflow:spec full と指定した

それ以外の場合は曖昧として扱います

上記のしきい値には、意図的に中間の範囲を設けています。作業量が 4～7 日、タスク数が 9～15 件、または一部の条件だけに該当する場合は中間ゾーンです。Quick の条件をすべて満たす場合にも、Full の条件のいずれかに該当する場合にも当てはまらなければ、その機能は定義上、曖昧です。ユーザーに質問してください。

曖昧な場合は、次のメニューを一度だけ尋ねます。

This feature could go either way. Pick a planning mode:

1. Quick — single plan.md, no EARS, no RGR (recommended for solo, ≤3 days)
2. Full — 3-file spec with EARS + TDD enforcement (recommended for team, >1 week, compliance)

Default if you don't pick: Quick.

選択したモードを伝えます。

「[Quick/Full] モードを使用します。上記のシグナルに基づく理由を 1 文で説明します。」

その後、以下の該当する手順を実行します。

---

Quick モードの手順

出力： docx/features/[NN-feature-name]/plan.md（単一ファイル）

ステップ 1：機能ディレクトリを作成する

1. ls docx/features/ を実行して、次の NN 番号を確認します
2. mkdir -p docx/features/[NN-feature-name] を実行します
3. dev-workflow/templates/plan.md を読みます
4. [Feature Name] を実際の名前に置き換え、docx/features/[NN-feature-name]/plan.md に書き込みます

ステップ 2：計画を記入する

対象読者の想定：このコードベースについて何も知らないエンジニアです。正確に記述してください。

必須セクション：

• Goal — 1 文
• Architecture — 2～3 文。何をどこに配置するか、その理由を記述します
• Tech Stack — 主要なライブラリ／ファイル
• Out of Scope — スコープを明確にします
• Tasks — 2～5 分で完了できる細かいタスク。次の内容を含めます。
  • Files: 正確なパス（行範囲を指定した Create / Modify）
  • Steps: 番号付きの手順。各項目には 1 つのアクションを記述します。「ここにバリデーションを追加する」ではなく、完全なコードを記載してください。期待される出力を含む、正確な検証コマンドを記載します。最後にコミットの手順を入れてください。

粒度のルール：1 つの手順に 5 分を超える場合は、分割してください。

ステップ 3：1 つの承認ゲート

「Quick の計画を docx/features/[NN-feature-name]/plan.md に保存しました。実装に進む前に確認して承認してください。準備ができたら /dev-workflow:spec execute を実行してください。」

以上です。EARS も、設計案の比較も、RGR もありません。実装は spec-driven-implementation が担当します（plan.md を自動検出し、Quick 実行モードで動作します）。

次のような場合、Quick モードは適切ではありません。

• エンジニア以外の承認が必要な要件を記述している → Full に切り替えます
• 2 つ以上のアーキテクチャ案を比較している → Full に切り替えます
• タスクを 15 件超列挙している → Full に切り替えます
• 要件 → タスク → テストのトレーサビリティが必要 → Full に切り替えます

アップグレード方法については、このスキルの末尾にある「アップグレード方法」を参照してください。

---

フルモードのプレイブック

3 つのフェーズと 3 つの承認ゲートがあります。シグナルがフルを示している場合に使用してください。

フェーズ 1：機能の作成

目標： 機能の構成とプレースホルダーファイルを作成します

手順：

1. ユーザー入力から機能名を解析します
2. Bash ツールを使って既存の機能を確認します：ls docx/features/
3. 機能ディレクトリに割り当てる次の番号（NN）を決定します
4. Bash ツールを使ってディレクトリを作成します：mkdir -p docx/features/[NN-feature-name]
5. プラグインから機能ディレクトリにテンプレートをコピーします：
   • Read ツールを使用します：dev-workflow/templates/requirements.md
   • Write ツールを使用します：docx/features/[NN-feature-name]/requirements.md（[Feature Name] を実際の名前に置き換えます）
   • Read ツールを使用します：dev-workflow/templates/design.md
   • Write ツールを使用します：docx/features/[NN-feature-name]/design.md（[Feature Name] を実際の名前に置き換えます）
   • Read ツールを使用します：dev-workflow/templates/tasks.md
   • Write ツールを使用します：docx/features/[NN-feature-name]/tasks.md（[Feature Name] を実際の名前に置き換えます）

出力：

Created feature: docx/features/[NN-feature-name]/
- requirements.md (from template)
- design.md (from template)
- tasks.md (from template)

Next step: Define requirements using EARS format

ユーザーの確認：

「機能の構成を作成しました。要件の定義に進みますか？」

---

フェーズ 2：要件定義（EARS 形式）

目標： EARS の手法を使って、明確でテスト可能な要件を記述します

スコープの分解確認（最初に実施）：

要件を引き出す前に、依頼内容を確認します。複数の独立したサブシステム（例：「認証＋請求＋管理ダッシュボード」）について説明されている場合は、作業を止め、いずれかの要件を詳細化する前に、個別の機能に分解します。3 つに分けるべき機能について、要件を引き出すための質問に時間を費やさないでください。

🗣 こう伝えます：「この依頼には [N] 個の独立したサブシステムが含まれています。要件を引き出す前に、それぞれに個別の機能を作成します。」

プレースホルダー禁止ルール：

要件および後続の計画には、以下を含めてはなりません。

• 「TBD」／「未定」／「後で定義」
• 「適切な X を追加する」／「必要に応じてエラーを処理する」／「必要に応じて検証する」
• 「[他のもの] と同様」／具体的な説明を伴わない「上記を参照」
• 目的語のない曖昧な動詞：「更新する」「改善する」「修正する」「強化する」
• 要件の文中の「など」や末尾の省略記号
• 未定義の名前への参照（存在しない REQ-ID、まだ仕様が定まっていないモジュール） 要件を具体的に指定できない場合は、ユーザーに尋ねてください。プレースホルダーを書かないでください。

ブレインストーミングの統合（任意）：

• ユーザーのアイデアが大まかで要件が不明確な場合は、Skill ツールを使って dev-workflow:brainstorming を呼び出します
• 何を構築するか、何を対象外とするかの明確化に役立ちます
• 協力しながら質問を重ね、さまざまな機能スコープを検討します
• 必須要件と、あると望ましい要件を見極めます

有効化方法：

Use Skill tool: Skill(skill: "dev-workflow:brainstorming")

EARS 形式の説明：

EARS（Easy Approach to Requirements Syntax）は、曖昧さのない要件を記述するための 5 つのテンプレートを提供します。

1. 普遍的要件 - 常に成立する要件

   • テンプレート：「システムは [要件] を SHALL する」
   • 例：「システムは、すべてのユーザー入力を処理前に検証する SHALL」

2. イベント駆動型要件 - イベントによってトリガーされる要件

   • テンプレート：「[トリガー] が発生したとき、システムは [応答] を SHALL する」
   • 例：「ユーザーが送信をクリックしたとき、システムはフォームデータを検証する SHALL」

3. 状態駆動型要件 - 特定の状態にある間に有効な要件

   • テンプレート：「[状態] の間、システムは [要件] を SHALL する」
   • 例：「支払いの処理中、システムは読み込みインジケーターを表示する SHALL」

4. 条件付き要件 - 条件に基づく要件

   • テンプレート：「[条件] の場合、システムは [要件] を SHALL する」
   • 例：「ユーザーのロールが管理者の場合、システムは管理パネルを表示する SHALL」

5. 任意要件 - 機能の切り替えに関する要件

   • テンプレート：「[機能が含まれる場合]、システムは [要件] を SHALL する」
   • 例：「プレミアムサブスクリプションが有効な場合、システムは高度な分析機能を有効にする SHALL」

調査プロトコル（要件を引き出す前に実施）：

要件に関する質問を始める前に、調査を通じてコンテキストを集めます。

1. 先行事例の調査

   • WebSearch を使って、類似する機能や製品を探します
   • 検索クエリ：「[feature type] best practices 2025」
   • 検索クエリ：「[feature type] common requirements」

2. 技術ドキュメント

   • WebFetch を使って、関連する技術ドキュメント、API、規格を取得します
   • 競合製品や類似製品のドキュメントを取得します

3. API の調査（該当する場合）

   • Bash と curl を使って API エンドポイントを調べます
   • API ドキュメントとスキーマを取得します

4. 調査結果の記録

   • 重要な知見を、requirements.md の「## Research Summary」セクションに要約します
   • 発見したパターン、アンチパターン、業界標準を記録します

🗣 次のように伝えます：「要件を定義する前に、類似した実装を調査します。」

---

体系的な質問のアプローチ：

要件を引き出すために、ユーザーに次の質問をします。

1. 中核となる機能

   • 「この機能の主な目的は何ですか？」
   • 「どのような問題を解決しますか？」

2. イベント駆動型の要件

   • 「どのようなユーザー操作がこの機能のトリガーになりますか？」
   • 「どのようなシステムイベントが関係しますか？」

3. 状態駆動型の要件

   • 「状態やモードに違いはありますか？」
   • 「それぞれの状態で何が起きるべきですか？」

4. 条件付きの要件

   • 「ユーザーやロールによって動作に違いはありますか？」
   • 「どのような条件が機能に影響しますか？」

5. パフォーマンス要件

   • 「応答時間に関する要件はありますか？」
   • 「想定される負荷や規模はどの程度ですか？」

6. セキュリティ要件

   • 「どのデータを保護する必要がありますか？」
   • 「誰がアクセスできる必要がありますか？」

7. エラー処理

   • 「どのような問題が起こり得ますか？」
   • 「エラーをどのように処理すべきですか？」

8. エッジケース

   • 「境界条件は何ですか？」
   • 「極端な状況では何が起きますか？」

ベストプラクティス：

• 必須要件には「SHALL」を使います
• 具体的かつ測定可能な表現にします（「すばやく」ではなく「2秒以内に」とします）
• 1つの要件につき、記述は1つにします
• 曖昧な用語（「適切な」「妥当な」「ユーザーフレンドリーな」など）は避けます
• 能動態を使います

要件 ID とトレーサビリティ：

• 一貫したプレフィックス（例：REQ-001）を使って、すべての要件に一意の ID を割り当てます。
• すべての要件タイプ（機能要件と非機能要件）を通じて、番号を連番にします。
• 後続のタスクから参照できるよう、各要件の行に ID を直接記載します。
• タスクや設計をこれらの ID に対応付ける方法を示す、短いトレーサビリティ注記を追加します。

出力形式： docx/features/[NN-feature-name]/requirements.md を更新し、次の内容を含めます。

• 概要セクション
• 機能要件（EARS のタイプ別に整理）
• 非機能要件（パフォーマンス、セキュリティ、ユーザビリティ）
• 制約事項
• 受け入れ基準（チェックボックス）
• 対象範囲外の項目

ユーザーの確認：

「要件がまとまりました。設計フェーズに進みますか？」

---

フェーズ 3：技術設計

目標： アーキテクチャ上の決定を含む、包括的な技術設計を作成します。

調査プロトコル（設計の前に実施）：

アーキテクチャのアプローチを提案する前に、解決策を調査します。

1. アーキテクチャの調査

   • WebSearch を使用：「[technology] architecture patterns 2025」
   • WebSearch を使用：「[problem domain] implementation approaches」

2. ライブラリ／フレームワークの調査

   • WebFetch を使用して、候補となるライブラリのドキュメントを確認します。
   • 類似プロジェクトで採用されているアプローチを比較します。

3. API の調査（該当する場合）

   • WebFetch を使用して、外部 API のドキュメントを確認します。
   • Bash と curl を使用して、API エンドポイントをテストします。
   • 統合要件と制約を把握します。

4. 調査結果の文書化

   • design.md に「## Technical Research」セクションを追加します。
   • 情報源へのリンクと主な知見を記載します。

🗣 言う：「アーキテクチャの選択肢を提案する前に、技術的なアプローチを調査します。」

---

プロセス：

1. ブレインストーミングの統合

   • Skill ツールを使用して、dev-workflow:brainstorming を呼び出し、協調的な設計検討を行います。
   • 2～3 種類のアーキテクチャアプローチを検討します。
   • 各アプローチのトレードオフを話し合います。

   有効化する方法：

   Use Skill tool: Skill(skill: "dev-workflow:brainstorming")
   

複雑な設計に対する UltraThink： 技術的なアプローチを提案する前に、次の場合は深く考えるためのモードを有効にします。

• アーキテクチャに複数のサービスや複雑なデータフローが含まれる
• アプローチ間のトレードオフが明確でない
• 設計がセキュリティ、パフォーマンス、またはスケーラビリティに影響する
• 要件に矛盾がある、または不完全に思われる

🗣 言う：「この設計には深い思考が必要です。アプローチを提案する前に、アーキテクチャの基本を徹底的に考えます。」

UltraThink 中に検討すること：

• 私たちは適切な問題を解決しているでしょうか？
• 間違っているかもしれないのに、何を前提としているでしょうか？
• 大規模な負荷で何が壊れる可能性があるでしょうか？
• 機能する最もシンプルなアーキテクチャは何でしょうか？
• 各アプローチには、どのような隠れたコストがあるでしょうか？
• ゼロから始めるとしたら、何を変えるでしょうか？

UltraThink の後： アーキテクチャ上のトレードオフとスケーラビリティに関する考慮事項を明確に説明しながら、各アプローチを提示します。

2. アプローチの比較 トレードオフを示しながら、選択肢を提示します。

   オプション A：[アプローチ名]

   • メリット：[利点]
   • デメリット：[欠点]
   • 複雑さ：低／中／高
   • 期間：[見積もり]

   オプション B：[アプローチ名]

   • メリット：[利点]
   • デメリット：[欠点]
   • 複雑さ：低／中／高
   • 期間：[見積もり]

3. 推奨案

   • 推奨するアプローチを明示します。
   • 明確な根拠を示します。
   • そのアプローチが要件に最も適している理由を説明します。

4. 設計ドキュメントの構成 以下を網羅する包括的な design.md を作成します。

   アーキテクチャの概要

   • 機能がシステムにどのように組み込まれるか
   • 高レベルのコンポーネント図（ASCII アート）

   コンポーネント構成

   • 各コンポーネントとその責務の一覧
   • コンポーネント間の依存関係の定義
   • 公開インターフェースの指定

   データフロー

   • データの移動をステップごとに説明
   • フローを示す図

   API コントラクト

   • 入力／出力スキーマ
   • エラーレスポンス
   • リクエスト／レスポンスの例

   エラー処理

   • エラーのシナリオと処理方針
   • フォールバック動作

   セキュリティ上の考慮事項

   • 認証／認可
   • 入力検証
   • データ保護

   パフォーマンス上の考慮事項

   • 最適化戦略
   • キャッシュの方法
   • データベースのインデックス要件

   テスト戦略

   • ユニットテストの対象領域
   • 統合テストのシナリオ
   • E2E テストのワークフロー

承認ゲート：

「設計が完了しました。タスクの分解に進んでもよろしいですか？」

次に進む前に、ユーザーから明示的な承認を得るまで待ちます。

---

次のステップ

Quick モードの後（plan.md を保存した後）：

/dev-workflow:spec execute を実行します。実装スキルは plan.md を自動検出し、Quick 実行を行います。手順に従い、検証コマンドを実行して、コミットします。RGR の強制はありません。

Full モード（design.md 承認済み）の後：

/dev-workflow:spec tasks を実行し、続けて /dev-workflow:spec execute を実行します。実装スキルが tasks.md を検出し、Full 実行を開始します。各タスクで RED-GREEN-REFACTOR を行い、要件 ID へのトレーサビリティを確保し、品質ゲートを適用します。

どちらのモードも dev-workflow:review、dev-workflow:git-workflow、dev-workflow:test-driven-development と連携します（最後のものは Full モードでは必須、Quick モードでは任意です）。

---

アップグレードパス：Quick → Full

Quick の機能が計画の範囲を超えた場合（スコープが拡大する、関係者が加わる、アーキテクチャ上の決定が必要になるなど）：

1. 既存の docx/features/[NN-name]/plan.md を読みます
2. そこから Full モード用の 3 つのファイルを作成します：
   • requirements.md — Goal とタスクから暗黙的な要件を抽出し、EARS 形式で書き直して、REQ-### ID を割り当てます
   • design.md — Architecture と Tech Stack を抽出し、ユーザーに質問して「検討した代替案」を追加します
   • tasks.md — タスクを、要件 ID と関連付けた RED/GREEN/REFACTOR に再分割します
3. トレーサビリティを確保するため、plan.md を plan.archived.md に変更します
4. Full プレイブックのフェーズ 2（要件）またはフェーズ 3（設計）から再開します

ダウングレード（Full → Quick）はサポートされていません。EARS 形式の要件を作成した後に破棄するのは無駄なので、そのまま Full モードを続けてください。

---

例

例 A：Quick モード（自動選択）

ユーザー：「レポートページに CSV エクスポートボタンを追加してください」

アシスタント：

Signals: solo, ~1 day, no compliance, no architectural decision → Quick mode.

Created docx/features/03-csv-export/plan.md with 4 tasks.
Review and approve, then run /dev-workflow:spec execute.

例 B：Full モード（自動選択）

ユーザー：「Web とモバイル全体にユーザー認証を追加してください。SOC 2 への準拠が必須です」

アシスタント：

Signals: multi-platform, compliance required, JWT vs session decision → Full mode.

Created docx/features/04-user-authentication/{requirements,design,tasks}.md.
Phase 1 complete. Phase 2: I'll elicit requirements in EARS format.

1. What authentication methods should be supported?
2. What's the session lifetime requirement?
[...]

例 C：曖昧な場合（ユーザーに確認）

ユーザー：「通知システムを追加してください」

アシスタント：

Scope is ambiguous between Quick and Full. Pick one:

1. Quick — single plan.md, no EARS, no RGR (≤3 days, solo)
2. Full — 3-file spec with EARS + TDD (>1 week, team, compliance)

Default if you don't pick: Quick.

---

注意事項

• フェーズ間では必ず明示的な承認を求めてください
• 要件には EARS 形式を厳密に使用してください
• 「実行」ではなく「何をするか」と「どのようにするか」に焦点を当ててください
• 推奨する前に、複数のアーキテクチャ案を検討してください