writing-plans

計画の作成

実行する人の曖昧さを減らす、実行可能な実装計画を作成します。フェーズ1からフェーズ6にわたる大規模な作業を、/goal でラップして実行します（以下を参照）。

推奨：/goal でラップして実行

Claude Code に組み込まれている /goal（v2.1.139+）の下で起動してください。そうすることで、フェーズの途中で停止せず、計画をコミットするまで実行が継続します。

/goal "Claude has narrated a successful plan commit (with commit hash) and reported the Phase 4 reflection sub-agent verdicts inline" /superpowers:writing-plans <design-path>

/goal はユーザーが入力する外側のラッパーです（スキルが実行途中に自分自身に対して有効化することはできません）。その評価器が判定するのは、トランスクリプト内で Claude が説明した内容だけです。条件は、ファイルシステムの状態ではなく、ナレーションされた出力（コミットハッシュや、フェーズ4の振り返りの要約そのものなど）を基準に表現してください。詳しい仕様と条件の表現方法については、../../skills/references/goal-wrapper.md を参照してください。

重要：中止判定（最初に実行）

解決された設計フォルダーにある bdd-specs.md を読み込み、Scenario: の出現数を数えてください。次のいずれかに該当する場合は中止し、タスクを分解してはいけません。

• bdd-specs.md の BDD シナリオが3件未満、または
• 推定タスク数の合計が5件未満（BDD シナリオ数×2 + セットアップタスク1件 で推定するか、設計フォルダーの _index.md に明示的な「タスク見積もり」があれば、そちらを優先してください）

OR 条件により、AND 条件では見逃される「BDD が2件でセットアップタスクが多数」のケースも検出できます。

中止時の応答（以下をそのまま出力）：

完全なタスク分解パイプラインを実施するには設計が不十分です（BDD < 3 OR 推定タスク数 < 5）。代わりに、インラインで1ページの簡易計画を作成します。完全なパイプラインを強制するには、/superpowers:writing-plans --force <design-path> として再実行してください。

次に、単一の _index.md のみを作成し（タスクごとのファイル、フェーズ4の振り返り、計画評価器は使用しません）、終了してください。--force トークン（$ARGUMENTS 内にそのまま含まれ、大文字と小文字を区別する完全一致のトークン）を指定すると、この判定を回避できます。

重要：正当性の判定（中止判定の後に実行）

解決された設計フォルダーにある _index.md を読み込み、grep が次のいずれかに一致する場合は中止し、タスクを分解してはいけません。

grep -nE "STATUS:.*NOT.JUSTIFIED|DESIGN-NOT-YET-JUSTIFIED|DESIGN-CONSIDERED-DEFERRED|DO NOT IMPLEMENT" "<resolved-design-folder>/_index.md"

この判定により、「次に進む承認を得ていない」と明示された設計を検出します（詳しい仕様については docs/retros/checklists/design-v1.md の JUST-01 を参照。きっかけとなった事例は docs/retros/2026-05-09-v3-considered-deferred.md）。

一致した場合は、決定的に拒否してください（このマーカーは決定的な根拠です。解釈によって無効化してはいけません）。

1. 次の1行のメモを出力します。Refusing: <design-path>/_index.md:{N} is marked NOT-JUSTIFIED — '{matched text}'. Re-invoke /superpowers:brainstorming to revise the design, or pass --justify-override to bypass this gate.
2. 先に進まず終了します。

オーバーライド：--justify-override（$ARGUMENTS 内にそのまま含まれ、大文字と小文字を区別する完全一致のトークン）を指定すると、この拒否を回避して最初のアクションに進めます。

禁止事項：--force（サイズ判定のみを回避）と --justify-override（この正当性判定のみを回避）を混同してはいけません。これらは独立しています。設計が不十分な場合に --force を指定しても、NOT-JUSTIFIED の拒否は回避できません。

最初のアクション — 設計パスの解決

1. 設計パスを解決します。
   • $ARGUMENTS にパス（例：docs/plans/YYYY-MM-DD-topic-design/）が指定されている場合は、それを使用します。
   • 指定されていない場合は、YYYY-MM-DD-*-design/ 配下でベース名が最後にソートされる *-design/ フォルダーを選びます。フォルダー名に含まれる日付の接頭辞が最も新しいものを選び、ファイルシステムの更新日時は使いません。ls -1d docs/plans/*-design/ 2>/dev/null | sort | tail -1 を実行します（ls -t は使用しません。更新日時によって、新しいフォルダーよりも古いフォルダーが優先される場合があるためです）。結果をそのまま使用し、確認のために処理を中断してはいけません。
   • docs/plans/ に *-design/ フォルダーがない場合は、Refusing: no design folder found under docs/plans/. Run /superpowers:brainstorming first, or pass the design folder path explicitly. として拒否し、終了します。
2. 同じターン内に初期化へ進みます。

初期化

1. 設計チェック：フォルダーに _index.md と bdd-specs.md が含まれていることを確認します。ドラフトを作成する前に、ドキュメントのインデックスを確認してください：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" show <design-path> を実行します。ステータスが expired: の場合は、作業を拒否し、期限切れのステータスを記載した1行のメモを出力して、プランフォルダーを作成せずに終了します。次に、メモリーを確認します：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active を実行し、フェーズ1の前に、トピックとの関連性が最も高い上位の項目を読みます。
2. コンテキスト：bdd-specs.md を最後まで読みます。これがタスクの信頼できる情報源です。

背景知識

基本概念：暗黙より明示、粒度の細かいタスク、検証主導、コンテキストからの独立性。

必須：ユニットテストのタスクでは、テストダブルを使用して外部依存関係（DB／ネットワーク／サードパーティ API）を分離する必要があります。それ以外の分解に関する不変条件は、フェーズ2の手順1〜7で徹底されます。

フェーズ1：プランの構成

目標、アーキテクチャ、制約、コンテキストを定義します。

1. 仕様を読む：設計フォルダーの bdd-specs.md を読みます。
2. 構成をドラフトする：./references/structure-template.md を使用してプランの概要を作成します。
3. コンテキストセクションを記述する：_index.md の ## Context に、この作業が必要な理由（動機、制約、過去のインシデント）を記入します。既存コードを変更する場合は、現状と目標の比較表を追加します（新規開発の場合は省略します）。
4. グローバル制約セクションを記述する：_index.md の ## Global Constraints セクションに、すべてのバッチとすべてのタスクが遵守すべき横断的な不変条件を記入します（これにより、並列バッチを安全に実行できます）。箇条書き1つにつき不変条件を1つ記載し、説明文は追加しません。設計に横断的な制約がまったくない場合に限り、省略できます（まれです）。カテゴリと例については、./references/structure-template.md の §Global Constraints を参照してください。

フェーズ 2: タスク分解

特定の BDD シナリオにマッピングされた小さなタスクに分割します。

禁止: ユーザーに粒度の選択、分解の承認、プロセス途中での計画の確認を求めてはいけません — ステップ 1〜7 にこれらの追加事項を加えて自動的に適用します。フェーズ 4 の振り返りが品質ゲートであり、コミット後の git show の差分が監査対象です。

• 基盤タスク（セットアップ、共有スキーマ、型、設定、ストレージ）は、機能ペアより小さい NNN を付けます
• 1 つの Feature のすべてのシナリオを 1 つのテストファイルにまとめます。Feature が独立したサービス境界（例: フロントエンドとバックエンド）をまたぐ場合にのみ分割します

1. シナリオの参照: 重要: すべてのタスクは、Gherkin 構文を使用して完全な BDD シナリオの内容をタスクファイルに明示的に含めなければなりません — bdd-specs.md への参照だけでなく自己完結させ、実行者がファイルを切り替えることなく完全なシナリオを確認できるようにします。形式: ./references/structure-template.md §BDD Scenario。
2. 検証の定義: 重要: 検証ステップでは BDD スペックを実行する必要があります（例: npm test tests/login.spec.ts）。
3. 順序の強制: 各機能 NNN について、テストタスク（task-NNN-<feature>-test）は depends-on を介して対になる実装タスク（task-NNN-<feature>-impl）より先行しなければなりません。
4. 依存関係の宣言: 必須: 各タスクファイルには **depends-on** フィールドを含め、真の技術的前提条件のみを列挙しなければなりません — このタスクを開始する前にその出力が必要となるタスクです。禁止: 実行順序を課すためだけにタスクを連鎖させること。独立性のルールと例: ./references/task-granularity-and-verification.md §Dependency Rules。
5. タスクファイルの作成: 必須: タスクごとに 1 つの .md ファイルを作成します。ファイル名パターン: task-<NNN>-<feature>-<type>.md（例: task-001-setup.md、task-002-feature-test.md / task-002-feature-impl.md — 同じ機能のテストと実装は NNN プレフィックスを共有します。タイプ: test、impl、config、refactor。完全なテンプレート: ./references/structure-template.md §Task Files）。
   • 適正なサイズ設定: 唯一の利用元が単一の機能タスクである場合、独立したセットアップ/設定/ドキュメントタスクを捏造してはいけません — それらを必要とするタスクに折り込みます。独立した task-001-setup が正当化されるのは、2 つ以上の下流タスクがその出力を共有する場合のみです。疑似独立したセットアップタスクは、偽の並列性を生み出しバッチ数を膨らませます。
6. インターフェースの宣言: 必須: 各タスクファイルには、このタスクが公開または消費するコントラクト（関数シグネチャ、型、API エンドポイント、イベント名、CLI フラグ）を宣言する ## Interfaces セクションを（## BDD Scenario の後に）含めます。depends-on でリンクされたタスクはこれらのブロックを介して接続するため、並列バッチはマージ前にインターフェースの互換性を検証できます。
7. 「何を」を記述し、「どのように」は記述しない: 禁止: 実装本体を生成してはいけません。何を実装するかを記述します。## Interfaces ブロックのインターフェースシグネチャはコントラクトを定義しますが、本体のロジックは決して記述しません。

フェーズ 3: 検証とドキュメント化

完全性を検証し、保存し、同じイテレーションでフェーズ 4 に進みます。

1. 検証: 有効なコミット境界があり、曖昧なタスクがないことを確認します。失敗した場合、一時停止せずに — 同じイテレーションでフェーズ 2 に再入して該当するタスクを修正し、その後再検証します。
2. 保存: docs/plans/YYYY-MM-DD-<topic>-plan/ フォルダに書き込みます。
   • 重要: _index.md には インライン YAML メタデータを含む「Execution Plan」セクションを含めなければなりません
   • 重要: _index.md には、すべてのタスクファイルをリンクする「Task File References」セクションを含めなければなりません
   • 重要: _index.md には、すべてのシナリオがカバーされていることを確認する「BDD Coverage」セクションを含めなければなりません
   • 重要: _index.md には、視覚的な依存関係グラフを含む「Dependency Chain」セクションを含めなければなりません（フェーズ 4 で入力されます）
   • YAML メタデータとファイル参照の例: ./references/structure-template.md §Execution Plan

フェーズ 4：計画の振り返り

コミットする前に、メインの計画セッションの影響を受けない分離されたコンテキストで、並列に実行する新規サブエージェントを使って計画の品質を検証します。

Agent ツールで subagent_type=general-purpose を指定し、3 つのサブエージェントを並列に起動します（完全なプロンプトテンプレート：./references/reflection.md）。

1. BDD カバレッジレビュー — 設計シナリオごとに対応するタスクがあることを確認します。カバレッジマトリクス、対応タスクのないシナリオ、余分なタスクを出力します
2. 依存関係グラフレビュー — depends-on の正しさ、循環、依存関係の欠落を確認します。依存関係グラフを出力します
3. タスク完全性レビュー — 各タスクに必要な構成（BDD シナリオ、ファイル、手順、検証）を確認します。不完全なタスクの一覧を出力します

追加のサブエージェント（必要に応じて起動）：Red-Green ペアリングレビュー、ファイル競合レビュー。

統合と更新：

1. すべてのサブエージェントの指摘を集め、影響度の高い順に優先順位を付けます
2. 指摘を解消するため、計画ファイルを更新します
3. 必須：サブエージェント 2 の依存関係グラフを _index.md の「Dependency Chain」に追加します
4. 更新したセクションを再検証します
5. 振り返りの概要を、ターンの出力にインラインで記録します（サブエージェントの判定ごとに 1 行と、変更内容）— コミット後にユーザーが git show で確認する監査記録です。承認を求めて一時停止しないでください

出力：更新済みの計画、_index.md 内の依存関係グラフ、インラインの振り返り概要 — フェーズ 5 に進める状態。

途中キャンセル（/goal の実行時のみ。ユーザーが「abort」／「cancel」／「start over」を入力した場合）：1 行のメモを出力して停止します。コミットもフェーズ 5 への移行もしません。再試行する場合、ユーザーは新しい指示で再度呼び出します。

複数ターンにわたる再開（中断されたターンの後に /goal でラップされている場合のみ）：フェーズ 1 から再開しないでください — Glob "docs/plans/*-plan/_index.md" を実行し、進行中の計画フォルダーを読み込み、ファイルシステムの状態に応じたフェーズから再開します。タスクファイルは存在するものの、_index.md に YAML の tasks: ブロックまたは References／Coverage セクションがない場合はフェーズ 3、_index.md は完成しているものの「Dependency Chain」グラフがない場合はフェーズ 4、計画は完成していてコミットされていない場合はフェーズ 5、すでにコミット済みの場合はフェーズ 6 です。

計画品質をレビューするのはサブエージェントのみです（別途、計画モードの評価者は設けません。ユーザーはコミット後に git show でレビューします）。サブエージェントは、評価基準として docs/retros/checklists/plan-v{N}.md を読みます。チェックリスト項目に FAIL があった場合は、該当する計画ファイルを修正し、そのサブエージェントを再実行してください。未対応の FAIL がある計画はコミットしないでください。

チェックリストがない場合は自動的に生成：振り返り用サブエージェントを起動する前に、plan-v{N}.md が存在しない場合は bash "${CLAUDE_PLUGIN_ROOT}/lib/seed-checklists.sh" plan docs/retros/checklists/plan-v1.md を実行します（終了コード 0 = 生成済み、3 = すでに存在するため続行、1／2 = 中止）。その後、解決済みのチェックリストパスを各サブエージェントのプロンプトに渡します。

必須：各振り返り用サブエージェントのプロンプトには、解決済みのチェックリストファイルを読み、各項目を二択の PASS／FAIL 評価基準として適用する指示を含めてください（./references/reflection.md の §Checklist Binding にあるテンプレートにこの指示が含まれています。削除しないでください）。チェックリストなしで実行するサブエージェントの評価は、根拠に基づく判定ではなく、基準の定まらない意見です。

Phase 5：Git コミット

git-agent（利用できない場合は git にフォールバック）を使って、プランフォルダーをコミットします。

アクション： 0. プランをドキュメントインデックスに登録（更新）する（git add の前）：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert plan <new-plan-path> --status active --summary "<one-line>" を実行します。重要：後回しにしないでください。インデックスの更新は、プランフォルダーと同じコミットグループに含めます。 0.5. 重要：後回しにしないでください：Phase 4 のサブエージェントが初回の PASS ではなく、修正と再実行が必要な FAIL になった場合に限り、メモリーを書き込む条件付きのステップです。該当する場合は、誤検知の原因を記録した docs/memory/pitfall_<slug>.md を作成し、続けて bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/pitfall_<slug>.md --status active --summary "<one-line>" --category pitfall を実行します。すべてのサブエージェントが初回で合格した場合は何もしません。

1. フォルダー全体を、1 つの連結コマンドでステージングしてコミットします。単独の git add は git プラグインのフックによって拒否されます：git add docs/plans/YYYY-MM-DD-<topic>-plan/ && git-agent commit --no-stage --intent "add implementation plan for <topic>" --co-author "Claude <Model> <Version> <[email protected]>"
2. 認証エラーの場合は、--free フラグを付けて再試行します。
3. フォールバック：git-agent を利用できない、または失敗した場合は、Skill ツールを使って /git:commit スキルを呼び出します。完全な手順は ../../skills/references/git-commit.md を参照してください。

Phase 6：実行への移行

次の内容を出力します：

プランが完了しました。このプランを実行するには、/superpowers:executing-plans を使用してください。

禁止事項：実装を直接開始することを提案しないでください。

終了基準

目標と制約が明確であること、ファイルリストと検証方法を含むタスク分解、BDD ステップ、コミット境界、曖昧なタスクがないこと、振り返りが完了しすべての FAIL に対処済みであること、Git コミットが完了していること。

参考資料

• ./references/structure-template.md - プランおよびタスクファイルのテンプレート
• ./references/task-granularity-and-verification.md - タスクの分解、検証、依存関係のルール
• ./references/reflection.md - プランの振り返りに使用するサブエージェント向けプロンプト
• ../../skills/references/git-commit.md - Git コミットのパターン
• ../../skills/references/goal-wrapper.md - /goal のセマンティクスと条件の表現（共通）