problem-based-srs

Problem-Based SRS

この文書における「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」、「OPTIONAL」というキーワードは、ここに示すようにすべて大文字で記載されている場合に限り、BCP 14 RFC 2119 RFC 8174 の説明に従って解釈してください。

Problem-Based SRS の方法論（Gorski & Stadzisz）を使用して、要件エンジニアリングを統括します。このスキルは、すべての要件が実際のビジネス上の問題にさかのぼれるようにする、構造化されたプロセス（ステップ 0 からステップ 5）を調整します。

方法論の概要

図の標準： すべての視覚的成果物には、Mermaid UML 図を優先形式として使用してください。Mermaid は Software Glance（ステップ 2）と Software Vision（ステップ 4）では必須であり、図が有用なその他のステップでは推奨されます。

Stakeholder Input
       ↓
┌──────────────────┐
│ Step 0: BC       │ → /problem-based-srs business-context
│ Business Context │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 1: CP       │ → /problem-based-srs problems
│ Customer Problems│
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 2: SG       │ → /problem-based-srs software-glance
│ Software Glance  │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 3: CN       │ → /problem-based-srs needs
│ Customer Needs   │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 4: SV       │ → /problem-based-srs software-vision
│ Software Vision  │
└────────┬─────────┘
         ↓
┌──────────────────┐
│ Step 5: FR/NFR   │ → /problem-based-srs functional-requirements
│ Requirements     │
└──────────────────┘

トレーサビリティチェーン： FR → CN → CP（すべての要件は問題にさかのぼります）

ドメインマッピング（WHY → WHAT → HOW）：

ドメイン	成果物	答える問い
WHY	Customer Problems（CP）	なぜ解決策が必要なのか？（ビジネス上の根拠）
WHAT	Customer Needs（CN）	ソフトウェアはどのような成果を提供する必要があるのか？
HOW	Functional Requirements（FR）	システムはどのように動作するのか？

利用可能なアクション

Problem-Based SRS の方法論は、アクション引数を使って各ステップを呼び出す単一のコマンドである /problem-based-srs によって実行されます。アクションを指定せずに（または full を指定して）/problem-based-srs を実行すると、方法論全体を最初から最後まで統括して実行します。

アクション	コマンド	目的
business-context	/problem-based-srs business-context	ステップ 0：構造化されたビジネスコンテキストと原則を確立する
problems	/problem-based-srs problems	ステップ 1：顧客の問題を特定し、分類する
software-glance	/problem-based-srs software-glance	ステップ 2：ソリューションの概要を作成する
needs	/problem-based-srs needs	ステップ 3：顧客ニーズ（成果）を定義する
software-vision	/problem-based-srs software-vision	ステップ 4：ソフトウェアのビジョンとアーキテクチャを定義する
functional-requirements	/problem-based-srs functional-requirements	ステップ 5：機能要件を生成する
validate	/problem-based-srs validate	ドメイン間のトレーサビリティを検証する（ZigZag）
complexity	/problem-based-srs complexity	オプション：公理的設計による品質分析
full	/problem-based-srs	方法論全体を実行する（ステップ 0 → ステップ 5）

アクションの呼び出し方法

各アクションの詳細なステップ固有の指示は、このスキルと同じ場所にある参照ファイル reference/<action>.md（ファイル名がアクション名です）に記載されています。ユーザーがアクションを呼び出したら、成果物を作成する前に該当する参照ファイルを読み、記載内容に正確に従ってください。

アクション	参照ファイル
business-context	reference/business-context.md
problems	reference/problems.md
software-glance	reference/software-glance.md
needs	reference/needs.md
software-vision	reference/software-vision.md
functional-requirements	reference/functional-requirements.md
validate	reference/validate.md
complexity	reference/complexity.md
live	reference/live.md — SRS Navigator キャンバス（/live）を開く

full 実行（単独の /problem-based-srs）では、各ステップに進む際に reference/<action>.md を読みながら、ステップを順番に進めてください。

🔖 識別子の表記（正規）

すべての成果物 ID にはドット表記を使用します。ID 自体にトレーサビリティチェーンが表現されており、ID を読むだけで、どの成果物から派生したものかがわかります。

成果物	形式	例	意味
顧客の問題	CP.{n}	CP.01	1 番目の顧客の問題
サブ問題	CP.{n}.{m}	CP.01.1	CP.01 の 1 番目の側面
サブサブ問題（まれ）	CP.{n}.{m}.{k}	CP.01.2.1	CP.01.2 の 1 番目の側面
顧客ニーズ	CN.{cp}.{n}	CN.01.1	CP.01 に対応する 1 番目のニーズ
機能要件	FR.{cp}.{cn}.{n}	FR.01.1.1	CN.01.1 を実現する 1 番目の FR
非機能要件	NFR.{n}	NFR.01	1 番目の品質要件

ルール：

1. 必ずドット形式の ID を使用してください。 CP.01、CN.01.1、FR.01.1.1 のようにします。ニーズに CP.1.1 を使用したり、独自の形式を使ったりしてはいけません。
2. ID には親を明示する必要があります。 FR.01.1.1 は CN.01.1 を実現し、CN.01.1 は CP.01 に対応します。親を特定できない場合、その成果物はまだ作成できる状態ではありません。
3. ハイフン形式の ID（CP-001、FR-002）はレガシー形式です。 これらを使用している既存の仕様書は引き続き有効で、ツールも読み取れますが、新たに作成してはいけません。
4. 本文では ID をそのまま記載してください（例：「CP.01 に対応」）。トレーサビリティを自動的に抽出できるようにするためです。

📁 進捗の保存（重要）

重要： 各ステップで、作成した成果物を必ずファイルに保存してください。セッション間で進捗は自動的に保存されません。

⚠ ファイル作成ルール：一度に 1 ファイル

複数の成果物ファイルを並行して作成してはいけません。 ファイルは必ず1 つずつ順番に作成し、次のファイルを作成する前に、各ファイルの保存が完了するまで待ってください。複数ファイルをまとめて並行作成すると、ツール呼び出し時に結合した内容が大きすぎて JSON シリアライズエラーが発生します。

初回セットアップ

新しいプロジェクトを開始するときは、デフォルトで .spec/（プロジェクトルートにある隠しフォルダー）に成果物を保存します。ユーザーが別のフォルダーを指定した場合、または既存の成果物フォルダー（例：docs/srs/、requirements/）が見つかった場合は、その場所を使用してください。

成果物ファイルの構成

各ステップを進めながら、次のフォルダー構成を作成してください。

.spec/
├── 00-business-context.md            # Step 0: Business context, principles, and constraints
├── 01-customer-problems.md           # Step 1: CPs (WHY)
├── 02-software-glance.md             # Step 2: High-level solution view
├── 03-customer-needs.md              # Step 3: CNs (WHAT)
├── 04-software-vision.md             # Step 4: Architecture and scope
├── functional-requirements/          # Step 5: Individual FR files
│   ├── _index.md                     # FR summary and traceability matrix
│   ├── FR.01.1.1-[short-name].md     # Individual FR file
│   ├── FR.01.1.2-[short-name].md     # Individual FR file
│   └── ...                           # One file per FR
├── non-functional-requirements/      # NFR files (quality attributes)
│   ├── _index.md                     # NFR summary
│   ├── NFR.01-[short-name].md        # Individual NFR file
│   └── ...                           # One file per NFR
└── traceability-matrix.md            # CP → CN → FR complete mapping

FR/NFR を個別のファイルにする理由

各機能要件と非機能要件は、次の理由から個別のファイルとして保存します。

1. エンジニアがそれぞれ異なる要件を独立して担当できます
2. バージョン管理で個々の要件の変更を追跡できます
3. コードレビューで特定の要件に焦点を当てられます
4. トレーサビリティをファイル単位で維持できます
5. ステータスの追跡（ドラフト、承認済み、実装済み、テスト済み）が容易になります

FR および NFR のファイルテンプレート

どちらのテンプレートも Step 5 のアクションファイルにあります。reference/functional-requirements.md の個別 FR ファイルテンプレートと個別 NFR ファイルテンプレートを参照してください。要件ファイルを作成する前にこのファイルを読み込み、すべての FR/NFR で構成、トレーサビリティテーブル、受け入れ基準の形式を統一してください。

各ステップの完了後に保存

各ステップの完了後は、必ず次の作業を行ってください。

1. 対応するファイルを作成または更新する
2. ファイルが保存されたことをユーザーに確認する
3. 参照用にファイルパスを表示する

Step 5 の引き継ぎ例：

✅ Step 5 Complete: Functional Requirements Specified

📁 Saved to: .spec/functional-requirements/
   ├── _index.md (summary with 8 FRs)
   ├── FR.01.1.1-user-registration.md   → CN.01.1 (User Registration)
   ├── FR.01.1.2-user-authentication.md → CN.01.1 (User Authentication)
   ├── FR.01.2.1-data-validation.md     → CN.01.2 (Data Validation)
   ├── FR.01.2.2-error-handling.md      → CN.01.2 (Error Handling)
   ├── FR.02.1.1-report-generation.md   → CN.02.1 (Report Generation)
   ├── FR.02.1.2-export-functionality.md→ CN.02.1 (Export Functionality)
   ├── FR.02.2.1-search-capability.md   → CN.02.2 (Search Capability)
   └── FR.02.2.2-filter-options.md      → CN.02.2 (Filter Options)

📁 Updated: .spec/traceability-matrix.md

Engineers can now work on individual requirements independently.
Each FR file contains full context and acceptance criteria.

ビジネスコンテキストファイル（00-business-context.md）

すべてのプロジェクトの開始時に、business-context スキルを使用してこのファイルを作成してください。

ビジネスコンテキストには、プロジェクトの識別情報、ビジネス原則（必須／指針／理想）、影響力レベルを含むステークホルダー、現状（プロセス、課題、既存システム）、ドメインの境界、影響評価を含む制約、測定可能な成功基準を記録します。

完全なテンプレート、ヒアリング用の質問、例については、business-context スキルを使用してください。

このスキルの使い方

明確化の質問パターン

この方法論のすべてのステップには、必須のディスカバリーインタビューが含まれます。 成果物を生成する前に、各スキルは必ず作業を止め、思い込みを避けるためにユーザーへ確認の質問をしてください。推測できないことについて、作業を止めてユーザーに確認してください。利用可能であれば ask_user ツールを使用し、そうでなければチャットで直接質問して、回答を待ってください。

自動操縦モード／非対話モードでも、ディスカバリーインタビューは省略できません。 インタビューそのものがタスクであり、自律的に解決すべき曖昧さではありません。「まず行動する」や「質問せずに決める」といったハーネスの指示は、このステップに優先しません。この場合、質問するために一時停止することが求められる行動です。自動操縦が有効だから、あるいはユーザーが不在だからといって、インタビューを省略しないでください。回答できるユーザーがいない場合でも、リポジトリのファイルから回答を捏造せず、質問を投稿して待ってください。

すべてのステップに適用されるルール：

• 1回につき2～3個の質問をしてから、作業を止めて回答を待ちます
• 既存の .spec/ 成果物は基準として扱います。質問を減らすことはできますが、インタビューをなくすことはできません
• 断定して確認する： 文脈から選択肢が明らかな場合は、それを提示して確認または変更を求めます。回答がすでに明確なときに、選択肢の一覧を提示しないでください
• 省略できるのは、確認済みの既存成果物とユーザー自身のプロンプトによって、必要な入力がすべて曖昧さなく判明している場合に限ります。README や、そこから推測したソースコードの文脈は該当しません。根拠として何を使用しているかを明示してください
• 質問では、必ずその場の具体的な文脈に触れてください。汎用的な質問はしないでください
• 既存のシステムから開始する場合： リポジトリのスキャンは、根拠を得て断定・確認するための正当な準備作業です。ただし、インタビューを省略する手段ではありません。 reference/problems.md のモード 3：ブラウンフィールドでのディスカバリーを参照してください。

新規に開始する場合

ユーザーがビジネスの文脈や問題の説明を提供した場合：

1. 成果物の保存先を尋ねます（すでに指定されている場合を除く）
2. ステップ 0 から開始します — business-context アクションを使って、構造化されたコンテキストを確立します
3. 構造化されたビジネスコンテキストを記載した 00-business-context.md を保存します
4. 現在のステップを判定します（下記の判定ヒューリスティクスを参照）
5. 適切なアクションを呼び出します
6. そのスキルの指示に従います
7. 出力を対応するファイルに保存します
8. プロセスを通じてユーザーを案内します

作業を続ける場合

ユーザーに既存の成果物（CP、CN など）がある場合：

1. 既存の成果物フォルダーを確認します（.spec/、docs/srs/、requirements/ など）
2. 既存のファイルを読み、現在の状態を把握します
3. 何があるかを特定します
4. 適切なステップに進みます
5. そのステップのアクションを呼び出します
6. 必要に応じてファイルを更新しながら、そこから続行します

検証

いつでも /problem-based-srs validate を使用して整合性を確認できます。

判定ヒューリスティクス

存在する成果物を確認して、現在のステップを判定します：

ユーザーが持っているもの	現在のステップ	アクション	保存先
何もない／ビジネスアイデアのみ	0	business-context	00-business-context.md
ビジネスコンテキスト（BC）	1	problems	01-customer-problems.md
顧客の問題（CP）	2	software-glance	02-software-glance.md
CP + ソフトウェアの概要	3	needs	03-customer-needs.md
CP + CN + ソフトウェアの概要	4	software-vision	04-software-vision.md
CP + CN + ソフトウェアビジョン	5	functional-requirements	functional-requirements/*.md

各ステップ（クイックリファレンス）

ステップ 0：ビジネスコンテキスト（BC）

目的： 構造化されたビジネスコンテキストとプロジェクト原則を確立します 入力： ステークホルダーとの会話、プロジェクト概要、既存のドキュメント 出力： アイデンティティ、原則、ステークホルダー、境界、制約、成功基準を記載したビジネスコンテキスト文書 保存先： 00-business-context.md アクション： /problem-based-srs business-context

ステップ 1：顧客の問題（CP）

目的： ビジネス上の問題を特定し、文書化します
入力： ビジネスコンテキスト（ステップ 0）
出力： 義務／期待／希望に分類した CP のリスト
構文： [Subject] [must/expects/hopes] [Object] [Penalty]
保存先： 01-customer-problems.md
アクション： /problem-based-srs problems

ステップ 2：ソフトウェア概要（SG）

目的： 初期段階の抽象的なソリューションの概要を作成します
入力： 顧客の問題
出力： 境界とコンポーネントを含むシステムの概要
保存先： 02-software-glance.md
アクション： /problem-based-srs software-glance

ステップ 3：顧客ニーズ（CN）

目的： ソフトウェアが提供すべき成果を明確にします
入力： CP + ソフトウェア概要
出力： 成果クラス（情報／制御／構築／エンターテインメント）を付与した CN
構文： [Subject] needs [system] to [Verb] [Object] [Condition]
保存先： 03-customer-needs.md
アクション： /problem-based-srs needs

ステップ 4：ソフトウェアビジョン（SV）

目的： スコープと位置付けの概要を定義します
入力： CN + ソフトウェア概要
出力： ステークホルダー、機能、アーキテクチャを含むビジョン文書
保存先： 04-software-vision.md
アクション： /problem-based-srs software-vision

ステップ 5：機能要件（FR）と非機能要件（NFR）

目的： 詳細な要件を生成します
入力： CN + ソフトウェアビジョン
出力： トレーサビリティを備えた個別の FR ファイルと NFR ファイル
構文 FR： The [System] shall [Verb] [Object] [Constraint] [Condition]
保存先： functional-requirements/FR.[CP].[CN].[N]-[short-name].md および non-functional-requirements/NFR.[N]-[short-name].md
アクション： /problem-based-srs functional-requirements

品質ゲート

重要： トレーサビリティを検証してギャップを特定するため、ステップ 3 と 5 の後に /problem-based-srs validate アクションを使用したジグザグ検証を必ず実施してください。

ステップ 0（BC）の後

• プロジェクトの識別情報が揃っている（名称、ドメイン、目的）
• ビジネス原則が定義され、分類されている（必須／指針／理想）
• ステークホルダーが役割と影響力とともに特定されている
• 現状が文書化されている
• ドメインの境界が定義されている
• 制約が文書化されている
• 成功基準が測定可能である
• ファイルを保存： 00-business-context.md

ステップ 1（CP）の後

• すべての CP が構造化表記を使用している
• 分類が割り当てられている（義務／期待／希望）
• 問題の記述にソリューションが含まれていない
• ファイルを保存： 01-customer-problems.md

ステップ 2（SG）の後

• システム境界が定義されている
• 主なアクターとインターフェースが特定されている
• 概要レベルのコンポーネントが説明されている
• Mermaid UML 図が含まれている（必須）
• ファイルを保存： 02-software-glance.md

ステップ 3（CN）の後

• すべての CP に少なくとも 1 つの CN がある
• すべての CN が構造化表記を使用している
• 成果クラスが割り当てられている
• ファイルを保存： 03-customer-needs.md
• 必須：ジグザグ検証を実行する（CP → CN のマッピング）

ステップ 4（SV）の後

• 位置付けを示す文が明確である
• すべてのステークホルダーが特定されている
• 主な機能が列挙されている
• Mermaid UML アーキテクチャ図が含まれている（必須）
• ソフトウェア概要への相互参照がある
• ファイルを保存： 04-software-vision.md

ステップ 5（FR／NFR）の後

• すべての CN に少なくとも 1 つの FR がある
• すべての FR が「shall」または「should」を使用している
• 各 FR が functional-requirements/ 内の個別ファイルとして保存されている
• 各 NFR が non-functional-requirements/ 内の個別ファイルとして保存されている
• インデックスファイル（_index.md）が作成されている
• トレーサビリティマトリクスが完成している（FR → CN → CP）
• FR／NFR ファイルにコードスニペットやプログラミング例が含まれていない
• 構築の詳細が別の design/ フォルダーに記載されている（FR／NFR ファイルには記載しない）
• ファイルを保存： traceability-matrix.md
• 必須：ジグザグ検証を実行する（チェーン全体の検証）

問題優先の徹底

ユーザーが解決策に飛びつこうとした場合は、軌道を戻します。

検出： CP が存在する前に、ユーザーが特定のテクノロジー、機能、または実装に言及した場合

軌道修正：

I notice you're describing a solution. Let's first understand the problem.

Before we design [mentioned solution], help me understand:
1. What is the business context? (→ `business-context` action)
2. What business obligation, expectation, or hope drives this need?
3. What negative consequences occur without this?
4. Who is impacted?

→ Loading: `business-context` action (if no BC exists)
→ Loading: `problems` action (if BC exists)

構文クイックリファレンス

成果物	構文パターン
CP	[主体] [must/expects/hopes] [対象] [ペナルティ]
CN	[主体] needs [システム] to [動詞] [対象] [条件]
FR	The [システム] shall [動詞] [対象] [制約] [条件]
NFR	The [システム] shall [測定可能な基準を伴う品質特性]

引き継ぎプロトコル

各ステップの完了時に：

1. 保存：出力を適切なファイルに保存します
2. 概要：作成した出力の概要を示します
3. 検証：ゲート基準を満たしていることを確認します
4. 次のステップ：次のステップを提案します
5. 必要な入力：次のステップに必要な入力を示します

例：

✅ Step 3 Complete: Customer Needs Specified

📁 Saved to: .spec/03-customer-needs.md

Outputs:
- CN.01.1: [Information] User needs system to display...
- CN.01.2: [Control] Admin needs system to manage...
- CN.02.1: [Information] Manager needs system to report...

Gate Check:
- [x] All CNs use structured notation
- [x] Outcome classes assigned
- [x] Every CP has at least one CN
- [x] File saved

→ Next: Step 4 - Software Vision
→ Loading: reference/software-vision.md
→ Will save to: .spec/04-software-vision.md
→ Input: The CNs documented above

使用パターン

パターン 1：全プロセス（新規プロジェクト）

ステップ 0（ビジネスコンテキスト）から開始し、すべてのステップを順番に進めます。 注意： ファイルの保存先を尋ね、まずビジネスコンテキストを確立します。

パターン 2：途中から開始（既存の成果物）

存在する成果物を検出し、完了済みのステップを飛ばして、現在のステップから再開します。 注意： 既存の .spec/ フォルダーを確認し、現在のファイルを読み取ります。

パターン 3：反復的な改善

初回の作業を完了した後、理解が深まるにつれて特定のステップを反復します。 注意： 新しいファイルを作成するのではなく、既存のファイルを更新します。

パターン 4：検証のみ

/problem-based-srs validate アクションを使用して、新しい成果物を生成せずに既存の成果物を確認します。

パターン 5：独立した開発

ステップ 5 の後、エンジニアは個々の FR ファイルを引き継いで、独立して開発できます。 各 FR ファイルには必要なコンテキストがすべて含まれています（トレーサビリティ、受け入れ基準）。

パターン 6：アジャイル／スプリントとの統合

アジャイルワークフロー内で Problem-Based SRS を反復的に使用します：

• スプリント 0： 製品ビジョンのためにステップ 0～2（BC + CPs + Software Glance）
• スプリント 1 以降： 個別の機能セットのためにステップ 3～5
• 機能ごと： 一度に 1 つの機能について CP→CN→FR の流れを完了します
• 検証： 各スプリント後に /problem-based-srs validate を実行し、トレーサビリティを確保します

パターン 7：最小実用 SRS

迅速なプロトタイプや MVP の場合：

1. 中核となる CP を 2～3 個特定します（義務のみ）
2. 最小限の Software Glance を作成します
3. 必須の CN を導出します
4. 重要な FR のみを生成します
5. 拡張するまでは詳細な検証を省略します

各アクションを使用する場面

• business-context： ユーザーが新規プロジェクトを開始し、構造化されたコンテキストを確立する必要がある場合
• problems： ユーザーにビジネスコンテキストはあるものの、構造化された問題がない場合
• software-glance： ユーザーに CP があり、概要レベルのソリューションビューが必要な場合
• needs： ユーザーに CP + SG があり、成果を明確にする必要がある場合
• software-vision： ユーザーに CN があり、詳細なビジョンドキュメントが必要な場合
• functional-requirements： ユーザーに CN + SV があり、機能要件が必要な場合
• validate： ユーザーがトレーサビリティまたは一貫性を確認する必要がある場合
• complexity： ユーザーが公理設計分析を明示的に求めた場合

オプション：複雑性分析

より詳細な品質分析を行う場合、ユーザーは /problem-based-srs complexity アクションを明示的に呼び出し、公理設計に基づく仕様品質分析を実行できます。重要なシステム、大規模な仕様、または正式なレビューで使用します。これは標準的なフローには含まれません。

例

一連の手順をすべて確認するには、以下を参照してください：

• CRM の例 — ビジネス領域（顧客関係管理）
• MicroER の例 — 技術領域（再生可能エネルギーシステム）

コンテキストの使用量を最小限に抑えるため、現在のステップに応じてアクションを個別に実行してください。