外部設計書を書くときに大事なのは、きれいな文章を書くことではありません。
読み手が同じ判断をできることです。
書いた本人は、打ち合わせの経緯、既存仕様、口頭で決まったこと、業務上の前提を知っています。
しかし、外部設計書を読む人が同じ前提を持っているとは限りません。
実装者、レビュー者、テスト担当者、保守担当者、お客様が読んだときに、同じ動きを想像できるか。
そこが弱いと、レビューで止まります。
この記事は、外部設計書をきれいに見せるための記事ではありません。
仕様が伝わるか、実装できるか、テストケースに落とせるか、要件と合っているかを確認しやすくするための記事です。
この記事で扱うこと
この記事では、外部設計書を書くときに意識したい観点を整理します。
- 外部設計書は誰が読むのか
- 自己レビューで何を見るべきか
- 1週間後、1年後の自分が読んでも分かるか
- 曖昧な仕様が後工程で何を起こすか
- レビューで止まりやすい書き方
- 日本語、見出し、表記ゆれをなぜ揃える必要があるか
- テストケースに落とせる設計書とは何か
後編では、ECサイトの注文管理画面を例にして、悪い例、何が悪いか、修正例を具体的に見ています。
後編はこちらです。
最初に結論
外部設計書は、自分が理解するためのメモではありません。
関係者が同じ判断をするための資料です。
そのため、次の内容が読み取れる必要があります。
| 観点 | 読み取れるべきこと |
|---|---|
| 対象 | どの画面、どの項目、どのボタン、どのデータの話か |
| 条件 | どの状態で処理するのか |
| 処理 | 何をするのか |
| 結果 | 処理後に何が変わるのか |
| 例外 | 処理できない場合にどうなるのか |
| 表示 | 画面、メッセージ、ボタン状態がどうなるのか |
| テスト観点 | 何を確認すれば仕様を満たしたと言えるのか |
| 保守観点 | 後から読んでも判断理由を追えるか |
文章として読めても、これらが分からない場合は、仕様としては弱いです。
外部設計書は誰が読むのか
外部設計書は、開発者だけが読む資料ではありません。
複数の立場の人が、それぞれ違う目的で読みます。
| 読み手 | 見ていること |
|---|---|
| お客様 | 要件と動きが合っているか |
| レビュー者 | 仕様として矛盾や抜けがないか |
| 実装者 | 何を作ればよいか |
| テスト担当者 | 何を確認すればよいか |
| 保守担当者 | 後から見て動きを理解できるか |
| 未来の自分 | 当時の判断理由と仕様の意図を追えるか |
ここを意識しないと、書き方が自分向けになります。
自分は分かる。
同じチームの人なら分かる。
打ち合わせに出ていた人なら分かる。
この前提で書くと、外部設計書としては危険です。
外部設計書では、打ち合わせに出ていない人が読んでも、仕様を追える必要があります。
外部設計書はお客様も読む
外部設計書は、内部の実装メモではありません。
お客様が、要件と実際の動きが合っているかを確認するためにも読みます。
そのため、開発側だけで通じる言葉や、内部事情を前提にした説明だけでは足りません。
たとえば、次のような書き方です。
既存仕様と同様に処理します。
開発側では意味が通じるかもしれません。
しかし、お客様から見ると、どの既存仕様を指しているのか、今回の要件とどう合っているのかが分かりにくい場合があります。
外部設計書では、内部の前提ではなく、機能としてどう動くのかを書きます。
「知っている人なら分かる」は、外部設計書では弱いです。
お客様、実装者、テスト担当者が読んでも、同じ動きを想像できるところまで書く必要があります。
自己レビューでは、初めて読む人の目線に戻す
設計書を書いた後は、一度頭をまっさらにして読むことが大切です。
書いた本人は、仕様の背景を知っています。
打ち合わせで出た話も知っています。
既存機能の動きも知っています。
だから、少し説明が足りなくても、自分の頭の中で補完できてしまいます。
しかし、読み手が同じ情報を持っているとは限りません。
また、読み手は他人だけではありません。
1週間後、1か月後、1年後の自分も読み手になります。
設計書を書いている時点では、打ち合わせの内容や判断理由を覚えています。
しかし、時間が経つと、その前提は薄れます。
そのときに「なぜこの条件にしたのか」「どの画面の話なのか」「エラー後に何を変えないのか」が読み取れないと、過去の自分に確認することになります。
今の自分が分かることと、未来の自分が分かることは同じではありません。
自己レビューでは、次のように確認します。
- この文だけで対象が分かるか
- どの画面の話か分かるか
- どのボタンを押したときの話か分かるか
- 条件が分かるか
- 処理結果が分かるか
- エラー時の動きが分かるか
- 画面やデータが変わるのか、変わらないのか分かるか
- テストケースに落とせるか
- お客様が読んで、要件と合っていると判断できるか
- 1週間後、1か月後、1年後の自分が読んでも判断できるか
自分が読んで一瞬でも迷う箇所は、前提を知らない人にはさらに伝わりにくい可能性があります。
外部設計書では、「今の自分は分かる」では足りません。
読み手が同じ判断をできるかを確認します。
設計書を書いている最中は、仕様の背景が頭に残っています。
しかし、その記憶は残り続けません。
外部設計書は、今の記憶に頼って読む資料ではなく、後から読んでも文書だけで判断できる資料にする必要があります。
自分が知っていることを、読み手も知っているとは限らない
設計書でよくあるのが、前提を省略した書き方です。
たとえば、次のような表現です。
必要に応じてメッセージを表示します。
対象データを更新します。
既存仕様と同様に処理します。
エラー時は処理を中止します。
書いた本人は意味が分かっているかもしれません。
しかし、読み手は次の点で迷います。
| 表現 | 読み手が迷うこと |
|---|---|
| 必要に応じて | 何を条件に必要と判断するのか |
| 対象データ | どのテーブル、どの項目、どの画面項目なのか |
| 既存仕様と同様 | どの機能、どの画面、どの処理と同じなのか |
| 処理を中止 | 中止後に画面や入力値はどうなるのか |
外部設計書では、読み手に前提を補完させないことが大切です。
外部設計書はテストケースの元になる
外部設計書は、実装者だけでなく、テスト担当者も読みます。
テスト担当者は、設計書をもとにテストケースを作ります。
そのため、条件と結果が曖昧な設計書は、テストケースに落とし込みにくくなります。
たとえば、次のような記載です。
入力内容に不備がある場合は、エラーを表示します。
一見すると意味は分かります。
しかし、テストケースを作るには情報が足りません。
- 何を不備とするのか
- 必須未入力なのか、桁数超過なのか、形式不正なのか
- どのメッセージを表示するのか
- エラー表示後、入力内容は残るのか
- 登録処理は実行されないのか
- どの画面に戻るのか
- ボタンの状態は変わるのか
ここが書かれていないと、テスト担当者は確認するか、推測してテストケースを書くことになります。
推測で作られたテストケースは、仕様とずれる可能性があります。
曖昧な仕様が後工程で引き起こすこと
曖昧な仕様は、書いた時点では文章の問題に見えます。
しかし、後工程では実装、レビュー、テスト、保守の問題になります。
外部設計書に条件や結果が書かれていない場合、実装者はどこかで判断する必要があります。
その判断が設計者の意図と違えば、レビューで差し戻しになります。
レビューで見つからなければ、テストで不具合になります。
テストでも見つからなければ、本番後の問い合わせや障害になります。
曖昧な文章は、後から誰かが解釈して埋めることになります。
そして、その解釈が人によって変わると手戻りになります。
外部設計書の曖昧さは、後工程で消えるわけではありません。
実装者の迷い、テストケースの抜け、レビューの手戻り、仕様確認の増加として後から出てきます。
レビューで止まりやすい設計書の共通点
レビューで止まりやすい設計書には、いくつか共通点があります。
ここからは、特に見られやすい観点を整理します。
1. 画面・ダイアログ・メニューを混同しない
画面、ダイアログ、メニューは別のものです。
この区別が曖昧だと、実装範囲が変わります。
たとえば、次の2つは意味が違います。
クーポン入力画面を追加します。
注文確認画面の編集メニューに「クーポン適用」を追加し、選択時にクーポン適用ダイアログを表示します。
前者は新しい画面を作るように読めます。
後者は既存画面からダイアログを表示する仕様です。
メニューに追加するものと、メニュー選択後に表示するものも分けて書きます。
編集メニューに「クーポン適用」を追加します。
「クーポン適用」選択時は、クーポン適用ダイアログを表示します。
このように分けると、実装者もテスト担当者も確認しやすくなります。
2. 「等」「任意」「適切に」で読み手に判断を渡さない
外部設計書では、曖昧な言葉をそのまま使うと読み手に判断を渡してしまいます。
特に注意したいのは、次の言葉です。
| 表現 | 問題 |
|---|---|
| 等 | 何が含まれるのか分からない |
| 任意 | 範囲が分からない |
| 適切に | 判断基準が分からない |
| 必要に応じて | 何を条件に必要とするのか分からない |
| 同様に | 何と同じなのか分からない |
| 調整する | 何をどう変えるのか分からない |
| 行う | 処理内容が分からない |
たとえば、次のような書き方です。
法人会員等の場合は、クーポンを使用できません。
この場合、「等」に何が含まれるのかが分かりません。
法人会員だけなのか。
ゲスト購入も含むのか。
退会済み会員も含むのか。
読み手が判断することになります。
外部設計書では、対象を明記します。
以下の購入者区分では、クーポンを使用できません。
- 法人会員
- ゲスト購入
- 退会済み会員
曖昧な言葉を使う場合は、その範囲や条件まで書きます。
3. 条件と結果をセットで書く
仕様は、条件と結果をセットで書くと読みやすくなります。
条件だけでは足りません。
結果だけでも足りません。
たとえば、次のような書き方です。
注文ステータスが出荷済みの場合は、キャンセルできません。
意味は分かります。
しかし、画面仕様としては少し足りません。
- キャンセルボタンを非表示にするのか
- キャンセルボタンを不活性にするのか
- 押下時にエラーを出すのか
- そもそもメニューに表示しないのか
読み手によって想像する動きが変わります。
外部設計書では、条件と結果を分けて書きます。
注文ステータスが「出荷済み」の場合、キャンセルボタンを不活性とします。
これなら、テスト担当者は「出荷済み注文でキャンセルボタンが不活性になること」を確認できます。
4. エラー時に何が変わり、何が変わらないかを書く
エラー時の仕様では、メッセージを表示するだけでは足りないことがあります。
処理後の状態が重要です。
たとえば、次のような書き方です。
在庫不足の場合は、エラーメッセージを表示し、注文確定処理を中止します。
これだけでは、次が分かりません。
- メッセージを閉じた後、どの画面に戻るのか
- 入力内容は残るのか
- カート内容は変わるのか
- 注文データは作成されるのか
- 支払情報は保持されるのか
エラー時は、何を変更しないのかも書きます。
在庫不足の場合は、在庫不足メッセージを表示し、注文確定処理を中止します。
メッセージを閉じた後は、注文確認画面に戻ります。
カート内容、配送先、支払方法は注文確定前の状態から変更しません。
ここまで書くと、実装者もテスト担当者も判断しやすくなります。
5. 見出しは仕様を探すための目印にする
見出しは文章の飾りではありません。
仕様を探すための目印です。
見出しが弱いと、読み手は必要な情報を探せません。
たとえば、次のような見出しです。
機能概要・画面イメージ
この見出しの中に、画面項目、操作仕様、エラー仕様、画面イメージが混ざると読みづらくなります。
それぞれ役割が違うためです。
| 見出し | 書く内容 |
|---|---|
| 画面仕様 | 表示項目、ボタン、入力欄 |
| 操作仕様 | ボタン押下時、メニュー選択時の動き |
| 入力チェック | 必須、桁数、形式、範囲 |
| エラー仕様 | メッセージ、処理中止、状態維持 |
| 画面イメージ | キャプチャ、注釈、画面上の位置関係 |
見出しを分けると、読み手は必要な仕様にたどり着きやすくなります。
外部設計書では、見出しで情報の置き場所を作ります。
6. 表記ゆれは仕様の不一致として扱う
表記ゆれは、単なる文章の問題ではありません。
外部設計書では、仕様の不一致に見えることがあります。
たとえば、同じものを次のように書いていた場合です。
会員ID
顧客ID
ユーザーID
本当に同じものなのか。
別の項目なのか。
読み手は判断できません。
同じものは同じ名前で書きます。
別のものなら、違いを定義します。
表記ゆれが起きやすいものは、特に注意します。
| 揺れやすいもの | 例 |
|---|---|
| 画面名 | 注文確認画面 / 注文内容確認画面 |
| ダイアログ名 | クーポンダイアログ / クーポン適用ダイアログ |
| ボタン名 | OKボタン / 確定ボタン |
| 項目名 | 会員ID / 顧客ID / ユーザーID |
| 状態名 | 無効 / 不活性 / 押下不可 |
| 処理名 | 登録 / 保存 / 更新 |
表記ゆれがあると、レビュー者は「同じ意味ですか？」を確認する必要があります。
この確認が増えるほど、レビューは重くなります。
表記ゆれは、読む人に余計な判断を発生させます。
同じものは同じ名前で書き、違うものは違いが分かる名前にします。
7. 計算仕様は式・丸め・表示桁・計算順序を書く
計算がある仕様では、結果だけでは足りません。
式、丸め、表示桁、計算順序が必要です。
たとえば、次のような書き方です。
合計金額に応じて送料を計算します。
これだけでは、実装できません。
- 税込金額で判定するのか
- 税抜金額で判定するのか
- クーポン適用前なのか
- クーポン適用後なのか
- 小数が出た場合にどう丸めるのか
- 表示は整数なのか、小数第2位までなのか
計算仕様は、できるだけ式で書きます。
送料判定金額 ＝ 商品小計（税込） － クーポン割引額
送料判定金額が5,000円以上の場合、送料を0円とします。
送料判定金額が5,000円未満の場合、送料を500円とします。
丸めがある場合は、丸め方も書きます。
ポイント付与数 ＝ 商品小計（税込） × 付与率
算出結果に小数が発生した場合は、小数点以下を切り捨てます。
計算仕様が曖昧だと、実装者、テスト担当者、お客様の認識がずれやすくなります。
8. 画像の注釈と本文を対応させる
画面キャプチャに吹き出しや番号を付ける場合は、本文と対応させます。
画像に番号があるのに本文で説明していない。
本文に項目名があるのに画像上のどこを指すのか分からない。
この状態だと、読み手は画像と本文を行き来しながら推測することになります。
画像に番号を付けるなら、本文も同じ番号で説明します。
① クーポンコード入力欄
② 適用ボタン
③ エラーメッセージ表示領域
さらに、本文でも同じ番号を使います。
① クーポンコード入力欄に入力された値を検証します。
未入力の場合は、③ エラーメッセージ表示領域にメッセージを表示します。
画面イメージは、見た目を伝えるだけではありません。
本文の仕様を探しやすくするためにも使います。
9. 予告文や締め文を書きすぎない
外部設計書では、章タイトルで内容が分かるなら、予告文や締め文は最小限で十分です。
たとえば、次のような文章が続くと、読む量だけが増えます。
本章では、クーポン適用機能について説明します。
以上がクーポン適用機能の説明です。
章タイトルが「クーポン適用機能」であれば、同じ内容を繰り返しているだけです。
もちろん、前提や注意点がある場合は書くべきです。
ただし、意味のない予告や締めは、仕様を探すときのノイズになります。
外部設計書では、読みやすさだけでなく、探しやすさも重要です。
レビュー前チェックリスト
外部設計書を自己レビューするときは、次の観点で確認すると見落としを減らせます。
読み手の観点
- 書いた本人以外が読んでも意味が分かるか
- お客様が読んで、要件と合っていると判断できるか
- 実装者が読んで、作る内容を判断できるか
- テスト担当者が読んで、テストケースに落とせるか
- 保守担当者が後から読んでも、仕様の意図を追えるか
- 1週間後、1か月後、1年後の自分が読んでも、同じ判断ができるか
文章の観点
- 主語が抜けていないか
- 対象が明記されているか
- 条件が明記されているか
- 処理結果が明記されているか
- 「等」「任意」「適切に」「同様に」を使いすぎていないか
- 「行います」「調整します」だけで終わっていないか
仕様の観点
- 活性、不活性、非表示の条件が明確か
- エラー時に何が変わり、何が変わらないか分かるか
- 処理中止後の画面状態が分かるか
- 入力値やデータが保持されるのか分かるか
- 計算式、丸め、表示桁、計算順序が分かるか
構成の観点
- 見出しと内容が合っているか
- 画面仕様、操作仕様、エラー仕様が混ざっていないか
- 画像の注釈と本文が対応しているか
- 同じものを同じ名前で書いているか
- 表記ゆれが残っていないか
まとめ
外部設計書で大事なのは、書いた本人が理解できることではありません。
読み手が同じ判断をできることです。
外部設計書は、実装者、レビュー者、テスト担当者、保守担当者、お客様が読みます。
そして、1週間後、1か月後、1年後の自分も読みます。
そのため、自分の前提や今の記憶を読み手に補完させる書き方は避ける必要があります。
特に、次の点はレビューで止まりやすいです。
| 観点 | 問題 |
|---|---|
| 対象が曖昧 | どの画面、項目、データの話か分からない |
| 条件が曖昧 | いつ処理するのか分からない |
| 結果が曖昧 | 処理後に何が変わるのか分からない |
| エラー時が曖昧 | 画面やデータがどうなるのか分からない |
| 見出しが弱い | 仕様を探せない |
| 表記ゆれがある | 同じものか別のものか判断できない |
| 計算仕様が曖昧 | 実装結果やテスト結果がずれる |
外部設計書の曖昧さは、後工程で消えるわけではありません。
実装者の迷い、テストケースの抜け、レビューの手戻りとして表に出ます。
自己レビューでは、一度頭をまっさらにして、初めて読む人の目線で確認することが大切です。
自分が読んで一瞬でも迷う箇所は、前提を知らない人にはさらに伝わりにくい可能性があります。
今の自分が分かる設計書ではなく、未来の自分や他の関係者が読んでも判断できる設計書にする。
それが、外部設計書に求められる最低限の品質だと思います。
後編で扱うこと
前編では、外部設計書を書くときの考え方とレビュー観点を整理しました。
ただ、観点だけでは、自分の文章のどこを直せばよいか分かりにくい場合があります。
後編では、ECサイトの注文管理画面を例にして、レビューで止まりやすい書き方を具体的に見ています。
後編はこちらです。
後編では、次の形で整理しています。
悪い例
↓
何が悪いか
↓
修正例
外部設計書の文章を、どう直せば仕様として伝わりやすくなるかを見ています。