デザインドキュメント

(でざいんどきゅめんと/設計ドキュメント/Design Doc)

文書で確認(海外)
2020年
更新
2026-11-03

一言でいうと

実装に入る前に、システムの設計の目的、検討した選択肢、採用した案とその理由を書き、関係者のレビューで合意を得るための文書です。

面接では、書き手として設計のトレードオフを説明した経験と、レビュアーとして他者の設計に指摘した経験を分けて確認します。

提唱者と登場年

デザインドキュメントは、特定の提唱者がいる語ではありません。ここで示す2020年は、書籍『Software Engineering at Google』が刊行された年で、語が使われ始めた年を示すものではありません。同書のドキュメントの章は、Googleのほとんどのチームが、大きなプロジェクトに着手する前に、承認されたデザインドキュメントを求めていると説明しています。

Googleでの書き方は、記事「Design Docs at Google」にもまとめられています。記事によると、デザインドキュメントは、システムの主な書き手がコーディングの前に作る、形式の緩い文書です。実装の方針と主要な設計判断を、トレードオフに重点を置いて記録します。典型的な構成として、背景と範囲、ゴールと非ゴール、設計そのもの、検討した代替案、セキュリティ・プライバシー・可観測性といった横断的な関心事が挙げられています。

何を解決するか

コードを書いた後に設計の問題が見つかると、作り直す範囲が大きくなります。デザインドキュメントを書くと、変更の費用が小さい段階で設計の問題を見つけ、組織内の合意を得ることができます。検討して採用しなかった案とその理由が文書に残るため、後から加わったメンバーも設計の経緯を確認できます。経験のあるエンジニアがレビューで出した指摘は、チームの知見として共有されます。

記事「Design Docs at Google」は、問題や解決策が複雑で設計に曖昧さがあるかを、書くかどうかの判断基準に挙げています。トレードオフを含まず、実装の手順書のように読める文書は、書く価値が小さいと考えられます。複数のメンバーが同じシステムの設計判断を共有する組織で、効果が出やすいと考えられます。

実際の進み方

書き手が初稿を作成し、問題領域に詳しい同僚と改稿を重ねます。次に、より広い読み手のレビューを受けます。形式は、チームのメーリングリストへの共有から正式な設計レビュー会議まで幅があります。Googleでは、チームが承認したテンプレートで書くのが一般的で、標準のテンプレートはセキュリティへの影響やプライバシーなどの検討を求めています。

以後のレビューで大きな変更が出る見込みが小さくなったら、実装に進みます。実装中に設計が変わった場合は、文書を更新します。書き手が1〜2年後に文書を読み返すと、設計判断の当否を振り返ることができます。

導入でよくある失敗

  • テンプレートの項目をすべて書くことが目的になり、検討した代替案とトレードオフが書かれない
  • 解決策が明らかな変更にまで作成を義務づけ、レビュー待ちで実装が止まる
  • 実装中に設計が変わっても文書を更新せず、実装と食い違った文書が残る

求人票にこの語がある場合に読み取れること

設計の判断を実装前に文書で共有し、レビューで合意する開発文化があると読み取れます。求人票では、デザインドキュメントの作成を任せるのか、他チームの設計のレビューと承認まで任せるのかを書き分けると、期待する役割が伝わります。Staff Engineerやソフトウェアアーキテクトの採用では、他チームの設計をレビューした経験が評価の材料になります。候補者には、自ら書いたデザインドキュメントで採用しなかった代替案とその理由を聞きます。代替案ごとの長所と短所を具体的に説明できる場合は、トレードオフを比較して設計を判断してきたと考えられます。

隣接手法との違い

用語指すものデザインドキュメントとの違い
要件定義作るものが満たすべき条件を関係者から引き出し、文書にまとめる工程満たすべき条件を定める。デザインドキュメントは、どう作るかと判断の理由を書く
基本設計要件をもとに、画面・帳票・外部連携など利用者から見える仕様を決める工程仕様を確定させることが中心。デザインドキュメントは、採用しなかった案とその理由も記録する
コードレビュー書かれたコードの変更を他者が確認する工程実装後にコードを対象に行う。デザインドキュメントのレビューは、実装前に設計を対象に行う

出典