Web開発

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

How to Write an Effective Software Design Document (refactoringenglish.com)

243 pointsby fagnerbrack2026年9月14日105 コメント

要約

効果的な設計ドキュメントは、開発時間を大幅に節約し、チーム間の意思決定の連携を促進します。この記事では、設計ドキュメントの目的、いつ書くべきか、どの程度の詳細を含めるべきか、そして設計ドキュメントの主要な構成要素について解説しています。特に、設計上の決定が間違っていた場合のコストを考慮して、ドキュメントに含めるべき内容を判断する基準が示されています。

全文翻訳

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

優れた設計ドキュメントは、数年分の開発時間を節約できます。設計ドキュメントを作成することで、間違った実装に時間を浪費する前に、重要な決定について深く考えることができます。また、チームメイトやパートナーチーム間で設計上の決定を調整する最良の方法でもあります。

私はGoogle、Microsoft、そして自身の会社で開発者として設計ドキュメントを書いてきました。具体的な内容は異なりますが、基本的な原則は同じです。設計ドキュメントは、解決しようとしている困難な問題を明確にし、チームメイトがフィードバックを提供するのに役立ちます。

以下に、効果的な設計ドキュメントを作成するための私のアプローチと、設計ドキュメントに含めるべきもの、含めるべきでないものを説明します。

設計ドキュメントの例🔗

設計ドキュメントに関して最もよく受ける質問は、良い例を見つけるにはどうすればよいかということです。私は、質の高いと考える公開されている設計ドキュメントを見たことがありません。私のものはすべて、作成のために報酬を支払ってくれた企業の中に隠されています。

そこで、ここで共有している原則に基づいて、ゼロから設計ドキュメントを作成しました。これは、私が構築している実際のWebアプリの設計をまとめたものです。

［動画: Your browser does not support the video tag.］

私はコードを書く前に設計ドキュメントを作成し、アプリを実装する際にその設計に従っています。

Little Moments 設計ドキュメント

この設計は、私が通常ソロの趣味プロジェクトのために書くものよりも網羅的ですが、これはプロフェッショナルなプロジェクトで他の人と協力する際に作成する設計ドキュメントの長さと深さにほぼ相当します。

いつ設計ドキュメントを書くべきか？🔗

プロジェクトが複雑またはリスクが高いほど、設計ドキュメントを書く価値は高まります。

以下の質問を検討してください。

設計の実装のために複数の人が協力する必要がありますか？
プロジェクトは3ヶ月以上のフルタイムの開発作業を要しますか？
実装は数年間本番環境で稼働しますか？
プロジェクトにはチーム間の協力が含まれますか？
プロジェクトの目標と要件は曖昧ですか？
設計段階で防止できる壊滅的なリスク（例: セキュリティ上の欠陥、法的リスク）はありますか？

これらの質問のいずれかに「はい」と答えた場合、設計ドキュメントを作成する労力に見合う価値がある可能性が高いです。2つ以上に「はい」と答えた場合は、設計ドキュメントはほぼ間違いなく労力に見合う価値があります。

設計ドキュメントにどれだけ投資すべきか？🔗

設計ドキュメントは、シンプルな1ページのものから、5つの異なるチームからの承認が必要な50ページのドキュメントまで様々です。どの程度の詳細さが必要かを決定する必要があります。

コードのテストにどれだけ時間をかけるかというルールがないのと同じように、設計ドキュメントにどれだけ時間を費やすべきかという普遍的なルールはありません。適切な投資は、チームの目標、リスク、締め切り、文化によって異なります。時には、設計ドキュメントへの適切な投資はゼロであることもあります。

設計ドキュメントに含めるべきものとは？🔗

設計ドキュメントで可能な限りの詳細を指定すると、設計段階で実装をほぼ完了したことになります。それは設計ドキュメントの目的全体を損なうことになります。

経験則として、決定が設計ドキュメントに含めるべきかどうかを判断するために、簡単な質問をすることができます。それは、「間違った場合のペナルティは何か？」ということです。

間違った決定をするコストは？🔗

すべての設計上の決定が同じように重要であるわけではありません。一部の選択は、他の選択よりも永続的です。

例えば、C++でWebアプリケーションを構築し、20万行のコードを書いた後にRuby on Railsの方が良い選択だったと気づいた場合、あなたは立ち往生します。ゼロから書き直すことは決してうまくいきませんし、Railsで新しいコードを書くことができたとしても、あなたは依然として全く異なる2つの言語でコードを保守することになります。

他の設計上の決定は些細なものです。例えば、あなたのアプリが100件の記事のリストを表示するとします。それらはすべて一度に表示されるべきでしょうか？それとも、ユーザーは一度に25件ずつ表示し、「さらに読み込む」をクリックして次の25件を表示すべきでしょうか？

どちらでも構いません。

「さらに読み込む」ボタンは設計レベルの懸念事項ではありません。一方のソリューションを選択し、ユーザーからのフィードバックでそれが間違っているとわかった場合、数時間で修正できます。設計ドキュメントにあなたの思考プロセス全体を詳細に記述する必要はありませんし、それについて議論してレビューサイクルを無駄にすべきではありません。

設計ドキュメントの構成要素🔗

以下に、設計ドキュメントに含める一般的なセクションを挙げました。通常、すべてのドキュメントにすべてのセクションが必要なわけではありません。あなたにとって意味のあるサブセットを選択してください。

タイトル🔗

プロジェクトに必要な最初のものはタイトルです。それは人々が会話の中であなたのプロジェクトを参照する方法なので、短く、特徴的で、示唆に富むものにすることを目指してください。

例えば、アプリケーションサーバーとデータベースサーバーの間にキャッシュ層を追加する場合、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

目標🔗

目標セクションは、このプロジェクトに対する高レベルの目標を説明します。背景セクションと論理的に繋がり、実装が完了した後の世界の様子を説明する必要があります。

実装の詳細で目標を設定することは避けてください。目標は、プロジェクトがユーザー、チーム、または会社にどのように利益をもたらすかを伝えるべきです。

Kubernetes をインフラストラクチャに追加する。
新しいアプリバージョンをデプロイすることに関連する障害を最小限に抑える。

目標

Trogdor Webアプリのユーザー体感応答性を向上させる。

データベースサーバーの負荷を軽減する。

目標外のこと🔗

目標がプロジェクトの範囲内にあるものを定義する一方で、目標外のことセクションは範囲外にあるものを明確にします。

読者が誤ってあなたのプロジェクトの範囲内にあると仮定する可能性のある目標はありますか？もしあれば、それらを明示的な目標外のこととして追加してください。

目標外のこと

汎用的で再利用可能なキャッシュシステムを作成する

Trogdor Webアプリに追加するキャッシュ層は、アプリケーション固有の最適化を行います。このキャッシュを他のシステムで再利用することは範囲外です。

位置情報に基づいたキャッシュ

エンドユーザーの地理的に近い場所にキャッシュを配置することは、将来的にレイテンシを削減するために役立つかもしれませんが、v1の範囲外です。

シナリオ🔗

あなたの目標が「チャートに『URLとして共有』ボタンを追加する」のようなものである場合、読者はそれが実際にはどのように見えるかを理解できないかもしれません。

シナリオセクションでは、完成したシステムが現実世界でどのように機能するかを読者にイメージさせることができます。

シナリオ: レポートをURL経由で共有する

Bob は KeyMetrics ダッシュボードでカスタムレポートを作成します。

Bob はメニューバーに移動し、「共有 > URLとして」をクリックします。

Bob はそのURLを同僚の Charlie にメールで送信します。

Charlie はリンクをクリックし、読み取り専用モードで Bob のレポートの正確なコピーを表示します。

図🔗

図は非常に価値がありますが、そう見えないかもしれません。

設計の作成者であるあなたは、計画の各部分がどのように組み合わさるかを直感的に理解しています。あなたは頭の中にアーキテクチャを見ることができます。レビューアはこれらのメンタルピクチャーを持っていないため、それを見せる最も速い方法は、彼らのために絵を描くことです。

［画像: アーキテクチャ図］

シンプルなWebアプリケーションのアーキテクチャを示す図の例。

図に何を含めるべきかわからない場合は、これらの質問を考えてみてください。

データはシステム内をどのように流れますか？
システムの異なるコンポーネントはどのように組み合わさりますか？
システムは、その依存関係や下流のクライアントとどのように相互作用しますか？
システムはどのような通信プロトコルを定義しますか？

編集しやすい図作成ツールを選択してください。私は、開発者がホワイトボードで美しい図を作成し、それを設計ドキュメントのために写真に撮るのを見てきました。最初のドラフトは素晴らしく見えますが、全体を最初から再作成せずに写真を編集できないため、その図に永遠に縛られてしまいます。

Excalidraw、draw.io、Google Drawings は、改訂を容易にする人気の図作成ツールです。Mermaid、D2、Graphviz のような言語もあり、プログラムで図を生成できます。私はLLMを使って図作成コードを生成してもらった経験があります。チームメイトが図を再現できるように、ソース描画またはコードへのリンクを忘れないでください。

用語集🔗

用語集は、読者が認識しない可能性のある用語を定義します。

ドキュメントの潜在的な読者、特に新しいチームメンバーやあなたの直接のチーム外の人々についてよく考えてください。それらの読者は、ドキュメントが参照する内部ツールやシステムの名前を理解できるでしょうか？

可能な場合は、用語集を参照する必要なく、読者が認識できる用語を使用してください。用語を用語集で定義することは、定義しないよりは良いですが、最善の解決策は、読者がドキュメント内を移動する必要がないように、認識可能な用語を使用するか、インラインで定義することです。

用語集

Apposaurus: チームの内部負荷テストツールです。Apposaurus を使用して、Trogdor Webアプリへの訪問者の急増をシミュレートし、期待されるワークロード下でアプリが機能し続けることを確認します。

Baba-o-styley: 会社のコードスタイル規約を強制する内部コードリンターです。

制約条件🔗

予算、クライアント、インフラストラクチャ、または依存関係によって設計に課せられる重大な制約がある場合は、読者が設計上の選択のコンテキストを理解できるように、それらの制約を説明してください。

制約条件

私たちのサーバーはすべてRISC-Vなので、すべてのコードと依存関係はRISC-Vアーキテクチャで実行される必要があります。

サービスレベル目標 (SLOs)🔗

SLOは、システムのパフォーマンスに関する測定可能で客観的なメトリックを作成します。サービスレベルアグリーメント（SLA）を聞いたことがあるかもしれません。SLAは、目標未達に対する金銭的ペナルティを加えたSLOにすぎません。

企業内では、通常、同僚に間違いに対して金銭的な罰則を科すことはありません（とはいえ、それは少し楽しいのではないでしょうか？）。そのため、設計ドキュメントではSLAではなくSLOを定義します。

あなたのマネージャーは、あなたのアプリは「モバイルでパフォーマンスが良い」必要があると言うかもしれませんが、それは曖昧です。あなたのマネージャーの「パフォーマンスが良い」という考えは2ミリ秒未満のレイテンシかもしれませんが、コードが完成するまで待ってからそれを知るのは避けたいことです。明確に定義されたSLOは、目標を具体的で客観的な用語で表現することによって曖昧さを防ぎます。

あなたのSLOの典型的な考慮事項は次のとおりです。

アップタイム/可用性: システムはどのくらいの割合の時間利用可能になりますか？
レイテンシ: サービスはリクエストをどれだけ速く完了しますか？
スケール: システムはどのくらいの量の作業を処理できますか？

サービスレベル目標

Trogdorのユーザー向けHTTPリクエストの50パーセンタイルレイテンシ: <=200ms

Postgresのクエリレイテンシの50パーセンタイル: <= 80ms

監視/アラート🔗

SLOを確定したら（上記）、本番環境でそれらをどのように測定するかを考える時です。

SLOを達成したことを確認する最も簡単な方法は、手動でテストすることです。組織が成熟するにつれて、SLOの失敗を即座に発見するために監視を自動化する必要があります。

監視戦略を定義する際には、これらの質問を自問してください。

サービスがダウンした場合、どのようにしてそれを知ることができますか？
サービスのパフォーマンスが100倍遅くなった場合、どのようにしてそれを知ることができますか？
どのような他のイベントがアラートをトリガーすべきですか？
- 例: CPU使用率の急増、認証失敗、システムエラー

監視

以下のイベントは、オンコールエンジニアへのページをトリガーします。

Trogdorのユーザー向けHTTPリクエストの95パーセンタイルレイテンシ: >= 3s

Postgresサーバーの平均CPU使用率（直近2分間）: >= 90%

タイムライン🔗

タイムラインセクションは、プロジェクトをマイルストーンに分割します。プロジェクトのステークホルダーにいつ結果を届けるかを指定します。

有用な成果物を作成するマイルストーンを選択してください。例えば、ダミーデータが表示されるUIから始め、まずクライアントにそれを見せます。クライアントの要件を誤解していたことが判明した場合、ダミーデータは、UIに本番データを入力するためのすべての配管を実装した後ではなく、早期にそれを発見させてくれます。

プロジェクトのタイムラインを推定する方法がわからない場合は、Joel Spolsky の「Painless Software Schedules」を強くお勧めします。この記事は25年前のものですが、私の好きなソフトウェア見積もり戦略であり続けています。

タイムライン

マイルストーン1 (2026-07-01): RecencyBank は、ハードコードされたキャッシュデータの一部（Postgres から読み込まない）でテスト環境で稼働します。

マイルストーン2 (2026-07-17): RecencyBank はテスト環境で稼働し、Postgres から実際のデータをキャッシュします。

マイルストーン3 (2026-08-03): RecencyBank はテスト環境で稼働し、キャッシュの無効化とライフサイクルルールを適用します。

マイルストーン4 (2026-08-22): RecencyBank は完全に実装され、本番環境にデプロイされます。

インターフェース🔗

あなたのプロジェクトは、人々や他のソフトウェアシステムにサービスを提供するために存在します。それらのやり取りはどのようなものですか？

グラフィカルシステムの場合、ユーザーインターフェースは何ですか？
- 単純なスケッチで十分です。正確なUIの選択にこだわりすぎないでください。
ソフトウェアインターフェースの場合、APIまたはCLIのセマンティクスは何ですか？
ファイルベースのインターフェースの場合、ファイル形式は何ですか？

インターフェース

Trogdor の Server 構造体は現在、PostgresDB Go struct に直接依存しています。
type Server struct { db PostgresDB }
PostgresDB は以下の公開メソッドを持っています。
GetUser(id UserID) (User, error)
ListUsers() ([]User, error)
...
私たちは、PostgresDB と同じAPIサーフェスを持つGoのinterface型を作成します。
type Store interface {
  GetUser(id UserID) (User, error)
  ListUsers() ([]User, error)
}
私たちは、同じinterfaceを実装し、バックエンドのPostgresDB構造体をラップするRecencyBankキャッシュ型を実装します。RecencyBankの実装は、Postgresからの読み込みをキャッシュし、状態を変更するリクエストやキャッシュに含まれていないデータに依存するリクエストをPostgresに転送します。

Serverの実装への唯一の変更は、1つのメンバーの型を新しいinterfaceに置き換えることです。
type Server struct { db store.Store }

依存関係/インフラストラクチャ🔗

依存関係セクションは、次のような質問に答える必要があります。

どのプログラミング言語を使用しますか？
コードはどのハードウェアまたはサービスで実行されますか？
永続データはどこに保存されますか？

このセクションを見落としがちですが、言語、ライブラリ、インフラストラクチャに関する決定は、システムの複雑さと長期的な保守コストに大きな影響を与えます。

実装後に変更が困難になる可能性のある依存関係について深く考えてください。簡単に交換できるものについては、それほど心配しないでください。言語やストレージバックエンドを変更するのは困難ですが、メールを送信するために使用しているサードパーティサービスに不満がある場合は、午後に交換できます。

依存関係

言語: Go

私たちはすでにGoを広く使用しており、高並列ワークフローの提供に適した言語です。

サードパーティパッケージ

bbolt: これは広く使用されているキーバリューストアの実装であり、RecencyBankに必要な機能の多くを実装しています。

セキュリティ🔗

安全なソフトウェアを構築するために、開発者はソフトウェアライフサイクルの全体にセキュリティを統合する必要があります。設計段階から始めるのです。

セキュリティセクションは、次のような質問に答える必要があります。

どのような脅威を考慮しましたか？
- 例: 攻撃者が考えられるすべてのパスワードを試した場合どうなりますか？ユーザーがマルウェアに感染したPDFをアップロードした場合どうなりますか？
このシステムの攻撃対象領域は何ですか？
- つまり、潜在的に悪意のあるデータをどこで処理しますか？
信頼境界はどこですか？
- データは、特権の低いシステムから特権の高いシステムへどの時点で流れますか？
- 例: Webアプリでは、ユーザーのブラウザからのリクエストは信頼境界を越えます。Webサーバーはブラウザからの入力を安全だと仮定すべきではありません。

あなたのシステムではセキュリティ上の脅威は可能性が低い、または無関係だと考えている場合でも、その根拠を文書化することは役立ちます。あなたの説明は、レビューアがあなたが見落とした脅威を特定するきっかけになるかもしれません。

セキュリティ

RecencyBank は、アクセス制御を一切強制しないため、パブリックインターネットからの直接のリクエストを受け付けてはなりません。

RecencyBank は、Trogdor Webサーバーからのインバウンドリクエストのみを受け入れ、Postgres サーバープールへのアウトバウンドリクエストのみを行うことができる、分離されたネットワーク上で実行されます。

プライバシー🔗

プライバシーセクションは、システムが扱う機密データを検討し、それを保護するためにどのような安全策を講じるかを考える機会です。以下の質問に答える必要があります。

システムはどのような機密データを扱いますか？
どのくらいの期間保持しますか？
誰がそれにアクセスできますか？
どのように保護しますか？
- 例: データは保存時および転送時に暗号化されますか？

プライバシー

RecencyBank は、Postgres データベースと同じ機密ユーザーデータを含んでいるため、Postgres システムのプライバシーポリシーを継承します。特に、エンジニアはバグ番号に関連付けられた場合にのみ、本番環境の RecencyBank システムにアクセスできます。エンジニアは、バグの調査に厳密に必要なユーザーデータのみにアクセスを限定する必要があります。

法的考慮事項🔗

あなたのシステムが金融やヘルスケアのような高度に規制されたドメインで運用されている場合、法的セクションは関連法規を遵守するのに役立ちます。

規制ドメイン外であっても、物事がうまくいかなかった場合にシステムが法律に違反する可能性があるかどうかを考えてください。会社やクライアントをリスクにさらす可能性のある法的違反をどのように回避するかを説明してください。

オープンソースライセンスの下でコードを公開している場合は、どのライセンスを選択したかとその理由を定義してください。

FizzleCorp 契約遵守

FizzleCorp との契約は、彼らの専有的な FizzlePerfect™ ユーザー生体認証データの新しいコピーを作成する能力を厳しく制限しています。

幸いなことに、私たちの法務チームは契約の文言をレビューし、キャッシュ層は既存の「ストレージ層」の定義に適合するため、契約の再交渉なしに RecencyBank 内で FizzlePerfect™ データをキャッシュできることを確認しました。

ロギング🔗

ログは、バグ、パフォーマンスの問題、またはセキュリティインシデントを調査する際に非常に役立ちます。効果的なロギングのために設計すると、システムの長期的な保守が容易になります。

ロギングについて考える際には、これらの質問を検討してください。

サービスはどのような重要なイベントをログに記録しますか？
異なるログレベルはありますか？
- 例: 情報、警告、エラー、クリティカル
システムはどこにログを保存しますか？
ログをどのくらいの期間保持しますか？
誰がログにアクセスできますか？
ログから除外する必要がある機密データはありますか？

ロギング

RecencyBank は以下のイベントをログに記録します。

初期化時に、RecencyBank を初期化するために使用されたパラメータ、およびホスト上の RAM 容量と使用状況をログに記録します。

メモリへの値の永続化に失敗した場合。

キャッシュの無効化に失敗した場合。

未解決の課題🔗

設計ドキュメントを作成する過程で、おそらく次のいずれかの状況に少なくとも1つ遭遇するでしょう。

設計に欠陥があるが、それをどう解決するか確信が持てない。
設計にギャップがあるが、それを埋めるためにもっと情報を収集する必要がある。
複数の解決策の間で迷っている。

設計ドキュメントに「未解決の課題」という付録を作成し、未解決の課題を文書化してください。

未解決の課題セクションの各エントリは、以下を説明する必要があります。

追加作業が必要な問題は何ですか？
問題を解決するための選択肢は何ですか？
問題を解決するための直接的な次のステップは何ですか？

レビュー段階で未解決の課題を管理する方法については、私のコンパニオン投稿を参照してください。

未解決の課題: キャッシュのRAMサイズ選択

キャッシュ層に割り当てるRAMの量を決定する必要があります。RAMの追加はパフォーマンスを向上させますが、RAMは高価であり、追加のRAMには収穫逓減があります。

キャッシュシステムとデータベースの間でインフラストラクチャコストを最小化する最適なRAM量が存在する可能性があります。理論的には、テスト環境をセットアップして複数のシミュレーションを実行することでその最適な値を発見できますが、それらのシミュレーションを実行するには開発時間が必要です。

テスト環境を作成し、単一のシミュレーションを実行するコストは、3.0開発日と見積もっています。インフラストラクチャが整えば、追加のシミュレーションはそれぞれ約0.75開発日で済みます。

提案される解決策: テストなしで128 GBのRAMを選択します。おそらく最適値に近いでしょうし、開発時間はRAMのコストよりも大幅に高価です。

次のステップ: テックリードに意見を求めます。

解決済みの課題🔗

未解決の課題を解決したら、決定を要約し、設計ドキュメントの「未解決の課題」セクションから「解決済みの課題」セクションに移動します。後世のために完全な議論を保持してください。

解決済みの課題: キャッシュのRAMサイズ選択

決定: キャッシュ層に128 GBのRAMをプロビジョニングします。パフォーマンス目標を達成できず、RAMが不足している場合は、その時点でRAMを追加できます。最適なRAMサイズを見つけるためのテストを実行する開発コストは、追加のRAMコストをはるかに上回ります。

私たちは決定する必要があります… [元の未解決の課題の残りの部分がここにあります]

検討された代替案🔗

読者から「なぜXをしなかったのですか？」と尋ねられると予想される場合は、「検討された代替案」セクションで事前に答えるのが役立ちます。このセクションは、特に魅力的に見えたり、広範囲に調査したりした場合に、却下したオプションを説明する場所でもあります。

私は、拒否された設計アイデアをすべて細心の注意を払って文書化するのに何時間も費やす開発者を知っていますが、それはやりすぎだと思います。読者としても作成者としても、代替案セクションで必要なのは、強力な代替案を簡潔に説明し、それがなぜうまくいかなかったかを説明することだけです。

検討された代替案

Google Cloud Firestore (永続ストレージ)

耐久性と信頼性は魅力的でしたが、プラットフォームのロックインとローカルでのテストの難しさが気に入らなかったです。

設計ドキュメントのレビューを通じた推進🔗

設計ドキュメントが完成したら、次のステップはチームと共有し、フィードバックを収集することです。

次のセクションでは、プロジェクトを停滞させるのではなく前進させるような、有益な設計フィードバックを引き出すためのテクニックをカバーしています。

設計ドキュメントから有益なフィードバックを得る方法