simple-spec-builder

使用するタイミング

次の場合にこのスキルを使用します。

• ユーザーが一般的な機能について説明し、正式なユーザーストーリーへの変換を求めている場合。
• アイデアを構造化され、視覚的に整理されたアジャイル要件に変換する必要がある場合。
• ユーザー体験全体を視覚的にマッピングする必要がある場合（ユーザーストーリーマッピング）。
• ユーザーストーリーが大きすぎる場合（エピック）、高度な分割手法を使って分割する必要がある場合。
• 既存のユーザーストーリーに測定可能な受け入れ基準がない場合、または Gherkin 形式で構造化する必要がある場合。
• スパイク、独立した技術ストーリー、または機能的なウォーキングスケルトンが必要となる技術的または機能的な不確実性がある場合。
• 機能がビジネスや顧客にもたらす実際の価値が明確でない場合。

---

チケットごとの拡張仕様

このリポジトリで、ディスク上に垂直スライスが文書化されている作業の場合：

成果物	場所
インデックスと実行順序	.tasks/<PBI-or-other-id>/index-spec.md
ファイルごとに1つのストーリー／スライス	.tasks/<id>/spec-<NN>-<kebab-name>.md
意思決定	.tasks/<id>/open-questions.md
ソリューション図	.tasks/<id>/solution-diagrams.md

仕様形式の公式チームテンプレートは templates/enriched-template.md にあります。 ソリューション図の公式テンプレートは templates/solution-diagrams.md にあります。

open-questions.md ドキュメント — 必須の生成

生成するタイミング： 仕様（spec-*.md）の分解と生成時に、ブロッカー、曖昧さ、または機能面／技術面の不整合が見つかった場合は、open-questions.md ファイルを必ず生成してください。これは任意の成果物ではありません。未解決または議論中の項目が1つでもある場合は、ドキュメントを作成し、直ちに内容を完成させる必要があります。

更新ルール： ユーザーは選択肢に [x] を付けるか、Other: に記入するだけで選択を示します。ユーザーが選択肢を示したら、エージェントは選択内容を自動的に解析し、対応する仕様に変更を反映したうえで、## Summary (Only for Agent, do not edit this table manually) 見出しの下にある最終サマリーテーブルに決定事項を記入する必要があります。ユーザーはこのテーブルを手動で編集してはいけません。

ドキュメントの完全な構成、書式ルール、実例は templates/open-questions.md にあります。

solution-diagrams.md ドキュメント — 必須の生成

生成するタイミング： 指定されたソリューションの技術設計と視覚的な図を記録するため、solution-diagrams.md ファイルを必ず生成してください。

このファイルは直ちに作成し、次の内容を含める必要があります。

1. コンポーネント、アクター、システム間のやり取りと呼び出しのフローを詳しく示すシーケンス図。
2. ソリューションの静的構造、関係、属性、メソッドを概説するクラス図。
3. ソリューションのその他の側面（例：状態図、データフロー、コンポーネントアーキテクチャ）の理解に役立つ追加図のプレースホルダー。

このドキュメントのテンプレートと完全な構成は templates/solution-diagrams.md にあります。

---

プロジェクトの背景

項目	詳細
ストーリーの形式	As a [user role], I want [goal], so that [benefit]
受け入れ基準	BDD 形式／Gherkin 言語（Given／When／Then）
品質フレームワーク	INVEST Model、SMART 基準、Jobs-to-be-Done（JTBD）
計画手法	ユーザーストーリーマッピング（Jeff Patton）、アウトカム ＞ アウトプット

このスキルに関連するアーキテクチャ： ストーリーは、機能する垂直スライスを表す必要があります。大規模なプロジェクトやエピックでは、最初のスライスを機能するウォーキングスケルトンとし、システムをエンドツーエンドで実行して、技術的リスクを早期に検証する必要があります。

---

重要なパターン

A. 継続的な分析と共感

• パターン 1：3Cs から 5Cs へ。 Card、Conversation、Confirmation で止まらないようにします。ストーリーでは、Construction と Consequences まで広げて成功に向けて計画します。実装した機能が望ましい利益を実際にもたらしたかを把握するため、メトリクスを追加します。
• パターン 2：「Over-the-Wall」アンチパターンの防止。 いかなる状況でも、プロダクトオーナーが単独で作業することを想定したストーリーを書いてはいけません。ユーザーに質問を繰り返すサイクルへ参加してもらいます。ストーリーは、継続的な会話への招待です。
• パターン 3：ユーザーペルソナとJobs-to-be-Done（JTBD）に注力する。 役割フィールドに汎用的な「ユーザー」を使うのはやめます。人口統計や動機に共感できる、詳細な架空の人物像を作成して使用します。顧客が解決する必要のある根本的な仕事や問題（JTBD）に注力します。
• パターン 4：ドキュメントよりも共通理解を重視する（「対話と記録」）。 ストーリーの本当の目的は、完璧なドキュメントを書くことではなく、継続的な会話を通じて共通理解を築くことです。会話に取って代わるのではなく、会話を思い出すために書きます。

B. 要件の整理と品質

• パターン 5：ユースケースを厳密に分離する。 ストーリーがユースケースにならないようにします。ユーザーが必要としている「何か」に注力し、「どのように」やシステムとのやり取りは、図などの別のドキュメントに委ねます。
• パターン 6：技術ストーリーとスパイク。 インフラストラクチャやリファクタリングなどの純粋な技術ストーリーでは、「As a [role]」形式を無理に使いません。不確実性が高い場合は、まず技術的な Spike を作成し、期間を限定した調査で実現可能性を評価します。
• パターン 7：NFR を分離する。 パフォーマンス、スケーラビリティ、アクセシビリティ、セキュリティを単純な受け入れ基準として扱ってはいけません。システム全体の品質制約となる非機能要件（NFR）として分離します。
• パターン 8：「完了の定義」（DoD）を尊重する。 受け入れ基準では、特定の機能要件を検証します。ユニットテストやコードレビューなどの一般的な品質タスクは、プロジェクトで必須の DoD に含まれるため、受け入れ基準に含めてはいけません。
• パターン 9：IA の計画・検証・実行。 複雑な要件では、まず検証ファイルに構造化された計画や概要を作成し、ユーザーに承認してもらってから、Gherkin で最終稿を作成します。

C. 受け入れ基準の作成

• パターン 10：SMART 品質。 各基準は、具体的（Specific）、測定可能（Measurable）、達成可能（Achievable）、関連性があり（Relevant）、期限が明確（Time-bound）になるように設計します。優れた基準は、常に二者択一の方法で検証できます。
• パターン 11：汎用的な BDD/Gherkin 言語。 基本要素である Given（コンテキスト）、When（トリガーとなるイベント）、Then（期待される結果）を厳密に適用します。
• パターン 12：ハッピーフローを先に、アンハッピーフローを後に。 理想的な環境を前提として、メインシナリオを作成します。その後、エラーや代替経路を意図的に発生させてシナリオを崩します。
• パターン 13：複雑な基準の分割。 1 つの基準に条件が多く連なっている場合（「GIVEN a AND b WHEN c THEN d AND e」など）、複数の個別基準に分割する必要があります。
• パターン 14：スリーアミーゴのルール。 基準が 3 つの柱、すなわちビジネス（PO）、開発（IT）、デザイン／QA のエッジケースを網羅していることを、頭の中でシミュレーションして確認します。

D. 高度なストーリー分割（エピックの垂直スライス戦略）

• パターン 15：ワークフローのステップで分割（戦略 1）。 フローの開始部分と終了部分を切り分けて MVP を作成し、中間のステップは後回しにします。
• パターン 16：ビジネスルールで分割（戦略 2）。 運用上の制約を緩和した状態から始め、後続のストーリーで法的ルールや却下などの強化要件を取り入れます。
• パターン 17：入力オプション／プラットフォームで分割（戦略 4）。 インターフェース（アプリと Web）やデータの入力方法に応じて、別々のストーリーを作成します。
• パターン 18：データ型で分割（戦略 5）。 パラメーターの複雑さを切り分けて（例：単純な検索と高度なフィルター）、要件を分離します。
• パターン 19：CRUD 操作で分割（戦略 6）。 「管理する」という動詞の使用を避け、作成、読み取り、更新、削除に分解します。
• パターン 20：テストシナリオで分割（戦略 7）。 アンハッピーフローや複雑なエッジケースを親要件から切り離し、独立したストーリーにします。
• パターン 21：役割で分割（戦略 8）。 一般の顧客、VIP、管理者で結果が異なる場合は、目標を複数のストーリーに分けます。
• パターン 22：最適化は後回し（戦略 9）。 「まず動くものを作る」という考え方を適用し、基本機能を実装してから、深刻なパフォーマンス改善を将来のストーリーに先送りにします。
• パターン 23：技術的な互換性（戦略 10）。 初期開発は主要なブラウザーや技術に集中し、価値の提供を確実にします。
• パターン 24：「Good-Better-Best」による分割。 停滞を避けるため、まず「現時点で十分な」ストーリー（Good）を定義し、次に体験を「より良く」するストーリー（Better）を切り分け、最後に「最適な」ストーリー（Best）に取り組みます。

E. ユーザーストーリーマッピング（視覚的なプロダクト計画）

• パターン 25：アウトプットよりアウトカムを重視。 仕事はソフトウェアをさらに多く作ることではなく、ソリューションのインパクトを最大化することです。機能よりもビジネス上の成果を優先します。
• パターン 26：深さより幅を先に（広く浅く）。 マッピングでは、詳細にとらわれないようにします。上から下へ掘り下げる前に、左から右へ物語が流れるように高レベルのアクティビティをまとめて「バックボーン」を構築します。
• パターン 27：戦略的なスライス（MVP）。 ストーリーマップに水平線を引いて不要な要素をすべて切り落とし、最初のスライスに含まれるストーリーをまとめて、機能する MVP を作成します。
• パターン 28：機能的なウォーキングスケルトン。 スライスでは、技術レイヤーごとに分割しないでください。技術的リスクをすぐに発見できるよう、エンドツーエンドで機能する最初のウォーキングスケルトンを作成します。

F. 見積もりと経済価値評価のツール

• パターン 29：MoSCoW マトリクス。 要件を Must have、Should have、Could have、Won't have に分類できるよう支援し、背景情報を提示します。
• パターン 30：実質価値の算出（ROI／WSJF）。 WSJF（遅延コスト／規模）による優先順位付けを適用し、実証的な経済的メリットに基づいた測定を促します。

---

高度な意思決定ツリー

エージェントは、リクエストが特定の文章作成・改善に関するものか、製品全体のマッピングに関するものかを判断する必要があります。

フロー 1：分析、文章作成、分割（ストーリー／エピック）

1. ユーザーが、明確な役割、実証的な価値、または「Why」の背景を欠いた要件を提示していますか？
   • はい：中止します。「ユーザーペルソナ」を作成するために質問し、ニーズを理解するためにJobs-to-be-Doneを活用します。パターン 9を適用します。
   • いいえ：ステップ 2 に進みます。
2. 顧客向けの要件（機能要件）ですか、それともシステムの技術要件ですか？
   • 技術要件：パターン 6（「As a user」形式を使わない技術ストーリー／スパイク）を適用します。
   • 機能要件：ステップ 3 に進みます。
3. リクエストに曖昧な用語「manage」が含まれる、または巨大なフロー（エピック）を対象としていますか？
   • はい：CRUD（パターン 19）、入力オプション（パターン 17）、または**Good-Better-Best（パターン 24）**による分割の適用を検討します。2 つまたは 3 つの分割戦略を提案します。
   • いいえ：ステップ 4 に進みます。
4. 受け入れ基準（AC）は、正常系のシナリオのみを対象としていますか？
   • はい：対応を中断します。異常系フローの定義を求めるパターン 12を適用します。リスクが非常に高い場合は、パターン 20を使って分割します。
   • いいえ：ステップ 5 に進みます。
5. 受け入れ基準に過剰な検証項目が含まれている、または「すばやく読み込む」などの要件が含まれていますか？
   • はい：長い基準を分割して改善し、パターン 13を適用します。パターン 7 および 8を適用して、全体制約（NFR）と完了の定義（DoD）を分離します。
   • いいえ：BDD／Gherkin 構文で構成します。
6. 仕様の作成または改善中に、ブロッカー、曖昧さ、矛盾が検出されましたか？
   • はい：実装前に解決すべきすべての項目を詳述したopen-questions.mdを必ず作成します。
   • いいえ：ステップ 7 に進みます。
7. ソリューション図を必ず作成します：
   • ソリューションのフローを示すシーケンス図、技術設計のクラス図、および開発を説明するための追加図を記載できるスペースを含むsolution-diagrams.mdを必ず作成します。
8. ユーザーはデプロイ後の影響を測定する方法を知っていますか？
   • いいえ：指標の追跡を議論に取り入れます（Consequences／パターン 1）。
   • はい：最終的なアジャイルユーザーストーリーを作成します。

フロー 2：ユーザーストーリーマッピング（製品マッピング／ビジュアルレイアウト） ユーザーが「マッピングする」「フローを作成する」、または「MVP を定義する」よう求めた場合：

1. **問題の枠組みを定める：**ユーザーペルソナと期待される成果が定義されていますか（成果／パターン 25）？
2. **全体像をマッピングする（バックボーン）：**主なアクティビティを時系列順（左から右）に並べて、バックボーンを定義します（パターン 26）。
3. **詳細を掘り下げる：**上から下へ詳しく検討します。代替案、ビジネスルール、またはデータのバリエーションを尋ねます。
4. **リリース戦略を切り出す（MVP）：**主な成果を達成するために必要な最小限の範囲に絞り、水平の分割線を引きます（パターン 27）。
5. **学習戦略を切り出す（Walking Skeleton）：**技術的リスクが高い場合は、最初のスライス（スライス 1）として「機能的な Walking Skeleton」（パターン 28）を提案します。

---

例

例 1：標準的な Gherkin ストーリー（正常系／異常系フロー）

**ストーリー：**顧客として、銀行での行列を避けるため、ATM から現金を引き出したいです。 受け入れ基準（シナリオ 1：正常系フロー）：

• Given 口座に残高があり、カードが有効である
• When 顧客が現金を引き出そうとする
• Then 口座から引き落とされ、現金が払い出される。

受け入れ基準（シナリオ 2：異常系フロー）：

• Given 口座残高が合意された当座貸越限度額を超えている
• When 顧客が現金を引き出そうとする
• Then ATM に要求を拒否するメッセージが表示される。

例 2：CRUD 操作によるストーリーの分割

リクエスト：「ユーザーとして、カートを管理したい」

• 作成： 買い物客として、注文するために新しい本をカートに追加したい。
• 読み取り： 買い物客として、合計金額を確認するためにカート内の商品を確認したい。
• 更新： 買い物客として、カート内の本の数量を更新したい。

例 3：ユーザーストーリーマッピング — 幅（バックボーン）と深さ（詳細）

バックボーン（左から右）： 商品を検索 -> カートに追加 -> 支払い -> 配送を確認。 「支払い」の詳細（上から下）：

• 必要十分： クレジットカードで支払う（MVP）。
• より良い方法： PayPal で支払う。
• エラーフロー： カードが拒否された場合にエラーを表示する。

例 4：スライス化と機能的なウォーキングスケルトン

エピック： 主催者として、イベント参加者を管理したい。

• スライス 1（ウォーキングスケルトン）： データベースのフローがエンドツーエンドで機能することを確認するため、名前とメールアドレスを使って参加者を手動で登録する。
• スライス 2（改善）： CSV で参加者リストをインポートする。
• スライス 3（リリース可能にする）： ウェルカムメールを自動送信する。

---

リソース

• 品質ガイド：INVEST ガイドラインとユーザーストーリーの品質
• HTML テンプレートの参考資料：templates/user_story_template.md
• ソリューション図のテンプレート：templates/solution-diagrams.md
• マッピング手法：ユーザーストーリーマッピング（Jeff Patton 著）（概念：バックボーン、ナラティブフロー、成果 > アウトプット、スライス化）