できるITエンジニアの「設計書・仕様書」作り：読む人が迷わず、誤解せず、実装とテストに落とせる書き方
設計書や仕様書って、書くのに時間がかかるわりに「読まれてない気がする」「結局口で説明してる」「あとで誤解が出て手戻りする」になりがちです。
でも、できるエンジニアが本気で重視しているのは、文章のカッコよさではなくて次の一点です。
読む人が迷わず、誤解せず、実装とテストに落とせること。
設計書は作者の頭の良さを見せる場ではなく、チームの意思決定と品質を安定させるための道具です。だから「情報を盛る」より「誤読と抜け漏れを減らす構造」を先に作ります。
この記事では、そのための要所を、親しみやすい手順としてまとめます。
まず固定する：この文書は何を決めるのか（目的）と、どこまで決めるのか（範囲）
仕様書とひと口に言っても、要求（何を実現するか）を書いているのか、外部仕様（画面やAPIの振る舞い）を書いているのか、内部設計（構造や処理の流れ）を書いているのかで、読む人の期待が変わります。
ここが曖昧だと、読み手は「書いてないこと」を勝手に補完してしまい、誤解の温床になります。
冒頭で最低限そろえたいのは、次の3つです。
文書の目的（要求なのか、外部仕様なのか、内部設計なのか）
対象機能（今回決めるもの）
対象外（今回決めないもの）
この3つが書けているだけで、「この文書に書いてないこと」を根拠に議論しなくなります。
さらに、改訂履歴と意思決定の根拠を残しておくと、後日仕様変更が入ったときに「なぜそう決めたのか」を追えます。これは手戻り削減に効きます。ドキュメントは一回書いて終わりではなく、更新され続ける前提で設計するのが現実的です。Googleのドキュメント作法でも、古い・重複・不正確な情報を減らし、短く有用な文書を保つ姿勢が推奨されています。
迷子防止：詳細の前に「全体地図」を先に渡す
優れた設計書は、詳細が正しいだけでなく、読み手が短時間で次を把握できます。
自分の担当範囲はどこか
影響範囲はどこまでか
どのページ（章）を読めば良いか
このために、詳細に入る前に全体像を提示します。文字で長々と説明するより、まず地図です。
画面の話なら画面遷移（利用者の流れ）
データの話なら入力→保存→出力（データの流れ）
システムの話なら境界（自システムと外部の境目）
この地図があるだけで、読み手は「今どこを読んでいるか」を見失いません。
Googleのエンジニアリング実践でも、チームで同じやり方を共有し、レビューや合意形成を進めることが重要だとされています。設計書は、まさにそのための共通言語です。
文章で説明しない：仕様は「条件と結果」の規則として書く
設計書が読みづらくなる最大の理由は、仕様が“説明文”になっていることです。
読む側が欲しいのは、物語ではなく規則です。
振る舞い（何が起き、何が返るか）を、条件と結果の形に落として書きます。
画面なら、入力項目、必須条件、入力制限、エラー表示、保存後の状態
APIなら、リクエスト項目、成功レスポンス、失敗レスポンス、状態コード、例外時の扱い
バッチなら、起動条件、対象範囲、処理順、再実行時の扱い
そして、曖昧な言い回しを避けます。
「適切に」「必要に応じて」「状況によって」
このあたりは、書く側は便利でも、読む側は実装できません。曖昧さは残しても良いのですが、その場合は「未確定事項」として明示して管理します（後述）。
規則として書くと、自然にテストも作りやすくなります。テストは仕様の裏返しだからです。
非機能を付録にしない：性能・可用性・セキュリティ・運用は本文で決める
現場の手戻りの多くは、非機能の見落としから起きます。機能は動いているのに、次の理由で作り直しになるパターンです。
同時アクセスが増えたら遅い
障害時に復旧できない
ログが足りず原因が追えない
個人情報の扱いが危ない
運用が回らない
だから非機能は「あとで考える付録」にせず、仕様の一部として先に決めます。特にITサービスは、運用で価値が決まります。
ここで便利なのが、クラウド各社が出している「よい設計の観点」です。AWSやAzure、Google Cloudは、信頼性や運用性、セキュリティ、費用など、設計で見落としがちな論点を体系化しています。設計書を書く側がこれを“点検表”として使うと、非機能の抜けを減らせます。
境界と例外を先に潰す：正常系より先に「壊れ方」を決める
仕様の事故が起きやすいのは、境界と例外です。
どこまでが自システムの責任か
どこからが外部の責任か
外部サービスが落ちたらどうするか
タイムアウトしたらどうするか
重複送信されたらどうするか
権限が足りないときはどう返すか
こういう話を「実装でうまくやります」で済ませると、障害時に破綻します。
できるエンジニアは、正常系より先に例外の扱いを定義して、サービスの耐性を確保します。ここが決まると、実装もテストも一気に安定します。
言い方の統一も大事です。仕様書で「しなければならない」「してよい」などの強さがバラバラだと、読み手が混乱します。IETFのRFC 2119は、仕様文書で要求レベルを示す言葉（MUST、SHOULD、MAYなど）をどう解釈するかを定義しています。プロトコル以外でも「この条件は必須」「ここは推奨」「ここは任意」を言葉の強さで揃えるだけで、誤解が減ります。
テスト可能性が設計書の品質を決める：受け入れ条件を書けるか
設計書の良し悪しは、「テスト観点が自然に出てくるか」でかなり判定できます。
受け入れ条件（この条件を満たせばOK）
境界値（最小・最大・ちょうど）
エラーメッセージ（何を出すか）
異常系（権限なし、必須欠落、二重送信、外部失敗など）
これが書かれていれば、テストは設計書から直接作れます。
逆に、テストが作れない仕様書は、実装者の解釈に依存しやすく、品質がぶれます。チーム開発で「人によってできが違う」を減らすには、設計書にテスト可能性を埋め込むのが近道です。
未確定事項は隠さない：質問リストとして管理して、期限と決定者を書く
現実には、すべてを最初から決め切れない場面が必ずあります。ここでやりがちなのが、未確定を文中に溶かしてしまうことです。
「必要に応じて」「状況により」「あとで相談」
こうなると、実装が始まった瞬間に“仕様があるように見える未確定”が増えます。
未確定は未確定として、質問リストに切り出します。さらに、決める期限と決定者をセットで書きます。
これだけで、曖昧なまま実装が進む事故をかなり防げます。
Atlassianのドキュメント作法でも、対象読者に合わせて分かりやすく書くことや、フィードバックで改善することが重視されています。未確定を見える化するのは、まさにチームで改善を回すための前提です。
すぐ使える雛形：迷わない構造を最初から用意する
最後に、ここまでの考え方をそのまま形にした雛形を置いておきます。チームに合わせて削って使うのがおすすめです。
# （タイトル）
## 1. 目的
この文書は何を決めるか。
## 2. 範囲
対象機能：
対象外：
## 3. 前提
利用者、権限、外部システム、制約。
## 4. 全体像
画面遷移／API一覧／データの流れ／システム境界。
## 5. 仕様（条件→結果）
画面、API、バッチごとに「いつ」「何が起きるか」を規則で書く。
## 6. 非機能
性能、可用性、セキュリティ、運用、互換性。
## 7. 例外・境界
外部失敗、タイムアウト、重複、権限不足、再実行。
## 8. テスト観点（受け入れ条件）
正常系、異常系、境界値、期待するログ、期待する通知。
## 9. 未確定事項
質問、決定者、期限。
## 10. 改訂履歴
いつ、何を、なぜ変えたか。
雛形を使うと「書く内容の漏れ」が減り、レビューも速くなります。書く側も読む側も、疲れにくくなります。
まとめ：設計書は“盛る”より“迷わせない”が勝つ
設計書・仕様書作成の要点は、情報量を増やすことではありません。
目的と範囲を固定する
全体像を先に渡す
振る舞いを条件と結果で書く
非機能を本文で決める
境界と例外を先に潰す
テスト可能性を担保する
未確定事項を管理する
この要所を押さえるだけで、開発の速度と品質が同時に底上げされます。結果として、長期運用でも破綻しにくい土台になります。
設計書は、あなたの手を速くする道具でもあります。迷わせない構造を先に作って、チームの力を上げていきましょう。
参考文献
ISO/IEC/IEEE 29148:2018(en) Systems and software engineering — Life cycle processes — Requirements engineering（概要）
https://www.iso.org/obp/ui/en/
IETF RFC 2119 Key words for use in RFCs to Indicate Requirement Levels
https://datatracker.ietf.org/doc/html/rfc2119
Google Engineering Practices Documentation
https://google.github.io/eng-practices/
Atlassian Software Documentation Best Practices
https://www.atlassian.com/blog/loom/software-documentation-best-practices