← レポート一覧
EFFECTIVE SOFTWARE DESIGN DOC / ELI5
ソフトウェア設計書に
何をどこまで書くか
設計書には、間違えたときに直すのが大変な決定を書きます。この記事は、書くかどうかの決め方と、書く項目を、キャッシュ層 RecencyBank の例で説明しています。
1 / どんな話
設計書は何のために書くのか
著者の Michael Lynch さんは、Google、Microsoft、自分の会社で設計書(design doc)を書いてきた人です。この記事では、設計書をいつ書くか、何を書くかを、項目ごとに例をつけて説明しています。
設計書を書くと、間違った実装に時間を使う前に、重要な決定を考え抜くことになります。チームメイトや他チームと設計の判断をすり合わせるのにも、いちばん良い手段だと著者は書いています。
著者はよく「良い設計書はどこで見られるか」と聞かれますが、公開されている良質な設計書は見たことがないそうです。そこで、実際に作っている Web アプリ「Little Moments」の設計書をコードを書く前にゼロから書いて公開し、その設計どおりに実装を進めています。
良い設計書は、何年分もの開発時間を節約できます。
ただし、何でも書けばよいわけではありません。書くかどうか、何を書くかの決め方を次の章から見ていきます。
2 / 書くかどうか
書くかどうかを 6 つの質問で決める
どんな仕事にも設計書が要るわけではありません。記事では次の 6 つの質問を挙げ、Yes の数で判断しています。
6
設計の時点で防げる致命的なリスク(セキュリティ、法務)があるか
どこまで書き込むかにも幅があります。1 ページで済むこともあれば、5 つのチームの承認が要る 50 ページになることもあります。
テストをどれだけ書くかに決まったルールがないのと同じで、チームの目標、リスク、締め切り、文化しだいです。記事には「ゼロが正解のときもある」とも書かれています。
3 / 何を書くか
書くのは、間違えたときの代償が大きい決定だけ
何もかも設計書に書くと、設計の段階で実装を書いているのと同じになり、設計書を作る意味がなくなります。そこで著者は「それを間違えたら、代償はどれくらいか」で書くかどうかを決めています。
代償が大きい → 設計書に書く
Web アプリを C++ で書く
20万行(200k lines)書いたあとで Ruby on Rails が正解だったと気づいても手遅れです。ゼロからの書き直しは無理で、書けたとしても、まったく違う 2 つの言語を保守し続けることになります。
代償が小さい → 書かない
100 件の記事を一度に出すか、25 件ずつ「Load more」で出すか
記事の答えは「どうでもいい(It doesn't matter.)」です。間違っていても数時間で直せるので、設計書で議論してレビューの回数を使うべきではありません。
迷ったら「間違えていたとき、直すのに数時間か、何年か」を考えます。
何年もかかりそうな決定を設計書に書き、数時間で直せることは書かずに進めます。
4 / 項目の全体像
23 の項目を 5 つのまとまりに分けて見る
記事では、設計書によく入れる項目が 23 個紹介されています。全部そろえる必要はなく、その設計書に必要なものを選びます。
一列に並べると覚えにくいので、このページでは流れに沿って表紙まわりと 5 つのまとまりに分けました。この分け方は記事の見出しではなく、このページで整理したものです。
0
表紙まわり
TitleMetadataRelated documentsGlossary
何のプロジェクトで、誰が書き、誰が承認したか。読むのに必要な関連文書と用語。
1
なぜやるのか
ObjectiveBackground
目的を 1 文で、背景を数字で伝えます。
2
どこへ行く・どこへは行かない
GoalsNon-goalsScenarios
完成したら誰にとって何が良くなるか、何はやらないか、実際にどう使われるか。
3
どう作るか
ConstraintsDiagramsInterfacesDependencies / infrastructureTimeline
前提になる制約、構成の図、つなぎ目の形、使う技術、いつ何ができあがるか。
4
どう守るか
SLOsMonitoring / alertingSecurityPrivacyLegal considerationsLogging
性能の目標、異常への気づき方、脅威・データ・法律の扱い、何をログに残すか。
5
迷っていること
Open issuesResolved issuesAlternatives considered
まだ決まっていないこと、決まったこと、選ばなかった案とその理由。
記事の例は、ほぼ一貫して同じプロジェクトです。Trogdor という Web アプリと Postgres データベースの間に、キャッシュ層 RecencyBank を入れます。
まずは、どの設計書にも付ける表紙まわりの 4 項目です。
Title
名前
会話で呼ばれる名前なので、短く、特徴的で、目的を思い出せるものにします。
良い例と悪い例良い例は「RecencyBank」。悪い例は「Project Flying Silver Horse」(長くて意味がわからない)。
Metadata
基本情報
著者(名前とメール)、作成日、正式な URL(go/ リンクなど)、誰がいつ承認したか。
RecencyBank の例Status: Approved / alan@ が 2026-07-14 に承認
Related documents
関連文書
テスト計画、関連システムの設計書、前のバージョンの設計書へのリンクを置きます。
Glossary
用語集
新しいメンバーや他チームが知らない社内ツール名などを定義します。いちばん良いのは、読者が知っている言葉を使うか、本文のその場で定義することです。読者を文書の中であちこち行き来させずに済みます。
例Apposaurus = 社内の負荷テストツール
5 / なぜ・どこへまとまり 1 なぜやるのかまとまり 2 どこへ行く・行かない
なぜやるのか、どこを目指して、どこは目指さないのか
最初のページで、目的と背景を伝えます。事前に説明を受けていない人が読んでも分かるように、必要なことはここにまとめます。
Objective
目的
プロジェクトの目的を 1 文で書きます。どの関係者にもわかる平易な言葉で、最初のページに置きます。
RecencyBank の例「Trogdor Web サーバーと Postgres の間にキャッシュ層を追加して、アプリの性能を改善する」
Background
背景
なぜやるのか、何の問題を解くのか、過去に試したことはあるか。
RecencyBank の例ローンチ時は 100ms 以下だったページ読み込みが、3 年後には中央値 600ms。くわしくは下の図。
背景の数字から、ゴールが決まります。Goals は実装の詳細ではなく、ユーザー・チーム・会社にとっての効果で書きます。
悪い例: 使う道具の話
「Kubernetes をインフラに入れる」
何を使うかは書いてありますが、それで誰が何を得るのかがわかりません。
良い例: 得られる効果の話
「新バージョンのデプロイに伴う障害を最小化する」
完成したあとに何が良くなるかがわかります。
Goals
ゴール
実装の詳細ではなく、完成したあとに誰にとって何が良くなるかを書きます。
RecencyBank の例ユーザー体感の応答性を上げる / DB サーバーの負荷を下げる
Non-goals
やらないこと
読者がスコープ内だと誤解しそうなものを、はっきり外しておきます。
RecencyBank の例汎用の再利用できるキャッシュシステムは作らない / 位置情報を考慮したキャッシュは v1 の対象外
Scenarios
使われる場面
完成したシステムが現実でどう使われるかを、場面として描きます。
記事の例(ここだけ RecencyBank ではない題材)Bob がダッシュボードでレポートを作る → 「Share > as URL」をクリック → Charlie にメールで送る → Charlie がリンクを開くと、同じレポートが読み取り専用で見える
6 / どう作るまとまり 3 どう作るか
どう作るのかを、図とつなぎ目で伝える
書き手の頭の中にはアーキテクチャの絵がありますが、レビュアーの頭の中にはありません。いちばん早く伝える方法は、図を描くことです。
記事の Interfaces の例を図にしたもの(記事内の図の画像ではありません)
いまの Server は PostgresDB 構造体に直接依存しています。同じメソッド(GetUser, ListUsers)を持つ Go の Store interface を作り、RecencyBank がそれを実装して Postgres を包みます。
Constraints
制約
予算、顧客、インフラ、依存先から来る大きな制約を書きます。
RecencyBank の例サーバーは全部 RISC-V なので、全コードと依存は RISC-V で動くこと
Diagrams
図
データの流れ、部品の組み合わせ、依存先やクライアントとのやりとり、通信プロトコルを描きます。ホワイトボードの写真は後から編集できないので避け、Excalidraw、draw.io、Google Drawings、または Mermaid、D2、Graphviz で描いて、元データへのリンクも付けます。
著者のメモLLM に図のコードを書かせるのも、良い経験があったそうです。
Interfaces
つなぎ目
GUI なら簡単なスケッチ(細かい UI の選択にはこだわらない)、ソフトウェアなら API や CLI の意味、ファイルなら形式を書きます。
RecencyBank の例Server の変更は db PostgresDB を db store.Store にするだけ(上の図)
Dependencies / infrastructure
依存・基盤
言語、動かす環境、永続データの置き場所を書きます。後から変えにくい言語やストレージは深く考え、午後だけで替えられるメール送信サービスのようなものはそれほど気にしません(3 章のものさしと同じ考え方です)。
RecencyBank の例言語は Go / KV ストアは bbolt
Timeline
スケジュール
ステークホルダーに役立つ成果物が出るところでマイルストーンを切ります。たとえば先にダミーデータの UI を見せれば、要件の誤解を、配管を作り込む前に見つけられます。
見積もりの方法著者のおすすめは Joel Spolsky「Painless Software Schedules」(25 年前の記事ですが、著者のお気に入り)
M1 2026-07-01
テスト環境で、ハードコードしたデータを使って動かす
M2 2026-07-17
テスト環境で、Postgres の実データをキャッシュする
M3 2026-08-03
テスト環境で、キャッシュ破棄のルールを入れる
7 / 守りまとまり 4 どう守るか
性能・監視・セキュリティ・法務の決めごと
「モバイルで速く」のような言い方は曖昧です。上司の考える「速い」は 2ms 未満かもしれません。性能は、測れる数字の目標(SLO)で書きます。
セキュリティでは、想定した脅威、攻撃面、信頼境界を書きます。脅威がなさそうに見えても理由を書いておくと、レビュアーが見落としに気づくきっかけになります。
SLOs
性能の目標
稼働率、レイテンシ、スケールを、測れる数字で書きます。SLA は SLO に金銭ペナルティを足したものですが、社内の同僚に罰金は科さないので、設計書では SLO を使います。
RecencyBank の例Trogdor のユーザー向け HTTP リクエストの p50 ≤ 200ms / Postgres クエリの p50 ≤ 80ms
Monitoring / alerting
監視とアラート
落ちたらどう気づくか、100 倍遅くなったらどう気づくか、ほかに何をアラートにするか。
RecencyBank の例Trogdor の p95 ≥ 3s、または Postgres の直近 2 分間の平均 CPU ≥ 90% でオンコールを呼ぶ
Security
セキュリティ
想定した脅威(全パスワードの総当たり、マルウェア入り PDF のアップロードなど)、攻撃面、信頼境界(ブラウザからのリクエストは境界をまたぐ)。
RecencyBank の例アクセス制御がないので、公開インターネットからは受けない。分離ネットワークで、Trogdor からの受信と Postgres への送信だけを許可(上の図)
Privacy
プライバシー
どんな機微データを扱うか、どれくらい保持するか、誰がアクセスできるか、どう守るか(保存時・通信時の暗号化など)。
RecencyBank の例Postgres と同じポリシーを引き継ぐ。本番に入れるのはバグ番号があるときだけで、見るデータも必要最小限にする
Legal considerations
法務
金融・医療などの規制分野か、それ以外でも違法になりうるケースはないか。OSS ライセンスの選択とその理由。
RecencyBank の例FizzleCorp との契約で生体データのコピー作成が制限されているが、キャッシュ層は契約上の「storage layer」に含まれると法務が確認した
Logging
ログ
重要なイベント、ログレベル、保存場所、保持期間、誰が見られるか、ログに出してはいけない機微データ。
RecencyBank の例初期化時のパラメータと RAM 容量 / メモリへの保存の失敗 / キャッシュ無効化の失敗
8 / 迷っていることまとまり 5 迷っていること
迷っていることと、選ばなかった案を書いておく
書いている途中で、設計の穴、情報の不足、複数の案で迷う点が出てきます。これは付録の Open issues に書き、決まったら Resolved issues に移します。
Open issues
未解決の課題
設計の穴、情報不足、複数案で迷っている点を付録にまとめます。各項目に「何が問題か」「解決の選択肢」「直近の次の一手」を書きます。
RecencyBank の例キャッシュに割り当てる RAM の量(上の付箋)
Resolved issues
解決済みの課題
解決したら決定を要約して Resolved に移し、議論は全文残します。
RecencyBank の例128GB に決定。性能目標に届かず RAM が足りなければ、その時点で足す
Alternatives considered
検討した代替案
「なぜ X にしなかったの?」と聞かれそうなものに先回りして答えます。却下した案を何時間もかけて細かく書く必要はなく、有力な案と却下理由が数行あれば足ります。
RecencyBank の例Google Cloud Firestore: 耐久性は魅力だったが、ロックインとローカルでのテストのしにくさで却下
9 / まとめ
自分の仕事で使うときのまとめ
この記事が扱うのは、設計書を書き終えるところまでです。書いたあとにチームへ共有してフィードバックを集め、揉め事や混乱で止まらずに進める方法は、別の記事「How to Get Meaningful Feedback on Your Design Document」で扱われています。
仕事が来たとき
6 つの質問に答えて、設計書を書くか、どのくらい書き込むかを決める
書き始めるとき
最初のページに Objective と Background を置く。Goals は効果の言葉で書き、誤解されそうなことは Non-goals で外す
議論が長引くとき
「間違えたら直すのにどれくらいかかるか」を考える。数時間で直せることなら、設計書で議論しなくてよい
決めきれないとき
Open issues に、問題・選択肢・次の一手を書いておく
お手本を見たいとき
著者が公開している Little Moments の設計書(下の出典にリンク)
1
6 つの質問のうち 1 つでも Yes なら、書く価値がありそう
複数人で作る、3 か月を超える、数年動く、チームをまたぐ、要件が曖昧、致命的なリスクがある。2 つ以上ならほぼ確実に書く価値があります。
2
書くのは、間違えると直すのが大変な決定
言語やストレージのように後から変えにくいものは書き、Load more ボタンのように数時間で直せるものは書きません。
3
項目は流れに沿って、必要なものだけ選ぶ
なぜ → どこへ行く・行かない → どう作る → 守り → 迷っていること。23 項目を全部そろえる必要はありません。
出典
補足: 上の 3 つの関連リンクの URL は、元記事の HTML にあるリンクから確認しました。23 項目という数は元記事の項目一覧を数えたもので、5 つのまとまりへの分け方はこのページで整理したものです。元記事内の動画と、アーキテクチャ図の例の画像は確認できていません。6 章と 7 章の図は、記事の文章の例をもとにこのページで描いたものです。
用語メモ / 設計書(design doc)= 実装の前に、何をどう作るかを書いてチームで合意するための文書。ステークホルダー= プロジェクトに関わる人や部署。SLO= 守ると決めた品質の目標値。SLA= SLO に、守れなかったときの金銭ペナルティを加えた契約。p50 / p95= 応答時間を速い順に並べて 50% / 95% の位置の値(p50 は中央値)。オンコール= 障害時にすぐ対応できるよう待機する当番。攻撃面= 悪意あるデータを受け取りうる場所。信頼境界= 信頼度の低いところから高いところへデータが渡る境目。KV ストア= キーと値の組でデータを保存する仕組み。人日= 1 人が 1 日でこなす作業量の単位。go/ リンク= 社内向けの短縮 URL。
← レポート一覧