spec-plan

Spec Plan

どのエンジニアでも実行できるよう、明確で適切な分量の計画を作成します。選択された計画モードによって、計画を会話内にとどめるか、永続化される構造化アーティファクトにするかが決まります。このスキルでは、コードの作成や実装の開始は行いません。

自動分類はatelier-orchestratorが担当し、人間が変更できます。このスキルを直接呼び出したときにモードが選択されていない場合は、Spec-backed Planを使用します。Inline planningで大規模な設計や調整が必要だと分かった場合は、計画を提示する前に、Spec-backed Planに切り替えるか人間に確認してください。

終了時の境界

このスキルが出力する計画は1つだけです。出力後は終了します。

• Inlineモードでは、計画を会話内に提示し、リポジトリのファイルは変更しません。
• Spec-backedモードでは、承認済みのdesign.mdに基づいてplan.jsonのみを作成または更新します。

計画の草案作成や注釈のやり取りは会話内で行います。design.mdを変更したり、Markdown形式の計画草案を永続化したり、トラッカーのエントリーを作成したり、別のワークフロースキルを呼び出したり、実装ファイルを編集したりしてはいけません。人間から計画と実装を1つの依頼で求められた場合も、このルールは適用されます。実装には、このスキルの終了後に明示的な依頼が必要です。

計画ルール

• タスクはレイヤーごとではなく、必要な振る舞いを軸に構成します。
• 変更後も維持する必要がある振る舞いを、簡潔に列挙します。
• 各タスクについて、再利用、変更、または削除する既存コードを特定します。
• すべての新しい抽象化について、対応する既存の要件と現在の利用箇所を示します。
• 同じニーズがあることを2つ以上の現在の利用箇所で確認できる場合に限り、共有インフラストラクチャを導入します。
• 変更される契約と対象となる境界ごとにテストをまとめます。レイヤーをまたいでCRUDマトリクスを繰り返さないでください。
• 各モジュールのインターフェースまでをテスト計画に含め、それを越えないようにします（oracle-codebase-designを参照）。

適正規模の確認

計画を提示する前に、その規模や概念を依頼された振る舞いと比較します。範囲が限定された移行やリファクタリングによって、共有インフラストラクチャや無関係な振る舞いが導入される場合、または計画が変更対象の振る舞いに比べて大幅に大きい場合は、いったん止めて簡素化してください。

チャレンジ確認

計画を提示する前に、草案と設計の背景情報を添えて、読み取り専用のサブエージェントを2つ並行して起動します。それぞれのエージェントを明示的に選択してください（atelier-orchestratorの「Delegation」を参照）。

1. 設計レビュー： アーキテクチャとの適合性、レイヤーとデータモデルの境界、API契約、タスクの順序が依存関係に沿っているかを確認します。
2. 批判的検討： 前提に異議を唱え、見落とされたケース、スコープの拡大、根拠のない要件を探し、より簡潔な代替案を提案します。

各エージェントの指摘は、根拠を示したものを最大5件までとします。有効な指摘を計画に反映し、採用しなかった指摘には理由を添えて除外します。何を変更したかを記す短いチャレンジ済みの注記を添えて、計画を提示します。

Spec-backed Planでは毎回この確認を実施します。Inline Planでは、変更がデータモデル、API契約、または複数のモジュールやレイヤーに関わる場合に限り実施します。小規模で範囲が限定された編集では省略します。確認は草案ごとに1回実施し、計画の構成が変わらない限り、人間による注釈の修正では再実施しません。

出力

Inline Plan（明示的に選択された場合）

リポジトリのアーティファクトもタスクトラッカーのエントリーも作成しません。references/plan_template.mdを読み、その構成に従って会話内に計画を提示します。任意の小見出しは、空の見出しとして出力せず、省略してください。

インライン計画ワークフロー

現在の動作、境界、影響を受けるファイル、具体的な検証方法を特定できるだけのコードベースを読みます。計画の規模は実装リスクに見合ったものにします。確認済みのファイルおよびシンボル単位の詳細をテンプレートに記入します。重要な箇所では、ファイル間の接続や順序の制約も含めます。提示する前に、Planning Rules、Proportionality Gate、Challenge Gate を適用してください。

フェーズ、タスク ID、依存関係グラフ、受け入れマトリクス、design.md、plan.json、トラッカー項目、ハーネスの TODO を作り上げてはいけません。会話が計画の成果物です。

人間に次のように伝えてください：「インライン計画のレビュー準備ができました。」

停止してください。人間のレビューを待ちます。

人間が修正を求めた場合は、作業中の計画に反映し、references/plan_template.md を使って更新後の計画全体を再提示してください。変更のないセクションも含め、人間が一貫した計画全体をレビューできるようにします。変更箇所だけ、影響を受けるセクションだけ、要約、了承の返答だけで応じてはいけません。一語の修正であっても計画の改訂です。反映して、計画全体を再提示してください。

改訂のたびに、以前の承認は無効になります。改訂した計画の末尾には「インライン計画のレビュー準備ができました。」と記載し、人間がその完全版を明示的に承認するまで停止してください。現在の計画が承認されるまで、実装してはいけません。

人間がインライン計画を承認したら、計画が承認されたことを伝えて停止してください。同じ呼び出しで実装してはいけません。後から明示的に実装を依頼された場合は、atelier-orchestrator のインライン実行セーフガードに従い、承認済みの会話上の計画を直接実行できます。この実行では、spec-implement、spec-finish、code-subagents、タスク追跡は使用しません。

仕様に基づく計画成果物

docs/specs/YYYY-MM-DD-<feature-name>/
├── design.md  ← From spec-brainstorm (approved)
└── plan.json  ← This skill's output

計画はまず、人間が注釈を加えるための会話上の草案として始まり、承認後に構造化された plan.json に変換されます。

plan.json スキーマ

{
  "feature": "user-authentication",
  "spec": "docs/specs/2026-03-08-user-auth/design.md",
  "goal": "Add email/password authentication with session management",
  "preserved_behavior": [
    "Existing sessions remain valid"
  ],
  "phases": [
    {
      "id": "P1",
      "name": "Authenticate with email and password",
      "tasks": [
        {
          "id": "T1",
          "name": "Accept valid credentials and reject invalid credentials",
          "depends_on": [],
          "inputs": [
            "User schema from design.md",
            "Validation rules (email format, password strength)"
          ],
          "description": "Create UserEntity with email and password fields. Implement validation using a Result type. Password must be hashed, never stored plaintext.",
          "files": {
            "reuse": ["src/auth/password.ts"],
            "create": ["src/entities/user.ts", "tests/entities/user.test.ts"],
            "modify": [],
            "delete": []
          },
          "new_abstractions": [
            {
              "name": "UserEntity",
              "requirement": "Validate email/password credentials",
              "consumers": ["POST /sessions"]
            }
          ],
          "validation": {
            "tests": [
              "rejects empty email",
              "rejects invalid email format",
              "rejects weak password",
              "accepts valid user input"
            ],
            "acceptance": [
              "All validation tests pass",
              "User.fromRequest returns Result<User>",
              "No direct throws — all errors via Result"
            ]
          }
        }
      ]
    }
  ]
}

最上位フィールド

フィールド	型	説明
feature	string	ケバブケースの機能名
spec	string	承認済みの design.md へのパス
goal	string	1 文で記述した目標
preserved_behavior	string[]	変更せず維持する必要がある既存の動作の短いリスト
phases	Phase[]	依存関係順の実装フェーズ

フェーズのフィールド

フィールド	型	説明
id	string	フェーズ識別子（P1、P2 など）
name	string	フェーズ名（例：「ドメインモデル」「データアクセス」）
tasks	Task[]	このフェーズ内のタスク

タスクのフィールド

フィールド	型	説明
id	string	タスク識別子（T1、T2 など）
name	string	このタスクで実装する内容
depends_on	string[]	先に完了する必要があるタスク ID
inputs	string[]	作業開始前に把握しておく必要がある情報
description	string	構築するもの、重要な判断、制約
files	{reuse, create, modify, delete}	再利用、変更、削除する既存コードと、新たに作成するファイル
new_abstractions	{name, requirement, consumers}[]	新しい抽象化を、対応する現行要件および現在の利用者に関連付けたもの
validation	{tests, acceptance}	タスクの完了を確認する方法

---

仕様に基づくステップ 1：計画の草案を作成する

承認済みの design.md を読み、草案に Challenge Gate を適用してから、会話内で計画の草案を提示します。草案を design.md に書き込んだり、別の草案ファイルを作成したりしてはいけません。

計画の品質

実装者が次の条件を満たすことを前提に記述します。

• 言語とフレームワークを理解している
• このコードベース固有のパターンは知らない
• 明確な境界と検証基準を必要としている
• 計画が曖昧であれば、最も手間のかからない方法を選ぶ

タスクの構成

各タスクは単独で完結し、以下を含める必要があります。

• 入力：開始前に必要な情報や準備（仕様、既存コードなど）
• 説明：実装する内容、重要な設計上の判断、制約
• ファイル：再利用、変更、削除する既存コードと、新規作成するファイルを正確に指定
• 新しい抽象化：それぞれに必要となる要件と現在の利用側を記載します。タスクで追加しない場合は空のリストを使用します
• 検証：変更された契約とアクティブな境界ごとにテストを分類し、受け入れ条件も記載します

コードの具体例は含めないでください。実装の詳細も含めないでください。タスクでは、コードの書き方ではなく、何を実現し、どう検証するかを示します。

タスクの順序

必要な振る舞いと実際の依存関係に基づいてタスクを並べます。1つの契約を実装・検証するために複数のレイヤーにまたがる変更は、1つのタスクにまとめます。レイヤーごとにタスクを分割しないでください。

タスクの規模

各タスクの所要時間は15～60分としてください。それより大きい場合は、より小さなタスクに分割します。

人間に伝えること：「計画のドラフトがレビュー用にできました。」

停止してください。人間のレビューを待ちます。

---

仕様に基づくステップ2：注釈サイクル

人間は、計画のドラフトに直接注釈を追加します。修正、却下、ドメイン知識、ビジネス上の制約、「これはすべて削除」などを記入します。

You write plan → Human adds inline notes → You address all notes → Repeat 1-6x

人間が「注釈を追加しました」と伝えたら、次の手順を実行します。

1. ドキュメント全体を読み直す
2. すべての注釈に対応する
3. 計画を更新する
4. タスクを作成しないでください。実装しないでください。

「まだ実装しない」という制約は厳守してください。人間が明示的に承認するまで、計画は完成ではありません。

指示のパターン

パターン	例	対応
前提を修正する	「PUTではなくPATCHを使う」	修正する
アプローチを却下する	「キャッシュは不要なので削除する」	すっきりと削除する
制約を追加する	「キューコンシューマーはすでにリトライを処理している」	構成を見直す
選択を変更する	「生SQLではなくdrizzle:generateを使う」	指示どおりに変更する
セクションの方向を変える	「表示項目ではなくリストに表示する」	セクションを再検討する
範囲を縮小する	「ダウンロードは今は実装しないので削除する」	削除する。スタブは作らない

---

仕様に基づくステップ3：構造化タスクの作成

人間が「よさそうです」「承認します」「タスクを作成してください」と承認したら、計画をplan.jsonに変換します。

実行内容

1. 注釈を反映した計画のドラフトを、構造化されたplan.jsonに変換する
2. 各タスクは、入力、説明、ファイル、検証を含む単位に対応させる
3. タスク間の依存関係はdepends_onフィールドに記録する
4. トラッカーのエントリーを作成したり、plan.json以外のファイルを変更したりしない

検証

plan.jsonを作成した後、次を確認します。

• すべてのタスクにIDとdepends_onフィールドがある
• 依存関係が有効なDAGを形成し、循環がない
• すべてのタスクに入力、説明、検証がある
• 維持する振る舞いが簡潔かつ明確である
• すべてのタスクで、再利用、変更、削除するコードが特定されている
• 新しい抽象化ごとに、現在の要件と利用側が明記されている
• 共有インフラには、同じ必要性が実証されている現在の利用側が少なくとも2つある
• ファイルパスが完全かつ具体的である
• 検証条件が具体的でテスト可能であり、変更された契約とアクティブな境界ごとに分類されている
• 計画がProportionality Gateに合格している

---

引き継ぎ

plan.jsonを作成したら、そのパスを報告して停止します。

人間に次のように伝えます。

"Planning complete. Plan written to docs/specs/<path>/plan.json. A separate spec-implement invocation can execute it."

spec-implementを呼び出したり、実行モードを提示したり、実装を開始したりしないでください。人間は、別のリクエストで実装を開始する必要があります。

承認済みの振る舞い、範囲、アーキテクチャ、公開契約、主要な依存関係に変更がない軽微な実装上の差異は、インラインで記録し、plan.jsonに反映してもかまいません。重要な変更については再承認を得るためspec-planに戻します。設計の変更についてはspec-brainstormに戻します。反復のパターンについてはatelier-orchestratorを参照してください。

クイックリファレンス

選択したモード／ユーザーの発言	実行する内容
インライン／「計画を書いて」	テンプレートに基づくインライン計画の全文を提示し、停止します
インライン／「メモを追加しました」	変更を反映し、更新後のインライン計画全体を再提示して、再承認を待ちます
インライン／「承認しました」	承認を確認して停止します。成果物の作成も実装も行いません
仕様書ベース／「計画を書いて」	design.md に基づいて計画のドラフトを書き、停止します
仕様書ベース／「メモを追加しました」	再読してすべてのメモに対応します。実装は行いません
仕様書ベース／「承認しました」／「タスクを作成して」	plan.json のみを作成し、そのパスを報告して停止します