製造を行うために設計書を確認しているとよくあるのが
登録するってどのテーブルに何を登録するの？
エラー発生時はどうするの？
なんて設計書がきちんと書かれていれば起こるはずもない疑問。。。
ここでは、ダメな設計書について具体例をあげながら見ていきます。
❌ ダメな設計書の具体例
ケース①：抽象すぎて実装できない
ダメな設計
ユーザー情報を登録する処理を行う
👉 問題点
- 何を入力？
- バリデーションは？
- エラー時は？
なぜダメか
👉 実装者が全部考えることになる
→ 人によって実装がバラバラ
改善
入力：
・メールアドレス（必須）
・パスワード（8文字以上）
処理：
・形式チェック
・重複チェック
エラー時：
・エラーメッセージ表示
❌ ケース②：正常系しかない
ダメな設計
注文を登録する
👉 問題点
- 在庫切れは？
- 不正入力は？
- 通信エラーは？
なぜダメか
👉 本番で確実に壊れる
改善
・在庫不足：エラー表示
・入力不正：入力画面へ戻す
・DBエラー：リトライ or ログ出力
❌ ケース③：用語がバラバラ
ダメな設計
顧客ID / ユーザーID / 会員ID
👉 問題点
- 同じ？別物？
- 実装者が迷う
なぜダメか
👉 認識ズレ → バグ発生
改善
顧客ID（=ユーザーID）に統一
❌ ケース④：フローが不明
ダメな設計
ボタン押下で処理を行う
👉 問題点
- 何の順番で処理？
- 成功時・失敗時は？
なぜダメか
👉 実装者が想像で作る
改善
1. 入力チェック
2. DB保存
3. 成功：完了画面
4. 失敗：エラー表示
❌ ケース⑤：要件とズレている
要件
「出荷前のみキャンセル可能」
ダメな設計
キャンセルボタンを表示する
👉 問題点
- 条件が反映されていない
なぜダメか
👉 要件未達 → 手戻り
改善
出荷ステータスが「未出荷」の場合のみ
キャンセルボタンを表示
❌ ケース⑥：データ定義が曖昧
ダメな設計
日付を保存する
👉 問題点
- フォーマットは？
- タイムゾーンは？
- NULL許可？
なぜダメか
👉 システム間で不整合
改善
形式：YYYY-MM-DD
タイムゾーン：UTC
NULL不可
❌ ケース⑦：責務がぐちゃぐちゃ
ダメな設計
1つの関数で
・入力チェック
・DB保存
・メール送信
👉 問題点
- 変更に弱い
- テストしにくい
なぜダメか
👉 保守性が崩壊
改善
・バリデーション処理
・保存処理
・通知処理
に分離
❌ ケース⑧：非機能要件がない
ダメな設計
検索機能を作る
👉 問題点
- 何秒以内？
- 件数制限は？
なぜダメか
👉 本番で遅すぎて使えない
改善
・レスポンス：2秒以内
・最大1000件まで
🧠 ダメな設計書の共通点
全部まとめると👇
👉 「実装者に判断を丸投げしている」
🎯 良い設計書の条件
逆に言うと👇
👉 「誰が作っても同じものになる」
🔚 一言でまとめると
👉 ダメな設計書 =
「読む人によって解釈が変わる設計書」