要件から始めるソフトウェア設計（小規模TS Webアプリの実践）

01. 要件定義を設計入力にする

目的

  • 要求を「合意された要件」に変換し、設計・テストに接続できる状態にする
  • To-Be と非機能の最小合意を作り、手戻りコストを抑える

得られる判断能力

  • 要求（Needs/Goals）を、要件（Shall）と仕様（Behavior）に落とし込める
  • To-Be を文章で表現し、設計の前提として共有できる
  • 非機能を「最小合意」として定義し、過剰な要求を抑制できる

前提/用語

  • To-Be: 目標とする業務・体験の状態（あるべき姿）
  • 要件（Requirements / Shall）: 実装方法に依存しない約束（何を満たすべきか）
  • 仕様（Specification / Behavior）: 外部から観測できる振る舞い（入力/出力、状態遷移、エラー）を曖昧さなく
  • 受け入れ条件: 仕様（Behavior）を検証可能にする形式（Given/When/Then など）
  • 非機能（NFR）: 性能、可用性、セキュリティ、運用性など

要点

  • 「要求→要件/仕様」は翻訳作業ではなく、合意形成と検証可能性の確保である
  • To-Be は「画面」ではなく「業務/体験の状態」を文章化する（5W2H が有効）
  • 非機能は全量を網羅しない。最小合意として、意思決定に必要な項目だけを先に固定する
  • 要件の粒度は、設計の粒度（境界）とテストの粒度（自動化範囲）に直結する
  • 主要要件は「どの仕様/設計/テストで担保するか」を残すと漏れが減る（任意: Appendix B（B-11） / 記入例: Appendix D（D-19））
  • 受け入れ条件（Given/When/Then）に ID を振ると、レビュー/テストの会話コストが下がる（任意: Appendix B（B-12） / 記入例: Appendix D（D-20））

例（ランニング例）

ランニング例（タスク管理）で、要求を要件に落とします。

変換の手順（実務の最小プロセス）

  1. 要求（Needs/Goals）を 1 文で書く（「誰が/何に困っているか/何が改善されるか」）
  2. To-Be を文章化する（5W2H。UI ではなく業務/体験の状態）
  3. 要件（Shall）に分解する（実装方法を含めず、検証可能な約束にする）
  4. 仕様（Behavior）に落とす（受け入れ条件と観測点を固定する）
  5. 非機能（NFR）は「運用と検証に必要な最小合意」だけを先に決める（後から増やせる形にする）

要求（例）

  • 「管理者がタスクを作り、担当者に割り当てたい」
  • 「担当者は期限までに完了できるようにしたい」
  • 「割り当てられたらメール通知してほしい」

To-Be（5W2H で文章化）

  • Who: 管理者、担当者
  • What: タスク（タイトル、期限、状態、担当者）
  • Why: 期限内の完了率を上げる、抜け漏れを減らす
  • When: 割り当て時、期限変更時、期限超過時
  • Where: 社内 Web アプリ（PC/モバイル）
  • How: 画面操作 + API、通知はメール（外部I/F）
  • How much: 初期は小規模（同一チーム・同一リポジトリ）

要件（Shall）の例

  • システムはタスクを作成できること
  • システムはタスクに担当者を割り当てできること
  • システムは担当者の割り当て時に通知できること
  • システムは管理者/一般ユーザーの権限に応じて操作を制御すること

仕様（Behavior/受け入れ条件）の例: 割り当て + 通知

  • Given: 管理者がタスクを作成している
  • When: 管理者が担当者を割り当てる
  • Then:
    • タスクの担当者が更新される
    • 担当者に通知（メール）が送信される
    • 通知が失敗した場合の扱い（リトライ/再送/ログ）が定義されている

例外系の観点カタログ（仕様で確定すること）

「例外系」は追加のテストケースではなく、設計と運用の前提になります。曖昧なまま実装に入ると、境界（API/DB/外部I/F）で判断が割れ、後から手戻りになります。

以下は小〜中規模でも頻出する観点です（少なくとも「どう振る舞うか」を 1 行で決める）。

  • 権限（Authorization）: 誰が実行できるか/できない場合の応答（例: 403、監査ログ）（任意: 認可ルール表 Appendix B（B-13））
  • 対象の存在（Not Found）: 存在しないID参照時の応答（例: 404、表示文言、ログ方針）
  • 入力検証（Validation）: 不正入力の扱い（例: 400、エラー形式、UI での表示）
  • 状態/業務ルール違反（Rule Violation）: 不正な状態遷移や制約違反の扱い（例: 409/422、理由コード）
  • 競合（Concurrency）: 同時更新の扱い（例: 後勝ち/排他/楽観ロック、衝突時は 409）
  • 外部I/F失敗（External Failure）: 通知等が失敗した場合に業務を止めるか（継続/再送/検知/復旧手順）
  • 冪等性（Idempotency）: 二重送信・二重クリック時に重複処理しない約束（例: 再実行は同一結果に収束）
  • 時間/期限（Time）: タイムゾーン、期限超過の定義、期限が過去の場合の扱い（許可/拒否/警告）
  • 監査/ログ（Audit/Logs）: 成功/失敗で何を残すか（個人情報の扱い、保存期間、検索性）

非機能の最小合意（決め方）

非機能は「将来の理想」を列挙する場ではなく、実装と運用で 迷いが出る論点 を先に固定するための合意です。

最小合意の作り方（例）:

  • 影響の大きいリスクから決める（障害時の業務影響、情報漏えい、監査）
  • 「測定できない条件」は避け、観測方法（ログ/メトリクス/アラート）まで 1 行で書く
  • 目標値を決められない場合は「許容しない状態」を先に定義する（例: 個人情報を平文でログに出さない）

例（1 行で合意する書き方）:

  • 可用性: 営業時間内は主要導線（作成/割り当て/完了）が利用できること（失敗は検知し、復旧手順がある）
  • 性能: 主要導線は利用者が待てる範囲で応答すること（測定対象: API の応答時間をログ/メトリクスで集計）
  • セキュリティ: 認可は API 側で必ず検証すること（UI の表示制御に依存しない）/ 個人情報はログに出さない
  • 監査/運用: 「誰が/いつ/何をしたか」が追えること（監査ログの記録範囲と保持期間を合意する）

演習（最小1個）

ランニング例に対して、以下を作成してください。

  1. 要求（Needs/Goals）を 1 つ整理する（目的・課題・KPI・非ゴール）
  2. 要件（Shall）を 5 つ列挙する（実装方法に依存しない約束）
  3. 仕様（Behavior）として、受け入れ条件を 3 つ作成する（Given/When/Then 形式推奨）
  4. 非機能（可用性/性能/運用/セキュリティ）の 最小合意 を 1 行ずつ決める

テンプレは Appendix B を利用してください。

よくある失敗

  • 要件を仕様書（画面）として固定し、業務価値・制約条件の合意を飛ばす
  • 「性能」「セキュリティ」などの言葉だけが並び、検証条件が存在しない
  • 例外系（権限、競合、失敗時の振る舞い）が未決のまま設計に入る

チェックリスト

  • 要件に、検証可能な受け入れ条件が含まれている
  • To-Be と As-Is の差分（ギャップ）が説明できる
  • 非機能の最小合意（例: SLA/SLO、ログ、監査）が定義されている
  • 「重要な例外系」が列挙されている
  • 主要要件が、仕様/設計/テストのどこで担保されるか追跡できる（任意）
  • 主要導線の受け入れ条件に ID が付与されている（任意）
Edit this page on GitHub