--- title: "デザインドック（Design Doc）とは？書き方とテンプレート、書くべき場面とAIでの下書き" url: "https://www.issoh.co.jp/tech/details/8800/" published: 2025-09-11 updated: 2026-10-20 categories: ["開発"] publisher: "株式会社一創" --- # デザインドック（Design Doc）とは？書き方とテンプレート、書くべき場面とAIでの下書き **デザインドック（Design Doc、デザインドキュメント）**とは、コーディングを始める前に「このシステムをなぜ・どう作るのか」を書き出し、設計の意図と決定の根拠をチームで共有するための文書です。ここでの「デザイン」は画面の見た目ではなく**ソフトウェアの設計**を指します。仕様書のように「何を作るか」を細かく列挙するのではなく、採用した設計と、検討して捨てた代替案・トレードオフを残すことに重きを置きます。この記事では、定義と設計書・ADRとの違い、書く価値があるかを判定する問い、コピーして使えるテンプレート、レビューの回し方と承認後の扱い、生成AIでの下書きまでを順に扱います。 ## まとめ：デザインドックは代替案とトレードオフを実装前に残す設計文書 - **核心は「検討した代替案とトレードオフ」の記録**。代替案が書かれていない文書は、Design Docではなく実装マニュアルです。 - **仕様書・設計書との違いは問いの違い**。仕様書は「何を作るか」、Design Docは「どう作り、なぜそう決めたか」を扱います。1つの決定だけなら[ADR（アーキテクチャ決定記録）](/tech/details/9198/)で足ります。 - **書くかどうかは5つの問いで決める**。Design Docs at Googleは、設計への確信のなさ・合意の必要・横断的な懸念の見落としなど5つの問いのうち3つ以上に当てはまれば書く価値が高いとしています。 - **テンプレートは背景と範囲・目標と非目標・設計・代替案・横断的な懸念が骨組み**。本文に通常版と1〜3ページのmini版を載せました。 - **承認後の扱いは2流儀**。出荷前なら更新し続けるGoogle流と、開発開始後は更新せずArchiveにするメルカリShops流があり、どちらかを最初に決めておきます。 - **生成AIは下書きと一次レビューに使い、設計判断は人が持つ**。足りない前提を質問で返させ、出力に根拠のない補完が残っていないか人が確認します。 以下、定義から順に、書き方・レビュー・運用の判断まで具体的に見ていきます。 ## デザインドック（Design Doc）とは何か：定義と目的、設計書との違い ### Design Docの定義と、Malte Ublの公開記事が挙げる6つの役割 Design Docは、実装に着手する前に設計者が作成し、システムの背景・目的・採用する設計・検討した代替案などを記述する文書です。元Googleのエンジニア Malte Ubl が2020年7月に公開した[Design Docs at Google](https://www.industrialempathy.com/posts/design-docs-at-google/)は、Design Docを「主要な作者がコーディングに入る前に作る、比較的くだけた文書」と位置づけ、高いレベルの実装方針と主要な設計判断を、検討したトレードオフに重点を置いて記録するものだと説明しています。同じ資料は、Design Docの役割として次の6つを挙げています。 - 変更がまだ安く済む段階で、設計上の問題を早期に見つける - 組織の中で設計への合意を形成する - セキュリティやプライバシーなど横断的な懸念の検討漏れを防ぐ - シニアエンジニアの知見を組織全体へ広げる - 設計判断にまつわる組織の記憶の土台になる - 設計者の技術的な実績を示す成果物になる 実務で効くのは1つ目と5つ目です。文章にする過程で、曖昧だった前提や見落としていた依存関係が表に出ます。半年後に「なぜこのデータベースを選んだのか」と問われても、当時の代替案とトレードオフが書いてあれば議論をやり直さずに済みます。ソースコードは「どう動くか」を語りますが、「なぜこう決めたか」は語りません。その欠落を埋めるのがDesign Docです。なお、カタカナでは「デザインドック」と書かれるのが一般的で、「デザインドッグ」は表記の揺れです。 ### 「デザイン」は見た目ではなく設計：エンジニア型とPM型、PRDとの違い 日本語で「デザイン」と聞くとUIの意匠を思い浮かべがちですが、Design DocのDesignはソフトウェア設計です。ただし書き手によって中身の重心が変わります。エンジニアが書くDesign Docは「どう作るか」の技術判断が中心で、Googleの構成もこちらです。一方、米国のスタートアップで働くkosuke mori氏の[公開記事（2022年）](https://note.com/kosukemori/n/n968cd16c53eb)では、プロダクトマネージャー（PM）が書くデザインドックが紹介されており、ユーザーストーリー、成功指標、検証したい仮説、失敗を事前に想定するプレモーテムといった「なぜ作るか・どう測るか」の項目が厚くなります。 後者は、機能の要求を定義するPRD（製品要求仕様書）に近い文書です。判断の目安は単純で、議論したいのが**製品として何を満たすべきか**ならPRD、**それを技術的にどう実現するか**ならDesign Docです。両方が必要な案件では、PRDで目標と成功指標を固め、Design Docはそれを前提に技術の代替案を比べる、と役割を分けると重複しません。 ### 設計書・仕様書・ADR・RFCとの違い：問いと粒度の比較 仕様書は要求や振る舞い、設計書は構成や実現方法を記述する文書です。どちらも変更に応じて更新され、設計書には判断理由を含めることもあります。対してDesign Docは実装前の意思決定に焦点があり、重要な論点だけを高い視点で扱います。[ADR（Architecture Decision Record）とは｜書き方・Markdownテンプレート・design docとの違い](/tech/details/9198/)で扱うADRはさらに粒度が細かく、1つの決定を1ファイルで記録する文書です。ADRの原型である[Michael Nygardの「Documenting Architecture Decisions」](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)も、1決定を短いテキストで残す形を提案しています。Design Docは機能や変更のまとまりを1本で扱うため、複数のADRを内包する広さになります。 | 文書 | 主な問い | 粒度 | 書く時期 | | ---------- | ----------- | ---------- | -------- | | Design Doc | どう作り、なぜ決めたか | 機能・変更のまとまり | 実装前 | | PRD | 製品として何を満たすか | 機能・施策 | 企画段階 | | 仕様書 | 何を満たすか | システム・機能単位 | 要求の整理時から | | 設計書 | どう実現するか | 全体構成・部品単位 | 設計時・変更時 | | ADR | この1点をなぜ決めたか | 1決定＝1記録 | 決定の都度 | | RFC | この提案を採るべきか | 提案単位 | 合意形成前 | 境界は組織によって揺れますが、軸は「意思決定の根拠を残したいか（Design Doc・ADR）」「実装の網羅を残したいか（仕様書）」です。文書種別ごとの役割は[仕様書とは？設計書・要件定義書との違いと発注者が確認すべき観点を解説](/column/details/13200/)、ウォーターフォールの工程での位置づけは[基本設計とは？システム開発での位置づけと成果物、要件定義・詳細設計との違い](/column/details/2828/)で整理しています。要件の書き方を揃えたい場合は[EARS記法](/tech/details/11489/)のような要件記述の型も併用できます。 ### オープンソースのDesign Doc：KEP・PEP・Goのproposal・RustのRFC Design Docは社内文書に限りません。大規模なオープンソースでは、同じ考え方の文書が公開の場で運用されており、テンプレートも誰でも読めます。 | プロジェクト | 文書 | 代替案に当たる章 | | ---------- | -------------------- | -------------------------- | | Kubernetes | KEP | Alternatives | | Python | PEP | Rejected Ideas など | | Go | design doc（proposal） | Rationale | | Rust | RFC | Rationale and alternatives | Kubernetesの[KEPテンプレート](https://github.com/kubernetes/enhancements/blob/master/keps/NNNN-kep-template/README.md)にはSummary、Motivation（Goals／Non-Goals）、Proposal、Risks and Mitigations、Design Details、Drawbacks、Alternativesが並び、本記事のテンプレートとほぼ同じ構成です。Pythonの[PEP 1](https://peps.python.org/pep-0001/)は、PEPを「Pythonコミュニティに情報を提供する、または新機能を説明するdesign document」と定義しています。Goの[proposalプロセス](https://github.com/golang/proposal/blob/master/README.md)は、まず短いissueで提案し、議論で「受理」「却下」「design docを求める」のいずれかに振り分けます。design docが必要になった提案だけを `design/NNNN-shortname.md`（NNNNはissue番号）としてリポジトリに置く運用で、全提案に文書を求めない設計そのものが「書く場面を絞る」実例です。Rustの[RFCテンプレート](https://github.com/rust-lang/rfcs/blob/master/0000-template.md)はDrawbacks、Rationale and alternatives、Prior art、Unresolved questionsを独立した章に分けており、却下理由と未解決の論点を書く場所が最初から用意されています。 ## デザインドックを書くべき場面：書く価値を判定する5つの問い ### Design Docs at Googleの5つの問いと、3つ以上で書く判断 Design Docは書くのにもレビューするのにも時間がかかります。Design Docs at Googleは、手戻りを防いで得をする一方で作成とレビューで費用もかかるとしたうえで、書くかどうかを次の5つの問いで考えるよう勧めています。 1. 正しい設計に確信が持てず、先に時間をかけて確信を得る価値があるか 2. すべてのコード変更はレビューできないシニアエンジニアを、設計の段階で巻き込む助けになるか 3. 設計が曖昧、または意見が割れていて、組織としての合意に価値があるか 4. チームがプライバシー、セキュリティ、ロギングなど横断的な懸念を設計で見落とすことがあるか 5. 既存システムの設計を高い視点で説明する文書が組織に強く求められているか 原文は、このうち**3つ以上に「はい」と答えるなら、Design Docは次のプロジェクトを始めるよい方法になる**と結んでいます。チームで基準を持つなら、この5問をそのままレビュー依頼の前に答えさせるのが手軽です。メルカリShopsは2022年2月に公開した[運用紹介の記事](https://engineering.mercari.com/blog/entry/20220225-design-docs-by-mercari-shops/)で、明確な基準は設けていないとしつつ、開発に数スプリント以上かかる、実装方法が複数考えられる、技術やドメインで不慣れな領域を扱う、を目安に挙げており、最も多いのは新しいマイクロサービスの開発だと書いています。 ### 書かなくてよい場面：実装マニュアルになる文書とプロトタイプ 同じ資料は、書かなくてよいサインもはっきり示しています。「こう実装します」とだけ書かれ、トレードオフや代替案、判断の説明がない文書は**実装マニュアル**であり、その場合はすぐにプログラムを書いたほうがよかった、という指摘です。解き方が1つしかなく代替案が出てこない変更、捨てる前提の試作、素早い反復が必要なプロトタイプも、文書のオーバーヘッドと相性がよくありません。1人で数日以内に終わる改修に文書を強制すると、書くこと自体が目的になって形骸化します。後から変えにくい判断が1つだけ含まれるなら、Design Docの代わりにADRを1件残せば足ります。エンジニアが文書を書かない理由と、それでも回る仕組みは[ドキュメント化とは？エンジニアが書かない理由と開発現場で回る仕組み](/column/details/2578/)で掘り下げています。 ## デザインドックに書く項目と、コピーして使えるMarkdownテンプレート ### 設計判断を記録する標準テンプレートの項目一覧と、それぞれの必須度 書式は組織ごとに異なりますが、Design Docs at Googleが示す構成（Context and scope／Goals and non-goals／The actual design／Alternatives considered／Cross-cutting concerns）と、KEPなどのテンプレートで共通する項目はほぼ決まっています。原文自身が「ルール1は、そのプロジェクトにとって最も筋の通る形で書くこと」としています。次の表の「必須」「推奨」は本記事で提案する運用上の目安なので、案件に合わせて項目を調整してください。 | 項目 | 書く内容 | 必須度 | | ------------- | ---------------- | --- | | タイトル・著者・ステータス | 対象、責任者、状態と更新日 | 必須 | | 背景と範囲 | なぜ今作るのか、前提 | 必須 | | 目標と非目標 | やること、あえてやらないこと | 必須 | | 設計の概要 | 構成、システムコンテキスト図 | 必須 | | 詳細設計 | API、データ保存、主要な処理 | 推奨 | | 検討した代替案 | 採らなかった案と却下理由 | 必須 | | 横断的な懸念 | セキュリティ、プライバシー、監視 | 推奨 | | テスト・移行・展開 | 検証方法、段階的な展開 | 推奨 | | 未解決の論点 | レビューで決めたいこと | 推奨 | 見落とされがちなのが**非目標（Non-Goals）**です。原文は、非目標を「クラッシュしない」のような目標の否定形ではなく、**目標にしてもおかしくないが、あえて外すと決めたこと**だと説明し、データベース設計でのACID準拠を例に挙げています。メルカリShopsは目標と非目標をそれぞれ箇条書き3行以内に収めるよう意識していると書いており、短く絞るほどトレードオフを判断するときの物差しとして使えます。APIやスキーマの正式な定義を丸ごと貼るのは避け、設計判断に関わる部分だけを載せます。全文を貼ると冗長になり、すぐに実装と食い違うためです。 ### そのまま使えるMarkdownテンプレートとMermaidの構成図 リポジトリの `docs/design/` などに置き、コピーして書き始められるひな形です。見出しは上の表と対応させています。 ``` # Design Doc: 通知基盤の再設計 - 著者: 山田（バックエンド） - レビュアー: 佐藤、鈴木 - ステータス: ドラフト ｜ レビュー中 ｜ 承認 ｜ 実装済み ｜ アーカイブ - 最終更新: 2026-10-17 ## 1. 背景と範囲 現状の通知はアプリサーバーから同期送信しており、ピーク時に応答が遅れる。 本Docは、メールとプッシュ通知の送信経路だけを対象にする。 ## 2. 目標と非目標 ### 目標 - 通知の送信をリクエスト処理から切り離し、APIのp95を300ms以内に戻す ### 非目標 - SMS対応（今期は扱わない） - 配信順序の厳密な保証 ## 3. 設計の概要 （システムコンテキスト図と、処理の流れを数段落で） ## 4. 詳細設計 - API: 変更点だけを記載 - データ保存: 送信キューと送信履歴の持ち方 ## 5. 検討した代替案 | 案 | 長所 | 短所 | 判断 | |----|------|------|------| | A: メッセージキュー＋ワーカー | 疎結合、再送が容易 | 運用対象が増える | 採用 | | B: DBポーリング | 追加基盤が不要 | 遅延と負荷が読みにくい | 却下 | ## 6. 横断的な懸念 - セキュリティ: 送信先アドレスの扱いと保持期間 - 監視: キュー滞留数のアラート ## 7. テスト・移行・展開 - 10%の利用者から段階的に切り替える ## 8. 未解決の論点 - 再送回数の上限をいくつにするか ``` 設計の概要には、新しいシステムが周囲のどこと話すかを示す**システムコンテキスト図**を1枚入れると読み手の理解が速まります。図をテキストで書けば、Design Docと同じリポジトリで差分を管理できます。次は[Mermaidのシーケンス図の記法](https://mermaid.js.org/syntax/sequenceDiagram.html)に沿った例です。GitHubは[Markdown内のMermaidを図として描画](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)するので、プルリクエストの画面でもそのまま図になります。 ```` ```mermaid sequenceDiagram participant C as クライアント participant API as アプリAPI participant Q as 送信キュー participant W as 通知ワーカー participant M as メール配信サービス C->>API: 通知を伴う操作 API->>Q: 通知ジョブを登録 API-->>C: 即時にレスポンスを返す W->>Q: ジョブを取得 W->>M: 送信リクエスト M-->>W: 結果（失敗時は再送） ``` ```` Mermaidの書き方全般は[Mermaid記法の使い方｜無料のLive Editor（mermaid.live）でフローチャート・シーケンス図を作成](/tech/details/3374/)、構成図の粒度と記法の選び方は[アーキテクチャ図とは？書き方の手順とC4モデル・AWSアイコンの規約、作成ツールの選び方](/tech/details/4024/)で扱っています。 ### 1〜3ページで済ませるmini design docのテンプレート Design Docs at Googleは、大きなプロジェクトの目安を10〜20ページ前後とする一方、アジャイル開発の小さな改善やサブタスク向けに**1〜3ページの「mini design doc」**も十分成り立つとしています。手順は長い文書と同じで、範囲を絞って簡潔に書くだけです。小さな変更向けに、次の4見出しの記入例を示します。必要な論点があれば見出しを追加します。 ``` # Mini Design Doc: 送信履歴の保持期間を90日に短縮 - 著者 / ステータス / 最終更新: 山田 / レビュー中 / 2026-10-17 ## 目標と非目標 - 目標: 送信履歴テーブルの容量増加を止める - 非目標: 過去分の集計方法の変更 ## 変更点 - 90日を過ぎた行を日次バッチで削除する ## 検討した代替案 - 月別パーティションごと削除: 削除は速いが、移行に停止時間が要るため見送り ## リスクと確認方法 - 問い合わせ対応で91日以前の履歴が要る件数を、直近3か月の問い合わせ記録で確認する ``` 短くしても「検討した代替案」だけは残します。代替案が1つも書けないなら、それは前の章で触れた実装マニュアルで、Design Docにする必要がない変更だというサインです。 ### 検討した代替案とトレードオフの書き方：Design Docの核心 テンプレートの中で手を抜いてはいけないのが「検討した代替案」です。Design Docs at Googleはこの章を最も大切な章の1つと位置づけ、選んだ解が目標に対してなぜ最良なのか、読み手が思い浮かべる他の解がどんなトレードオフを持ち込むのかを明示する場所だとしています。採用した設計だけを書いた文書は、レビュアーに「なぜ他ではダメなのか」を判断する材料を渡せません。 書き方の型は単純です。少なくとも2つの案を挙げ、性能・コスト・実装工数・運用負荷といった軸で比べ、選んだ理由と捨てた理由をそれぞれ1〜2文で言い切ります。メルカリShopsの運用紹介では、代案が思い浮かばないときも、現状のインフラ標準とは別の方法や、サードパーティー製品・OSSを使う場合を考えて代案をひねり出すとしており、「自前で作る」以外の選択肢を最低1つ並べるのが実用的な最低線です。代替案の章が空のDesign Docは、レビューに回す価値がほとんどありません。 ## デザインドックの書き方：書く時期と長さ、レビューに回す手順 ### 実装前にいつ書くか・どこまで書くか：粒度と長さの目安 書くタイミングは、要件が一通り固まり、実装に入る前です。要件が動いている段階で詳細まで書くと、変更のたびに書き直しになります。長さは前述のとおり大きな案件で10〜20ページ前後、それを大きく超えるなら問題を分割したほうがよいと原文は述べています。初稿が長期化する場合は、対象範囲の広さに加え、未確定の要件や技術調査が執筆を止めていないか確認します。 粒度の原則は「ソースコードとコメントで伝わることは書かない」。原文も、コードや擬似コードを載せるのは新しいアルゴリズムを説明する場合などに限り、実現できることはプロトタイプへのリンクで示すよう勧めています。実装を読めば分かる詳細ではなく、コードからは読み取れない設計の意図と背景に字数を割きます。 ### Gitとプルリクエストでレビューに回す手順 [『Software Engineering at Google』第10章（Documentation）](https://abseil.io/resources/swe-book/html/ch10.html)は、Googleの多くのチームが主要なプロジェクトの着手前に承認済みのDesign Docを求めていること、この設計の議論が「コードを書く前のコードレビュー」のように働くことを紹介しています。Design Docs at Googleが示すライフサイクルは、作成と素早い反復、レビュー（複数回のこともある）、実装と反復、保守と学習の4段階です。最初は問題領域に詳しい同僚1〜2名に見せて方向性を固め、安定してから関係者全体のレビューに広げます。 コードと同じリポジトリに置くと、コメントのやり取りと変更履歴が残り、実装との突き合わせもしやすくなります。事前に上の通常版テンプレートを `docs/design/_template.md` として保存しておきます。GitHub CLIの認証と、書き込み可能なoriginを設定した既存リポジトリのルートで、次の操作を実行します（GitHub CLIの `gh` を使う例）。 ``` git switch -c design/notification-service mkdir -p docs/design cp docs/design/_template.md docs/design/2026-10-notification-service.md # テンプレートを埋めたらコミットする git add docs/design/2026-10-notification-service.md git commit -m "Design Doc: 通知基盤の再設計（ドラフト）" git push -u origin design/notification-service gh pr create --draft --title "Design Doc: 通知基盤の再設計" \ --body "見てほしい点: 5章の代替案と2章の非目標" ``` プルリクエストの本文には「どこを見てほしいか」を必ず書きます。漠然と「レビューお願いします」と出すより、代替案と非目標に観点を絞ったほうが指摘の質が上がります。Markdownで書くなら、Goのproposalプロセスが定める**1文ごとに改行する**書き方も有効です。Goは、そうすることでコメントを正確な位置に付けられ、差分も短く保てると理由を明記しています。レビュー観点の立て方は[コードレビューとは？目的・観点・進め方と実装現場の運用設計を解説](/tech/details/13384/)の考え方を流用できます。合意が取れたらドラフトを解除してマージし、ステータスを承認に変えます。 ### Google Docs・GitHub・Notionの選び分け：レビュアー別の判断基準 Design Docを置く場所は、誰がレビューに参加するかで決めると迷いません。 | 置き場所 | 向く場面 | 弱い点 | | ----------------- | --------------- | --------------- | | GitHub＋Markdown | レビュアーが全員エンジニア | 非エンジニアはコメントしにくい | | Google Docs | PMや他部署も議論に入る | コードとの突き合わせ、版の追跡 | | Notion・Confluence | 社内Wikiに設計を集約したい | リポジトリの変更と連動しない | GitHubは行単位の履歴とコードとの同時レビューが強みで、2025年9月からは、新しい「Files changed」画面（パブリックプレビュー）で[変更されたファイルの未変更行にもコメントを付けられる](https://github.blog/changelog/2025-09-25-pull-request-files-changed-public-preview-now-supports-commenting-on-unchanged-lines/)ようになりました。図は画像かMermaidなどのコードで用意する必要があります。Google Docsは同時編集に加え、[変更履歴の確認と版への命名](https://support.google.com/docs/answer/190843)ができます。実装との対応を追うには、承認した版に名前を付け、対応するコミットやリリースへのリンクを記録します。メルカリShopsはSlackで共有し、Notion上でレビューと議論をする流れで運用しています。エンジニアだけで閉じるならGitHub、事業側と合意を取る文書ならGoogle DocsやNotion、と分けるのが現実的です。 ## 承認後のデザインドックの扱い：継続更新とArchiveによる凍結 実装が始まった後のDesign Docをどう扱うかは、組織によって正反対の流儀があります。どちらが正しいというより、**どちらを採るかを最初に決めて文書に明記しておく**ことが要点です。 | 流儀 | 実装中の変更 | 出荷後 | | --------------------------- | --------- | ------------------ | | 更新する（Design Docs at Google） | 出荷前なら必ず更新 | 修正は別文書に分かれがち | | 凍結する（メルカリShops） | 更新は任意 | 更新せずstatusをArchive | Design Docs at Googleは、実装中に設計の不足や誤った見込みが見つかったら文書を更新するよう強く勧め、目安として「設計したシステムがまだ出荷されていないなら必ず更新する」としています。同時に、人は文書の更新が苦手で、変更が別の文書に切り出されがちだとも認めており、元の文書から追補へのリンクを張っておくと後の保守担当者を助けると書いています。一方、2022年公開のメルカリShopsの運用紹介では、開発開始後は原則として更新せず、開発完了後にstatusをArchiveにする運用が紹介されています。更新しないと明記しておけば、将来読む人が「これは最新の設計ではない」と分かる、というのが理由です。 実務での選び分けは、Design Docを**現役の設計資料**として使いたいなら更新する流儀、**開発時点の判断の記録**として残したいなら凍結する流儀です。凍結する場合、実装中の個別の決定はADRとして1件ずつ追記すれば履歴が途切れません。更新する場合も、設計書とコードのずれは放っておくと広がります。ずれをAIで検出し続ける考え方は[整合性駆動開発（CoDD）とは？設計書とコードの整合性をAIで維持する開発手法と導入判断](/tech/details/14278/)で扱っています。どちらの流儀でも、原文が勧めるように1〜2年後に自分の文書を読み直し、何が当たり何が外れたかを振り返ると、次の設計の精度が上がります。 ## GoogleのDesign Docs文化に学ぶ、実装前レビューという設計の規律 Design Docという言葉は、Googleのエンジニアリング文化から広く知られるようになりました。原文によれば、Googleのエンジニアは触ったことのないシステムに向き合うとき、まず「Design Docはどこ？」と尋ねることが多いそうです。文書は時間とともに実態からずれるものの、そのシステムを作ったときの考え方に最も近づきやすい入口だからです。 規律の中身は、実装前に設計を専門家のレビューにかけることです。SWE book第10章によれば、Googleの標準的なテンプレートはセキュリティ、国際化、ストレージ要件、プライバシーの検討を設計者に求め、その部分は各分野の専門家がレビューします。立派な文書を作ることが目的ではないので、凝った図や長い前置きより、論点が明確で代替案が比較されている素朴な文書のほうがよく機能します。 ## 生成AIでデザインドックを書く・レビューする際のプロンプトの型と指示 Design Docの下書きとレビューは、生成AI（ChatGPTやClaudeなど）と相性のよい作業です。[仕様駆動開発（SDD）](/tech/details/8740/)のように、AIに設計文書を読ませてから実装させる進め方も広がっています。 ### AIに設計メモからドラフトを書かせるプロンプトと、前提の質問を返させる指示 通知基盤の例なら、同期送信の課題、APIの応答時間の目標、SMSを非目標とする判断を設計メモにし、AIへ渡してテンプレートの各欄に整理させます。出力してほしい項目構成を先に指定するのが要点です。 ``` あなたはシニアソフトウェアエンジニアです。以下の設計メモを、Design Docに整えてください。 構成は「背景と範囲／目標／非目標／設計概要／詳細設計／検討した代替案／横断的な懸念」とし、 各項目は簡潔に。代替案は最低2つ挙げ、却下理由も添えてください。 不足している前提があれば、決めつけず質問として末尾に列挙してください。 # 設計メモ - （ここに箇条書きの設計メモを貼る） ``` 効いているのは末尾の「不足している前提は質問として出す」指示です。これがないと、AIは曖昧な箇所を勝手に埋め、それらしいが根拠のない文章を作ります。質問を返させれば、人が決めるべき論点が先に見えます。 ### AIに任せる代替案の洗い出しと、抜け漏れを探す一次レビュー 通知基盤の例なら、メッセージキュー案とDBポーリング案の比較軸や、再送回数の未決事項をAIに点検させます。人のレビュー前に一次チェックを任せると、レビュアーは本質的な議論に集中できます。 ``` 以下のDesign Docをレビューしてください。観点は次の5つです。 1. 検討されていない代替案はないか（あれば具体的に提案） 2. 非目標が「目標の否定形」になっていないか 3. セキュリティ・プライバシー・ロギングで書き漏れている論点はないか 4. 記述が曖昧で実装者が迷いそうな箇所はどこか 5. 代替案がなく「こう実装する」だけの実装マニュアルになっていないか 指摘は重要度の高い順に、根拠とセットで挙げてください。 ``` 2つ目と5つ目は、前述の非目標の定義と「実装マニュアル」の判定をそのまま検査項目にしたものです。人が思いつかなかった代替案が出てくれば、それを検討して却下理由を書くだけでも文書の説得力が上がります。 ### AIエージェントが読む設計文書：Kiroのdesign.mdとSpec Kitのplan.md KiroやGitHubのSpec Kitには、Design Docに近い設計文書を、AIエージェントによる実装の前提として作成する仕組みがあります。AWSのKiroの[Specs](https://kiro.dev/docs/specs/)は、1つの機能につき requirements.md（ユーザーストーリーと受け入れ条件）、design.md（技術アーキテクチャ、シーケンス図、実装上の検討事項）、tasks.md（追跡できる実装タスク）の3ファイルを作ります。GitHubのSpec Kitでは `/speckit.plan` コマンドが実装計画の plan.md を作り、その前段の research.md には「Decision（何を選んだか）／Rationale（なぜ選んだか）／Alternatives considered（他に何を検討したか）」の形式で調査結果をまとめるよう、[コマンド定義](https://github.com/github/spec-kit/blob/main/templates/commands/plan.md)で指示しています。 Design Docの核である「代替案と決定理由」は、AIに実装させる流れでも独立した記録として残る作りになっているわけです。運用で守りたいのは、エージェントが生成した design.md や plan.md をそのまま承認しないことです。生成された構成案に上の5観点のレビュープロンプトを当てるか、人が代替案と非目標を書き足してから実装に進みます。Kiroの全体像は[Kiroとは？AWS製の仕様駆動AI IDEの特徴・料金・使い方を解説【2026年版】](/tech/details/7963/)で扱っています。 ### AIに任せてよい範囲と、人が判断すべき境界線 AIに任せてよいのは下書きと一次レビューまでで、設計判断そのものは委ねません。AIは事実と異なる内容をもっともらしく書くため、技術的な記述は人が裏を取ります。外部のAIサービスに未公開の設計情報を貼る前には、社内規定で入力してよい情報かを確認し、必要なら固有名を伏せます。代替案の取捨や優先度の最終判断は、運用の責任を負う人が行います。通知基盤の例では、AIの提案がSMSを対象外とする非目標や、APIのp95を300ms以内にする目標と矛盾していないか、人が確認します。 ## デザインドックを導入すべきチームと見送ってよいチームの判断基準 個々の案件で書くかどうかは5つの問いで決めるとして、チームの仕組みとして導入するかは次で判断できます。**いずれかに当てはまるなら導入すべき**です。 - 1つの変更に2人以上のエンジニアや複数チームが関わり、着手前の合意が要る - データベースや外部サービスの選定など、後から変えにくい判断を含む - 半年以上運用するシステムで、担当者の交代が見込まれる - 発注者と開発会社の間で、設計の意図と範囲を文書で握っておきたい 反対に、少人数で短期の改修が中心のチームや、捨てる前提の検証が続く段階では見送ってかまいません。導入時は全案件に義務づけず、「mini design docで3ページ以内」から始め、レビューで代替案の章が機能しているかを見て範囲を広げるのが無理のない進め方です。 外部の開発会社へ発注する立場なら、Design Docに相当する設計判断の記録を成果物として出せるかどうかも、発注先を選ぶ観点になります。要件定義から設計方針の合意づくりまでを発注者側で支える[要件定義・RFP作成・PMO支援](https://www.issoh.co.jp/service/system/pmo/)では、代替案と非目標を含めた設計判断の整理からお手伝いしています。 ## よくある質問 ### デザインドックとは何ですか？ 実装を始める前に、システムの背景・目的・採用する設計・検討した代替案などを書き、設計の意図と根拠をチームで共有する文書です。「どう作るか・なぜそう決めたか」を残すことに重点があり、Googleの開発文化から広まりました。KubernetesのKEPやPythonのPEP、Goのdesign docも同じ考え方の文書です。 ### デザインドックと設計書・仕様書の違いは何ですか？ 仕様書が要求や振る舞い、設計書が構成や実現方法を記述するのに対し、Design Docは実装前の意思決定に絞り、代替案とトレードオフを含めて「なぜその設計にしたか」を残します。製品として満たすべき要求を定義するならPRD、1つの決定だけを記録するならADRが向きます。 ### デザインドックのテンプレートには何を書けばよいですか？ 背景と範囲・目標と非目標・設計概要・詳細設計・検討した代替案・横断的な懸念（セキュリティ、プライバシー、監視）が基本です。中でも「検討した代替案」は必須で、これを省くと実装マニュアルになります。小さな変更なら1〜3ページのmini design docで十分です。 ### デザインドックは誰が・いつ・どのくらいの長さで書きますか？ 設計を担当するエンジニアが、要件が固まり実装に入る前に書きます。Design Docs at Googleの目安では、大きなプロジェクトで10〜20ページ前後、小さな改善なら1〜3ページです。書くかどうかは、同じ資料の5つの問いのうち3つ以上に当てはまれば書く価値が高いという目安を使い、2つ以下のときは合意形成の必要性と作成の負担を比べて決めます。 ### 生成AIでデザインドックは作れますか？ 箇条書きの設計メモからテンプレート形式のドラフトを作らせたり、書いた文書の抜け漏れや代替案をレビューさせたりできます。不足する前提を質問として返させたうえで、回答に根拠のない補完がないか確認します。技術的記述の裏取りと最終的な設計判断は人が行います。 ## 関連記事 - [ADR（Architecture Decision Record）とは｜書き方・Markdownテンプレート・design docとの違い](/tech/details/9198/) - [Any Decision Recordとは｜ADRの範囲をAnyに広げる判断基準とテンプレート・運用設計](/tech/details/16103/) - [仕様駆動開発（SDD）とは？従来手法との違いとSpec Kitで試す手順【2026年10月】](/tech/details/8740/) - [アーキテクチャ図とは？書き方の手順とC4モデル・AWSアイコンの規約、作成ツールの選び方](/tech/details/4024/) - [仕様書とは？設計書・要件定義書との違いと発注者が確認すべき観点を解説](/column/details/13200/) - [プロダクトマネージャーの機能提案ドキュメント｜戦略（Why）と要件（What）の書き方](https://www.issoh.co.jp/column/details/2344/) --- 出典: [デザインドック（Design Doc）とは？書き方とテンプレート、書くべき場面とAIでの下書き]()（株式会社一創）