タイトル: 詳細設計
SEOタイトル: ソフトウェア詳細設計完全ガイド
| この記事の要点 |
|
詳細設計とは
詳細設計 (Detail Design) は、基本設計（外部設計）で決まった「何を作るか」を、プログラマがそのまま実装できる粒度に詳細化する工程です。How を決める段階であり、内部設計とも呼ばれます。
ウォーターフォール型開発では基本設計と実装の間に独立した工程として明確に区切られますが、Agile / DevOps 時代には「Just enough design」として実装と並行する形が主流になっています。
開発工程における位置づけ
+---------------+
| 要件定義 | 何を作るか (What)
+---------------+
| 基本設計 | 外部から見える振舞 (What をどう実現する大枠)
+---------------+
| ★ 詳細設計 | 内部実装の青写真 (How)
+---------------+
| 実装 | コーディング
+---------------+
| 単体テスト | 詳細設計通りか確認
+---------------+
| 結合テスト | 基本設計通りか確認
+---------------+
| 総合テスト | 要件通りか確認 (V 字モデル)
+---------------+
| 受入テスト |
+---------------+基本設計との違い
| 項目 | 基本設計 | 詳細設計 |
|---|---|---|
| 視点 | ユーザー視点 (外部) | 開発者視点 (内部) |
| 主成果物 | 業務フロー, 画面遷移, ER 図 (論理) | クラス図, シーケンス図, ER 図 (物理), テーブル定義書 |
| 粒度 | 機能単位 | 関数・モジュール単位 |
| レビュー参加者 | 顧客 + PM | 開発リーダー + プログラマ |
| 変更影響 | 大きい (要件まで遡る) | 小さめ (実装内に閉じる) |
主要な成果物
1. クラス図 (UML Class Diagram)
システムを構成するクラス、その属性・操作、クラス間の関係（継承・実装・関連・集約・コンポジション）を表現:
+----------------+ +----------------+
| Customer | 1 * | Order |
|----------------|-------->|----------------|
| -id: Long | | -id: Long |
| -name: String | | -date: Date |
| -email: String | | -total: Money |
|----------------| |----------------|
| +register() | | +addItem() |
| +login() | | +calc Total() |
+----------------+ +----------------+
^
|
|
+----------------+
| OrderItem |
|----------------|
| -qty: int |
| -price: Money |
+----------------+2. シーケンス図 (UML Sequence Diagram)
あるユースケースを実現するために、オブジェクト間でどのようにメッセージが流れるかを時系列で表現:
User Controller Service Repository DB
| | | | |
|--login()---->| | | |
| |--auth()---->| | |
| | |--findByEmail->| |
| | | |--SELECT->|
| | | |<---User--|
| | |<----User-----| |
| | |--checkPassword| |
| | |--createToken | |
| |<--token-----| | |
|<---200 OK----| | | |
| | | | |3. テーブル定義書（物理 ER 図）
| 項目 | 例 |
|---|---|
| テーブル物理名 / 論理名 | m_users / 会員マスタ |
| カラム物理名 / 論理名 | email / メールアドレス |
| データ型 / 桁数 | VARCHAR(255) |
| NULL 可否 | NOT NULL |
| PK / FK / UNIQUE | PK / FK to t_dept.dept_id |
| DEFAULT | NOW() |
| 備考 / 制約 | 形式は RFC 5322 準拠 |
| サンプル値 | taro@example.com |
4. 画面項目定義書
各画面の項目について以下を明文化:
- 項目 ID / 名称 / 種別 (TextBox / Select / Checkbox)
- 最大文字数・形式 (半角英数 / 数値 / 日付)
- 必須 / 任意
- 初期値・選択肢
- 入力チェック（クライアント / サーバ）
- 表示条件・活性条件
- イベント（onClick → どの処理を呼ぶか）
5. 入出力定義 (I-O)
外部システム連携・バッチの入出力ファイル仕様:
- ファイル名・配置場所
- 文字コード・改行コード
- レコード長・項目順・項目仕様
- 連携タイミング・連携手段（SFTP / API / S3）
- 異常時の扱い（リトライ / アラート）
アルゴリズムの明示
複雑なロジックは擬似コード / フローチャート / 状態遷移図で明示します:
[割引計算アルゴリズム]
入力: 注文金額, 会員ランク, クーポン有無
出力: 割引後金額
1. base_discount = ランク別割引率 (Bronze: 0%, Silver: 5%, Gold: 10%, Platinum: 15%)
2. coupon_discount = クーポンあれば 500 円固定
3. tax_excluded = 注文金額 / 1.10
4. discounted = tax_excluded * (1 - base_discount) - coupon_discount
5. if discounted < 0: discounted = 0
6. final = ceil(discounted * 1.10) ※ 税込・1円未満切り上げ
7. return finalエラー処理・例外処理
- 業務エラー（バリデーション、整合性違反） → ユーザーに分かりやすいメッセージ + ログ
- システムエラー（DB 接続断、外部 API 障害） → リトライ / 代替処理 / 上位に伝搬
- 致命的エラー → ログ + アラート + 安全停止
- エラーコード体系を統一:
E-XXX-9999形式など - 機密情報をエラーメッセージに出さない（SQL / スタックトレース / 内部 IP）
ロギング設計
| レベル | 用途 |
|---|---|
| TRACE | 詳細なステップ（開発時のみ） |
| DEBUG | 変数値や分岐の確認 |
| INFO | 業務上のイベント (ログイン成功等) |
| WARN | 異常ではないが注視（リトライ、フォールバック発動） |
| ERROR | 業務処理失敗 |
| FATAL | システム停止級 |
ログ項目: 日時 / レベル / リクエスト ID / ユーザー ID / クラス・メソッド / メッセージ / 例外。検索しやすい構造化ログ（JSON 等）が現代的。
トランザクション境界の明示
- 1 ユースケース = 1 トランザクション が基本
- 長時間処理は業務単位で分割（バッチコミット）
- 分離レベルを明示（READ COMMITTED / REPEATABLE READ）
- 分散トランザクション（2PC, Saga パターン）の必要性検討
- ロック粒度（行 / テーブル / ページ）と保持時間を最小化
性能要件と非機能
詳細設計では「性能を出すための実装方針」を明文化:
- 応答時間目標（例: 一覧 200ms 以内、検索 500ms 以内）
- スループット（例: 100 RPS @ p95 500ms）
- Index 設計（どのクエリにどの Index を使うか）
- キャッシュ戦略（Redis TTL, アプリ内 LRU）
- 非同期化（重い処理を Queue で後回し）
- 同時実行数制御（Connection Pool サイズ、並列度）
コーディング規約・命名規則
| 言語 | 標準規約 |
|---|---|
| Java | Google Java Style / Oracle 公式 |
| PHP | PSR-12 / Laravel スタイル |
| Python | PEP 8 |
| JavaScript/TypeScript | ESLint + Airbnb / Prettier |
| C# | Microsoft .NET Framework Design Guidelines |
| Go | Go 公式スタイル (gofmt) |
命名の原則
- 「何をするか」が明確（
processDataではなくcalculateDiscount） - 略語を避ける (
cnt→count,usr→user) - Boolean は is/has/can で開始（
isActive,hasPermission） - 定数は
UPPER_SNAKE_CASE - 言語標準のケースに従う (Java camelCase, Python snake_case)
レビュー手法
| 手法 | 特徴 |
|---|---|
| 机上レビュー | 個人が読んでチェック。最軽量 |
| ウォークスルー | 作成者主導で口頭説明、参加者が指摘 |
| インスペクション | 役割分担して厳密に、チェックリスト使用 |
| ペア設計 | 2 人で同時に設計、リアルタイム議論 |
| モブ設計 | 3 人以上、知識共有重視 |
成果物のテンプレート例
詳細設計書の章構成
- はじめに（目的・対象範囲）
- システム構成（コンポーネント図・配置図）
- クラス設計（クラス図・クラス仕様書）
- シーケンス設計（主要ユースケースのシーケンス図）
- データ設計（物理 ER 図・テーブル定義書）
- 画面設計（画面項目定義・遷移図）
- 入出力設計（外部 I/F・ファイル仕様）
- 処理フロー（複雑ロジックのフローチャート / 擬似コード）
- エラー処理
- ロギング・監視
- セキュリティ設計
- 性能設計
- テスト方針
Agile / モダン開発での詳細設計
従来型ウォーターフォールでは詳細設計書が膨大になりがちですが、現代のアジャイル開発では:
- 「コードが詳細設計」: 自己説明的コード + テストで設計を表現
- 必要な部分だけ図に: 全クラス図ではなく、複雑なドメインのみ作図
- ADR (Architecture Decision Record): 重要決定だけ簡潔に記録
- API 仕様は OpenAPI で: コードとセットで管理
- ER 図は自動生成: schemaspy / dbdocs.io 等で DB から自動描画
Just enough design = 「必要十分な詳細だけを、必要なタイミングで作る」が現代の主流。ただしレガシー連携や監査対応では従来型の詳細設計書も依然有効。
FAQ
Q: 基本設計と詳細設計の境界はどこ？
A: 厳密な境界はなく、組織やプロジェクトで異なります。「画面 / API の外形は基本設計、内部のクラス分割やアルゴリズムは詳細設計」が一般的な目安。
Q: Agile で詳細設計書は不要？
A: 大量の事前設計書は不要ですが、「設計判断の記録 (ADR)」「複雑ロジックの擬似コード」「テーブル定義」は最低限残すべきです。
Q: 詳細設計と実装が乖離するのを防ぐには？
A: 短いサイクルでレビュー、設計を Living Document に、コードからの逆生成を活用、テストでの実行可能仕様化が有効。
Q: 詳細設計のレビュー観点は？
A: 要件カバー / 整合性 / 性能 / セキュリティ / 拡張性 / テスト容易性 / コーディング規約準拠 / レアケース考慮、の 8 観点が代表的。