要件定義 レッスン6
仕様書の書き方
読み手に伝わる仕様書の構成と、曖昧さを排除して認識齟齬を防ぐ書き方のコツを学ぶ
良い仕様書の条件
仕様書は、書いた本人だけでなく、初めてその機能に触れるメンバーや、 数ヶ月後の自分自身が読んでも同じ理解にたどり着けることを目指して書きます。
明確であること
読み手によって解釈が分かれる余地がない
一貫性があること
用語や表記が文書全体で統一されている
検証可能であること
実装がその仕様を満たしたかどうかテストで確認できる
仕様書の基本構成
機能ごとに構成が多少変わっても、次のような要素をそろえておくと 読み手が必要な情報にたどり着きやすくなります。
# 機能名: 注文履歴の確認
## 背景・目的
- 顧客からの「過去の注文を見返したい」という要望に対応する
- 関連する要求: サポート問い合わせ件数の削減（再購入時の商品検索）
## 対象範囲（スコープ）
- ログイン済みユーザーの注文履歴一覧表示
- 注文詳細（商品名・数量・金額・配送状況）の表示
## 対象外（このリリースでは扱わないこと）
- 注文のキャンセル・返品申請機能
- 注文履歴のCSVエクスポート
## 詳細仕様
- 表示順序: 注文日時の新しい順
- 1ページあたりの表示件数: 20件、ページネーションあり
- 未ログインユーザーがアクセスした場合: ログインページへリダイレクト
## 非機能要件
- 一覧表示の応答時間: 95パーセンタイルで500ms以内
## 未確定事項・検討中の論点
- 退会済みユーザーの注文履歴表示可否は別途デザインチームと調整中ポイント
「対象外」のセクションを明記することは、スコープ管理の合意内容を仕様書に反映する 重要な役割を持ちます。書かないままだと「対応してもらえる」と誤解されがちです。
曖昧な表現を避ける
仕様書に潜みやすい曖昧な表現は、読み手ごとに異なる解釈を生みます。 具体的な条件や振る舞いに言い換える習慣をつけましょう。
避けたい表現
- ❌ 「エラーの場合は適切に処理する」
- ❌ 「大量のデータなど、必要に応じて対応する」
- ❌ 「基本的にはこの動作にする」
言い換えた表現
- ✅ 「在庫が0件の場合はエラーメッセージ『在庫切れです』を表示する」
- ✅ 「1回のリクエストで10,000件を超えるデータは分割してレスポンスを返す」
- ✅ 「入力値が空欄の場合は送信ボタンを非活性にする。それ以外の場合は活性にする」
仕様のレビューと合意形成
仕様書は書いて終わりではなく、関係者にレビューしてもらい、合意を得ることで 初めて「共通認識」として機能します。
1
対象読者を意識してレビュー依頼する
PO・エンジニア・QAなど、異なる視点からのフィードバックを集める
2
未確定事項を隠さず明記する
決まっていないことを「決まっているふり」で書かない
3
変更履歴を残す
後から「いつ・なぜ」変わったのかを追跡できるようにする
ポイント
- • 良い仕様書は明確・一貫性・検証可能という3条件を満たす
- • 背景・目的、対象範囲、対象外、詳細仕様、非機能要件を構成要素として揃える
- • 「適切に」「など」といった曖昧な表現を、具体的な条件と振る舞いに言い換える
- • 未確定事項は隠さず明記し、決まっているふりをしない
- • 仕様書はレビューを経て関係者の合意を得ることで共通認識として機能する
確認クイズ
1 / 3仕様書に「対象外（このリリースでは扱わないこと）」を書く目的として最も適切なものはどれか？