spec-shaping

仕様の具体化

プロダクトのアイデアを、適切な範囲に絞った仕様と、実行可能なスプリント計画に変換します。このスキルでは、相互に補完する次の2つのモードをサポートしています。

1. インタビューモード：明確で範囲の絞られた仕様ができるまで、課題の領域を掘り下げます
2. スプリント分解モード：仕様を最小単位のタスクと、デモ可能なスプリントに分解します

使用するタイミング

• 範囲を絞る必要がある、粗いプロダクト計画やアイデアがある場合
• 実装の詳細、UI/UX、トレードオフについて考えるサポートが必要な場合
• スプリントとタスクに分解できる仕様がある場合
• 作り始める前に、課題の設定が適切か検証したい場合

ドキュメント管理

仕様とスプリント計画は更新され続けるドキュメントとして扱います。一貫性と「鮮度」を保つため、次の基準に従ってください。

1. ファイル操作（検索、保存場所、更新）

• 最初に検索する：新しいファイルを作成する前に、このプロジェクトの既存の仕様を検索します。
• 更新するか、新規作成するか：
  • 更新：プロジェクトの「アイデンティティ」が同じ場合（中核となる課題は同じで、実装を改善または方向転換するだけの場合）は、既存の仕様を更新します。
    • 対応：ファイル名を今日の日付に変更し、メタデータを更新します。
  • 新規作成：課題の定義が根本的に変わった場合や、解決の方向性を完全に「白紙に戻す」場合は、新しい仕様を作成します。
• 出力先（状況に応じて決定）：
  1. 次のディレクトリを検索します：specs/、planning/、docs/specs/、product/。
  2. 見つかった場合は、そのディレクトリを使用します。
  3. デフォルトでは、specs/を作成して使用します。
  4. Vault：外部にある場合は、agents.md／claude.mdを確認して、上書き設定がないか調べます。

2. ファイルの基準（命名、メタデータ、内容）

• 命名：[意味のある名前] - [YYYY-MM-DD].md
  • 仕様：Checkout flow spec - 2024-03-25.md
  • スプリント：Checkout flow sprints - 2024-03-25.md
• フロントマター：

  ---
  status: [Planned | In Progress | Completed]
  last: [YYYY-MM-DD]
  ---
  

• コンテキストヘッダー（必須）：

  > [!NOTE] > **Context**: [Why was this updated? e.g. "Pivot to V2"] > _This document reflects the product thinking at the time of the last update._
  

• 変更履歴：末尾に## Changelogを設けます。存在しない場合は追加します。重要な変更（例：範囲の方向転換）のみを記録します。軽微な編集は記録しません。

---

インタビューモード

計画ファイルを読み、技術的な実装、UIとUX、懸念事項、トレードオフなどについて、ユーザーに詳しく質問します。質問が自明なものにならないようにしてください。

インタビューの原則

1. 広げる前に絞る：一文で明確に説明できるまで、課題の範囲を絞り込みます。「カレンダーを作る」のような曖昧な範囲では、仕様の検討が延々と続きます。「既存の予定の間にある空き時間を表示する」のように範囲を明確にすれば、実際の解決策につながります。
2. 複雑さを早期に明らかにする：「思った以上に難しくする要因は何か」「隠れた依存関係はどこにあるか」と質問します。目的は、作業の途中ではなく、始める前に潜在的な問題を見つけることです。
3. 理解と正当化を区別する：作るものをすでに決めていて、それを正当化するデータを探しているというアンチパターンに注意します。解決策について話し合う前に、なぜこの課題が重要なのかを尋ねます。
4. 隣接するユーザーを探る：ユーザー向けの機能であれば、現在の対象ユーザーのすぐ外側にいる「次の」ユーザーは誰かを尋ねます。そのユーザーに対応するには、何を変える必要があるでしょうか？

インタビューの進め方

十分に掘り下げてください。課題の設定が適切で、主要なリスクが明らかになったと確信できるまで、インタビューを続けます。その後、仕様をファイルに書き込みます。

優れた仕様は具体化できるものです。読んだ人が、解決策を主要な構成要素9個以下で説明できる必要があります。それができない場合は、まだ課題の範囲が十分に絞られていません。

---

スプリント分解モード

仕様ファイルを読み、プロジェクトをスプリントとタスクに分解します。

中核となる原則

1. アトミックなタスク：すべてのタスクは、単独で完了、レビュー、マージできる、アトミックでコミット可能な作業単位にします。
2. 構成の明確さ：小さなアトミックなタスクを組み合わせ、スプリントの明確な目標を達成できるようにします。タスクとスプリント目標との関係が明らかでない場合は、「スプリント目標」を簡潔に記載します。
3. デモ可能なスプリント：すべてのスプリントで、実行、テストが可能で、前のスプリントの成果を基に構築できるソフトウェアを作り、デモできる状態にします。
4. 明確な検証：各タスクには、明示的な検証基準を含めます。該当する場合はテストを、そうでなければ具体的な検証方法を記載します（例：「検証：API が期待されるペイロードとともに 200 を返す」、「検証：コンポーネントが Storybook で正しくレンダリングされる」）。
5. 依存関係を優先：依存する作業より先に、その前提となるタスクが完了するよう順序を決めます。
6. 期間は固定、スコープは可変：スプリントは期間を区切った アペタイト であり、スコープの確約ではありません。収まらないものは、期間を延ばすのではなく、より小さく形作ります。
7. 理解のための予算を確保：次のスプリントを効率化するため、将来の作業のリスク低減にスプリントのキャパシティの約 10～20% を確保します。スパイク、調査、検証などに充ててください。

出力構成

プロジェクトの進展に合わせて柔軟に変更できるよう、出力を構成します。

• 安定した識別子：タスクに ID（T1、T2 など）を付け、コンテキストを失わずに参照したり、スプリント間で順序を入れ替えたりできるようにします。
• トレーサビリティ：タスクを仕様のセクションに関連付け、仕様の変更によって影響を受けるタスクを追跡できるようにします。
• 依存関係の可視化：どのタスクがほかのタスクに依存するかを明確にします。

このプロジェクトに適した形式を選んでください。小規模なプロジェクトならシンプルなリストで十分ですが、複雑なプロジェクトでは、スプリントごとに分類したタスク登録表が役立つ場合があります。適切な判断をしてください。

スプリント分解のプロセス

1. 仕様を十分に読み込みます。トレーサビリティのため、自然なセクションの区切りを特定します。

2. まずタスク登録表を作成し、アトミック性と依存関係に重点を置きます。

3. 各スプリントでデモができるように、タスクをスプリントにまとめます。

4. 次の観点からセルフレビューします。

   • 1 回の集中した作業で完了するには大きすぎるタスクはありませんか？
   • 抜けている依存関係や、循環している依存関係はありませんか？
   • それぞれの検証基準は具体的で、検証可能ですか？
   • 開発者がどのタスクに着手しても、何をもって「完了」とするか正確に把握できますか？
   • 各スプリントには明確なデモシナリオがありますか？
   • スコープ設計の匂いテスト：スプリント全体を、9 個以下の主要スコープで説明できますか？できない場合は、タスクに分解する前に仕様をさらに絞り込む必要があるかもしれません。

5. レビューに基づいて修正します。

6. 最終的なスプリント計画を、仕様と同じ場所にある Markdown ファイルに書き込みます（例：Checkout sprints - 2024-03-25.md）。

任意：サブエージェントによるレビュー

相互依存関係が多い大規模または複雑な仕様では、新鮮な視点でスプリント計画をレビューするサブエージェントの利用を検討してください。メインの会話に影響されない「別の視点」を得られます。サブエージェントには、次の作業を依頼してください。

• スプリント計画に抜けや循環する依存関係がないか、タスクが大きすぎないかをレビューする
• タスクのスコープやスプリントへのグループ化について改善案を提示する
• 曖昧、または検証不能な検証基準を指摘する

判断は適宜行ってください。こうしたレビューは、徹底的な監査にかける手間に見合う、複雑で重要度の高い仕様に最も有効です。

明示的に対象外とする項目

• 所要時間の見積もり：期間を見積もらないでください。タイムラインに関する情報は人間が後から加えます。
• リソースの割り当て：明示的に依頼され、割り当てに十分なコンテキストがある場合を除き、タスクを人や役割に割り当てないでください。