Design Docs
Design Docsとは？
Design DocsとはGoogleなどで取り入れられているシステム設計ドキュメント手法
単なる仕様書ではなく、意思決定の背景やトレードオフ、検討した代案も含めて「設計の理由」を明確化する
高レベルの実装戦略と主な設計の決定事項をまとめて設計において考慮されたトレードオフに重点を置いて文書化する
開発をする前に書き、関係者の意思疎通を円滑するために使う。開発後の手戻りを減らすなどが主な目的
仕様書や設計書とは別物
基本構成
タイトル & 概要
何を解決するドキュメントかをひと目で理解できる。
背景 / 課題
なぜこの機能や改善が必要か。現状の問題や制約。
目標と非目標
何を達成するか、何を範囲外とするか。
提案する設計（アーキテクチャ / フロー）
システム図、データフロー、インタフェース仕様などを含める。
代替案と比較
他のアプローチとの比較。選ばなかった理由。
トレードオフ / リスク
パフォーマンス、コスト、開発スピードなどの観点。
実装計画 / マイルストーン
開発手順や段階的導入の方針。
影響範囲
他のシステム、チーム、利用者への影響。
オープンな課題
未解決の疑問点や追加検討が必要な事項。
Design Docのメリット
合意形成: 実装前に関係者の認識を揃える。
リスク低減: 早い段階で問題点を指摘・修正できる。
知識共有: 後から参画した人も意思決定の経緯を理解できる。
再利用性: 類似プロジェクトで過去の設計の知見を活かせる。
ソフトウェアを開発するエンジニアにとって重要なことは、コードを書くことではなくソフトウェアによってある問題が解決することです。
設計書ようなテキストを使用するということは、プロジェクトを進める中での初期段階で問題を解決することができるツールになるのではないかと言っています。
なぜならば、実際のコードよりも簡潔で理解しやすく、当事者にとってある問題とその解決策を高いレベルで伝えることができる為です。
良いDesign Docの特徴
簡潔で要点が明確（詳細すぎて読まれないのはNG）
図・表を活用（文章だけより理解しやすい）
選択肢と理由が説明されている
他ドキュメントとの違い
Design Doc
まとめ
「どう作るか」を議論・レビューするための舞台
トレードオフや代替案を含め、設計の妥当性を検証する
粒度
機能やシステム全体（PRDより小さく、仕様書より大きい）
目的
実装前に合意形成し、リスクを減らす
タイミング
要件が見えた時点で（実装前にドラフト）
保存場所
Confluence / Google Docs / Notion（議論しやすい場所）
まとめ
Design Doc → 設計全体を議論・レビューする「舞台」
ADR → その議論の中で出た「主要な決定」を抜き出してログ化する「記録」
粒度
1つの意思決定ごと
目的
意思決定の記録、透明性
タイミング
決定が固まった時に記録
保存場所
Gitリポジトリ
粒度
大きな機能単位
目的
ユーザー価値やビジネス目的を明文化する
タイミング
プロジェクトの最初に作成
保存場所
Confluence / Notion / Google Docs などチーム全体が参照できる場所
仕様書
まとめ
システムや機能が「どう動くべきか」を定義する契約書的文書
QAや開発者が参照する「期待する挙動の基準」
粒度
機能やAPIごと
目的
振る舞いやI/Fを正確に定義し、ブレをなくす
タイミング
Design Docで方向性が固まり、実装前に整備
保存場所
Confluence、Wiki、リポジトリ（場合によってはOpenAPI定義ファイル）
設計書
まとめ
クラス図、DBスキーマ、シーケンス図など具体的な構造を示す
粒度
モジュールやサービス単位（詳細設計なら関数レベルまで）
目的
実装者が迷わず手を動かせるレベルに落とす
タイミング
Design Docの方針が承認された後
保存場所
リポジトリ（docs配下など）やWiki
文書間の依存関係
code:text
PRD（何を作るか／ビジネス目的）
↓
要件定義書（機能・非機能要件に落とす）
↓
Design Doc（どう作るか／設計の方向性・選択肢・トレードオフ）
↓
設計書（実装レベルに落とし込んだ仕様）
必ずこの順番って感じではないけどだいたいこんな感じのことが多い
/icons/hr.icon