create-spec

機能仕様の作成

計画についての会話を、エージェントが並行して実装できる構造化された仕様フォルダーに変換します。仕様では機能を、それぞれ単独で完結したタスクファイルに分割します。各ファイルには、コーディングエージェントがほかの情報を読むことなく、その内容だけを頼りに実装できるだけの詳細を記載します。

重要なポイントは、単一ファイルにまとめた実装計画は、コンテキストウィンドウに収まらないほど大きくなるか、独立して実行するには内容が浅くなりがちだということです。各タスクを、必要なコンテキストをすべて含む個別のファイルに分割することで、各エージェントのコンテキストを絞りながら、複数のエージェントが並行して作業できるようにします。

使用するタイミング

• 要件や技術的な詳細について話し合った計画の会話のあと
• ユーザーから仕様の作成、機能の計画、作業のタスク分割を依頼されたとき
• ユーザーがエージェントによる並行実装に向けて作業を準備したいとき

手順

ステップ 1：要件を収集する

会話に計画のコンテキスト（要件についての議論、技術的な決定、概要が示されたアーキテクチャ）がすでに含まれている場合は、その内容をすべて抽出します。仕様は唯一の信頼できる情報源となり、ここに記録されていない内容はすべて失われるため、見落としがないよう会話全体を確認してください。

計画についての会話がない場合は、ユーザーに質問してください。

• この機能は何を実現し、なぜ重要ですか？
• 受け入れ基準は何ですか？
• どのような技術的制約や決定がありますか？
• 関連するファイル、API、スキーマ、パターンは何ですか？

ステップ 2：機能名を決める

機能を明確に表すケバブケースの名前を選びます（例：add-user-auth、migrate-to-postgres、dashboard-redesign）。この名前が specs/ 配下のフォルダー名になります。

ステップ 3：タスクに分解する

実装を、個別に完結するタスクに分割します。各タスクは次の条件を満たす必要があります。

• 1 人のエージェントが 1 回のコーディングセッションで完了できる
• 範囲が明確かつ具体的である（1 つのタスクにつき 1 つの関心事）
• 完了時に、動作しテスト可能なコードを成果物として作成する
• 同じウェーブ内のほかのタスクと、変更するファイルが重複しない

粒度を慎重に検討してください。粗すぎるとエージェントが並行して作業できず、細かすぎるとタスク間のコンテキスト切り替えにかかるオーバーヘッドが大きくなります。一般的に、1 つの関心事に関わる 1～5 個のファイルを作成または変更するタスクが適切です。

ユーザーから明示的に依頼されない限り、テストタスク（単体テスト、E2E テスト）は含めないでください。

ステップ 4：依存関係グラフを作成する

各タスクについて、次の項目を特定します。

• 依存先：このタスクを開始する前に完了している必要があるタスク
• 依存元：このタスクの完了を待つタスク

依存関係のないタスクがウェーブ 1 になります。依存先がすべてウェーブ 1 にあるタスクがウェーブ 2 になります。以降も同様です。各ウェーブ内のタスクはすべて並行して実行できます。

ウェーブを割り当てる際は、同じウェーブ内のタスクが同じファイルを重複して変更しないことを確認してください。同じウェーブ内の 2 つのタスクで同じファイルを変更する場合は、片方を後のウェーブに移動します。同じブランチで作業する並行エージェントは、同じファイルを安全に変更できません。

ステップ 5：仕様フォルダーを作成する

specs/{feature-name}/ に次の構成を作成します。

specs/{feature-name}/
├── README.md
├── requirements.md
├── action-required.md
└── tasks/
    ├── task-01-{name}.md
    ├── task-02-{name}.md
    └── ...

各ファイルを作成する前に、references/ 内のテンプレートを読んでください。

• references/readme-template.md — README 用（依存関係グラフ、ウェーブ表、ステータス管理）
• references/task-template.md — 各タスクファイル用（すべてのコンテキストを含み、単独で完結）
• references/requirements-template.md — 要件ドキュメント用
• references/action-required-template.md — 手動で行う人間の作業用

タスクファイルには、トポロジカル順にゼロ埋め 2 桁の接頭辞を付けます。まずウェーブ 1 のタスク、次にウェーブ 2 のタスクという順にします。ウェーブ内の順序は任意ですが、一定にしてください。

ステップ 6：自己完結型のタスクファイルを作成する

これは最も重要なステップです。各タスクファイルは、コーディングエージェントが実装前に読む唯一のものです。エージェントが必要とする情報をすべて含める必要があります。

• 説明：何を構築するのか、また、それがこの文脈でなぜ重要なのか
• 依存関係のコンテキスト：このタスクで必要となる、先行タスクの成果物（ファイル名だけでなく、文章で要約してください）。エージェントが他のタスクファイルを読む必要がないようにします。
• 技術的な詳細：計画時の会話に含まれる、実装に関する詳細をすべて記載します。CLI コマンド、コードスニペット、スキーマ、ファイルパス、環境変数、API エンドポイントなどが該当します。
• 作成／変更するファイル：用途を添えて、対象ファイルを明示的に列挙します。
• 受け入れ条件：具体的で、検証可能な条件を記載します。

新たな視点で各タスクファイルを見直してください。計画時の会話を一度も見たことのないエージェントが、このファイルだけを使って正しく実装できるでしょうか？できない場合は、不足している情報を追加してください。

ステップ 7：手作業が必要な対応を抽出する

人間による対応が必要な手順（アカウント作成、API キーの設定、DNS 設定、環境変数、サードパーティサービスへの登録など）を特定します。これらを、実施するタイミング（実装前／実装中／実装後）ごとに分類して action-required.md に記載します。該当するものがない場合は、「手作業で必要な対応はありません」と記載します。

ステップ 8：ユーザーに報告する

仕様を作成した後、次を表示します。

Feature specification created at specs/{feature-name}/

Files created:
- README.md (dependency graph, {N} waves, {T} tasks)
- requirements.md
- action-required.md
- tasks/ ({T} task files)

Wave breakdown:
- Wave 1: {count} tasks (parallel) — {brief description}
- Wave 2: {count} tasks (parallel) — {brief description}
- ...

Next steps:
1. Review action-required.md for tasks you need to complete manually
2. Review the requirements and task files
3. Use /implement-feature to start parallel implementation

重要なルール

• 各タスクファイルは完全に自己完結している必要があります。これが仕様の構成の要点です。そのファイルだけを読むコーディングエージェントが、何をすべきかを正確に把握できなければなりません。
• 計画時の会話に含まれる技術的な詳細をすべて記録します。仕様は唯一の信頼できる情報源です。CLI コマンド、スキーマ、コードスニペット、ファイルパス、環境変数、API エンドポイントを含めてください。ここに記録されていない情報は失われます。
• 同じウェーブ内のタスクで、変更対象のファイルが重複しないようにします。同じブランチで作業する並列エージェントが、同じファイルを安全に編集することはできません。
• タスクはアトミックに保ち、1 つのタスクにつき 1 つの関心事を扱います。変更対象のファイルが 5～7 個を超える場合は、タスクの分割を検討してください。
• ユーザーが明示的に依頼しない限り、テスト用のタスクは作成しないでください。
• タスクファイルには、スキャンしやすいようにトポロジカル順（ウェーブ 1 を先にし、その後ウェーブ 2 など）で番号を付けます。