効果的なソフトウェア設計ドキュメントの書き方

優れた設計ドキュメントは、何年もの開発時間を節約できます。設計ドキュメントを書くことで、間違った実装に時間を浪費する前に、重要な決定事項を十分に検討することができます。また、チームメートやパートナーチーム間で設計上の決定を調整する最良の方法でもあります。 私はGoogle、Microsoft、そして自身の会社で開発者として設計ドキュメントを書いてきました。具体的な内容は異なりますが、基本的な原則は同じです。設計ドキュメントは、あなたが解決しようとしている困難な問題を明確にし、チームメートがフィードバックを提供するのに役立ちます。 以下に、効果的な設計ドキュメントを作成するための私の方法を共有し、設計ドキュメントに何を含めるべきか、そして何を含めるべきでないかを説明します。 例：設計ドキュメント いつ設計ドキュメントを書くべきか？ 設計ドキュメントにどれだけ投資すべきか？ 設計ドキュメントに何を含めるべきか？ 間違った場合のコストは？ 設計ドキュメントの構成要素 タイトル メタデータ 目的 背景 関連ドキュメント 目標 目標外のこと シナリオ 図 用語集 制約 サービスレベル目標（SLO） 監視/アラート タイムライン インターフェース 依存関係/インフラストラクチャ セキュリティ プライバシー 法的考慮事項 ロギング 未解決の問題 解決済みの問題 検討された代替案 レビューを通じて設計ドキュメントを推進する 例：設計ドキュメント🔗 設計ドキュメントに関して最もよく受ける質問は、良い例を見つける場所です。私は、質の高いと考える公開された設計ドキュメントを見たことがありません。私のものはすべて、それらを書いてくれた会社に隠されています。 そこで、ここで共有する原則に基づいて、ゼロから設計ドキュメントを作成しました。これは、私が構築している実際のWebアプリの設計を示しています。お使いのブラウザはvideoタグをサポートしていません。 私はコードを書く前に設計ドキュメントを作成し、アプリを実装する際にその設計に従っています。 Little Moments Design Doc この設計は、私が通常ソロの趣味プロジェクトのために書くものよりも網羅的ですが、これは、プロのプロジェクトで他の人と協力する場合に作成する設計ドキュメントの長さと深さに大まかに相当します。 いつ設計ドキュメントを書くべきか？🔗 プロジェクトが複雑またはリスクが高いほど、設計ドキュメントを書く価値は高まります。 これらの質問を検討してください。 設計を実装するために複数の人が作業を調整しますか？ プロジェクトは3ヶ月以上のフルタイムの開発作業を要しますか？ 実装は数年間本番環境で実行されますか？ プロジェクトにはチーム間の協力が含まれますか？ プロジェクトの目標と要件は曖昧ですか？ 設計段階で防止できる壊滅的なリスク（例：セキュリティ上の欠陥、法的リスク）はありますか？ これらの質問のいずれかに「はい」と答えた場合、設計ドキュメントを書く労力はそれに見合う可能性が高いです。2つ以上に「はい」と答えた場合、設計ドキュメントはほぼ間違いなく労力に見合うでしょう。 設計ドキュメントにどれだけ投資すべきか？🔗 設計ドキュメントは、シンプルな1ページのものから、5つの異なるチームからの承認が必要な50ページのドキュメントまで様々です。どの程度の詳細が適切かを決定する必要があります。 コードのテストにどれだけ時間をかけるべきかというルールがないのと同じように、設計ドキュメントにどれだけ時間を費やすべきかという普遍的なルールはありません。適切な投資は、チームの目標、リスク、締め切り、文化によって異なります。場合によっては、設計ドキュメントへの適切な投資はゼロです。 設計ドキュメントに何を含めるべきか？🔗 設計ドキュメントですべての可能な詳細を指定すると、設計段階で実装を実質的に書き終えたことになります。それは設計ドキュメントの目的全体を損なうことになります。 経験則として、決定が設計ドキュメントに属するかどうかを判断するために簡単な質問をすることができます。それは、間違っていた場合のペナルティは何か？ということです。 間違った場合のコストは？🔗 すべての設計上の決定が等しく重要であるわけではありません。一部の選択は他の選択よりも永続的です。 たとえば、C++でWebアプリケーションを構築し、20万行後にRuby on Railsの方が良い選択だったことに気づいたとします。ゼロからの書き直しは決してうまくいかず、Railsで新しいコードを書くことができたとしても、あなたは依然として2つの全く異なる言語でコードを維持することになります。 他の設計上の決定は些細なものです。たとえば、あなたのアプリが100件の記事のリストを表示するとします。それらはすべて一度に表示されるべきですか？それとも、ユーザーは25件ずつ表示し、「さらに読み込む」をクリックして次の25件を表示すべきですか？ それは重要ではありません。 「さらに読み込む」ボタンは設計レベルの懸念事項ではありません。1つのソリューションを選択し、ユーザーフィードバックがあなたが間違っていると伝えてきた場合、数時間で修正できます。あなたは設計ドキュメントにあなたの思考プロセス全体を詳細に記述する必要はありませんし、間違いなくそれについてレビューサイクルを無駄にすべきではありません。 設計ドキュメントの構成要素🔗 以下に、設計ドキュメントに含める一般的なセクションを記載しました。通常、すべてのドキュメントにすべてのセクションが必要なわけではありません。あなたにとって意味のあるサブセットを選択してください。 タイトル🔗 プロジェクトに必要な最初のものはタイトルです。それは人々が会話の中でプロジェクトを参照する方法なので、短く、特徴的で、示唆に富むものにすることを目指してください。 たとえば、アプリケーションサーバーとデータベースサーバーの間にキャッシュレイヤーを追加する場合、RecencyBankは良い名前でしょう。言いやすく、プロジェクトの目的を説明しています。悪い名前は「Project Flying Silver Horse」でしょう。なぜなら、それは冗長で無意味だからです。 メタデータ🔗 退屈ですが有用なメタデータは、読者がドキュメントの基本的なコンテキストを理解するのに役立ちます。 作成者は誰か？（名前+メールアドレス） ドキュメントはいつ作成されたか？ 権威あるURLは？ 特に、組織がhttp://go/recency-bankのようなショートリンクリダイレクトを使用している場合。 誰がこのドキュメントを承認し、いつ承認したか？ ドキュメントがチームメートやパートナーからの承認を必要とする場合。 メタデータ URL: http://go/recency-bank-design 作成者: Michael Lynch (michael@refactoringenglish.com) 作成日: 2026-06-22 ステータス: 承認済み alan@ が承認、2026-07-14 betty@ が承認、2026-07-15 目的🔗 目的は、プロジェクトの目的を1文で説明したものです。ステークホルダーなら誰でも理解できる平易な言葉で、ドキュメントの最初のページに表示されるべきです。 目的 Trogdor WebサーバーとPostgresデータベースの間にキャッシュレイヤーを追加することにより、アプリケーションのパフォーマンスを向上させる。 背景🔗 背景セクションは、プロジェクトのコンテキストと動機を説明します。これらの質問に答えるべきです。 なぜチームはこのプロジェクトに取り組んでいるのか？ このプロジェクトはどのような問題を解決するのか？ 以前にこの問題を解決しようとした試みはあったか？ 背景 2023年にTrogdor Webアプリをローンチしたとき、ページの読み込み時間は通常100ミリ秒以下でした。3年後、中央値のページ読み込み時間は600ミリ秒に膨れ上がり、ユーザーは私たちのアプリを遅いと感じるようになりました。 私たちは遅延の原因を調査し、データベースのルックアップがページ読み込み時間の80％を占めていることを発見しました。データストアが大きくなるにつれて、データベースのルックアップは遅くなりました。 また、データベースのルックアップの95％が、データベース行の3％に集中していることも発見しました。この使用パターンは、メモリベースのキャッシュから大きな恩恵を受けます。キャッシュは頻繁にアクセスされるデータをより速く提供し、他のすべてのクエリのデータベース負荷を軽減します。 あなたの設計ドキュメントは、外部のコンテキストなしで意味をなしますか？ 設計ドキュメントを読む前に、チームメートやパートナーチームに何を言うか想像してみてください。 そして、ドキュメントを読む前にあなたからの説明を一切聞かない読者もいることを理解してください。したがって、彼らが理解する必要があるものはすべて、ドキュメントの最初のページにあるべきです。 関連ドキュメント🔗 このプロジェクトが他のドキュメントに接続されている場合は、読者がそれらを見つけやすくしてください。 以下へのリンクを含めてください。 このプロジェクトに関するプログラムマネージャーやテスト担当者からのドキュメント（例：テスト計画、機能仕様） 関連システムの設計ドキュメント このプロジェクトの以前のイテレーションの設計ドキュメント 関連ドキュメント テスト計画: http://go/recency-bank-test-plan Trogdorパフォーマンスレポート: http://go/trogdor-perf-2026 目標🔗 目標セクションは、このプロジェクトのハイレベルな目標を説明します。背景セクションと論理的に結びつき、実装が完了した後の状況を説明するべきです。 実装の詳細の観点から目標を設定することは避けてください。目標は、プロジェクトがユーザー、チーム、または会社にどのように利益をもたらすかを伝えるべきです。 悪い例: インターンに関する目標を設定する