필사 모드: 設計ドキュメント完全ガイド: 決定を残す文書と消える文書

• はじめに
• 1. いつ文書を書き、いつ書かないか
  • 1-1. 書かなくてよい場合
  • 1-2. 書くべき場合 — 五つの判別質問
  • 1-3. よく間違える点
• 2. 文書の四類型と選び方
  • 2-1. 1-pager — 問題が本物かを合意する文書
  • 2-2. 設計ドキュメント — 実装戦略とトレードオフ
  • 2-3. ADR — 決定一つを不変の記録に
  • 2-4. RFC — 組織の境界を越える合意
  • 2-5. 何をいつ使うか
  • 2-6. 論争点 — 重い RFC と軽い ADR
• 3. 標準セクションと、各欄が実際にしている仕事
  • 3-1. ヘッダに必ず入れる四行
• 4. Non-Goals と Alternatives Considered — 最も空欄になりやすい二つ
  • 4-1. Non-Goals は「やらないことリスト」ではない
  • 4-2. Alternatives Considered の唯一のアンチパターン
  • 4-3. 代替案に必ず含めるもの
• 5. レビューの運用
  • 5-1. 品質より先に速度が壊れる
  • 5-2. 承認基準を下げないとレビューは回らない
  • 5-3. 三段レビュー
  • 5-4. コメントを三種類にラベリングする
  • 5-5. 決定期限
• 6. 決定には消費期限がある — ADR の状態遷移
  • 6-1. 再検討条件を決定と一緒に書く
  • 6-2. 4-2 節とのつながり
• 7. 文書が古びる問題への対処
  • 7-1. 三つの戦略と適用先
  • 7-2. 古びを検知する安価な仕掛け
  • 7-3. 削除も保守のうち
• 8. 文書が失敗する形
  • 8-1. 実装マニュアル化
  • 8-2. 承認の演劇
  • 8-3. 偽の代替案
  • 8-4. 範囲の無限拡張
  • 8-5. 決定のない文書
  • 8-6. レビューの停滞
  • 8-7. チャットにしか残らない決定
  • 8-8. コードより長生きして嘘をつく文書
  • 8-9. 設計ドキュメントはチームを遅くするという主張
• クイズ: 理解度を確認しましょう
• おわりに
• 参考資料
• 関連記事

はじめに

設計ドキュメントは結局、二種類に分かれます。半年後に誰かが「これ、なぜこう作ったんだっけ」と聞いたときに答えになる文書と、そのころにはリンクすら見つからない文書です。違いは文章力ではありません。何を記録したか、そしてその記録が組織のどこに刺さっているかの違いです。

このブログにはすでに 文章で説得する — 設計ドキュメントと RFC が通る構造 と エンジニアの書く力 があります。この二本は修辞と承認の話です。どう書けば読まれるか、どうすれば文書が通るか。本記事はその前と後ろを扱います。文書を文章ではなくチームの意思決定インフラとして置き、いつどの形式を使うか、レビューをどんな手順で回すか、下された決定がどう期限切れになるか、そして文書がどんな形で失敗するかを整理します。目標はうまく書けた文書ではなく、決定を残す文書です。

基準点は「Design Docs at Google」です。定義はそこから引きますが、重心は実務でよく空欄になる欄と、よく崩れる手順のほうに置きます。

1. いつ文書を書き、いつ書かないか

「Design Docs at Google」は設計ドキュメントを、コーディング前に書く非公式な文書と定義し、載せるべきものを「高レベルの実装戦略と主要な設計上の決定、とりわけトレードオフに重点を置いたもの」と説明します。同じ記事は、エンジニアの仕事は「コードを生産すること自体ではなく、問題を解くこと」だとも言います。この二文をつなげると判別基準が出ます。トレードオフがなければ文書もありません。

1-1. 書かなくてよい場合

• 解法が明白で、意味のあるトレードオフがないとき。原文が直接名指しする省略条件です。
• 文書が事実上実装マニュアルになるとき。コードをそのまま散文に移した文書は、レビュアーに判断材料を与えません。それならコードを書くほうが速いです。
• 戻すコストが一人の半日で済む変更。試してだめなら消すほうが安く付きます。

1-2. 書くべき場合 — 五つの判別質問

二つ以上該当したら文書を書きます。一つだけなら 1-pager で足りることが多いです。一つも該当しなければコードから書きます。

1-3. よく間違える点

文書の要否を規模で判断する組織が多くあります。「三週間以上かかる作業は設計ドキュメント必須」といった規則です。規模は代理指標にすぎません。三週間の反復作業に文書は要らず、半日の保存フォーマット変更には要ります。基準は戻すコストと代替案の存在です。

2. 文書の四類型と選び方

同じ「設計ドキュメント」という言葉が、四つの別物を指しています。三つを混ぜて使うと、文書は何の仕事もしなくなります。

2-1. 1-pager — 問題が本物かを合意する文書

• 目的: 解法ではなく、問題の存在と優先度に合意する
• 分量: 一ページ。背景、症状、影響範囲、やらなかった場合のコスト、次の一手
• 寿命: 数日から数週間。設計ドキュメントに昇格するか破棄される
• 失敗モード: 解法を先に書き込んでしまい、問題定義の議論が飛ばされる

2-2. 設計ドキュメント — 実装戦略とトレードオフ

• 目的: どう作るかの合意。原文の言う「実装戦略と主要な設計上の決定」
• 分量: 通常は数ページ。システム規模ではなく不確実性に比例する
• 寿命: 実装期間。終われば大抵は凍結される
• 失敗モード: 代替案の分析がなく結論だけがある文書

2-3. ADR — 決定一つを不変の記録に

• 目的: 決定一つの文脈・選択・結果を短く固定する
• 分量: 一画面。文脈、決定、結果、状態
• 寿命: 恒久。本文は直さず、新しい ADR で置き換える
• 失敗モード: 決定ではなく説明を書いてしまい、何が決まったのか分からない

2-4. RFC — 組織の境界を越える合意

• 目的: 複数チーム・複数システムにまたがる標準や方向を定める
• 分量: 設計ドキュメントより長い。移行計画と影響を受けるチーム一覧が必須
• 寿命: 承認後は参照文書。改訂は新版として出す
• 失敗モード: 手続きが重すぎて誰も始めない、あるいは形式だけ残り実質の合意はチャットで済む

2-5. 何をいつ使うか

2-6. 論争点 — 重い RFC と軽い ADR

ここは業界の意見が割れます。勝者を決めずに軸を見ましょう。

• 決定の頻度: 決定が頻繁なら重い手続きがボトルネックになります。まれで大きいなら手続きコストは相対的に小さくなります。
• 関係者の分散度: 決定に縛られるチームが一桁なら会話が手続きを代替できます。二桁を超えると会話では届きません。
• 戻すコスト: 戻せる決定に RFC を使うと学習速度が落ちます。
• 維持コスト: ADR は安く書ける分だけ放置されやすいです。RFC は高く付く代わりに存在感が長く残ります。
• 組織の信頼水準: 信頼の低い組織で軽い手続きを敷くと、「誰がいつ決めたのか分からない」に帰結します。

両方を併用する組織も多いです。RFC で方向を決め、その方向の中で各チームが ADR として細部の決定を残す形です。

3. 標準セクションと、各欄が実際にしている仕事

「Design Docs at Google」が挙げる典型的な構成は、Context and Scope、Goals and Non-Goals、The Actual Design、Alternatives Considered、そしてセキュリティ・プライバシー・可観測性といった横断的関心事です。器だけ真似ても何も起きないので、各欄が実際に果たす機能として書き直します。

[ヘッダ]  タイトル / 作成者 / 最終更新日 / 状態 / レビュー期限

1. Context and Scope        この問題がなぜ今あるのか
2. Goals                    何が真になれば成功なのか
3. Non-Goals                目標になり得たが今回は目標でないもの
4. The Actual Design        実際の設計とその中のトレードオフ
5. Alternatives Considered  検討して採らなかった案と、その条件
6. Cross-cutting concerns   セキュリティ / プライバシー / 可観測性 / 運用

• Context and Scope: レビュアーが判断するのに必要な最小限の背景だけを埋めます。仕事は「読み手と書き手の知識差をなくすこと」です。会社の沿革を書き始めた時点で失敗です。
• Goals: レビュアーに設計を評価する物差しを渡します。目標が「性能改善」では物差しがないのと同じです。「p99 レイテンシを 800ms 未満に」のように判定可能である必要があります。
• Non-Goals: 範囲を固定します。次節で別に扱います。
• The Actual Design: ここが本文です。仕事は構造の説明ではなくトレードオフの提示です。データフロー、保存モデル、失敗時の挙動、移行経路が入ります。
• Alternatives Considered: 将来の再論争を防ぎます。これも次節で扱います。
• Cross-cutting concerns: 後で組織の別部署が必ず聞く質問を先回りします。空欄だとレビューが終わった後にセキュリティ検討が付き、日程がまた押します。

3-1. ヘッダに必ず入れる四行

状態(ドラフト・レビュー中・確定・廃止)、最終更新日、担当者、レビュー期限。この四行がないと、半年後の読み手はこの文書を信じてよいか判断できません。本文の品質よりも、この四行の有無のほうが文書の寿命を大きく左右します。

4. Non-Goals と Alternatives Considered — 最も空欄になりやすい二つ

4-1. Non-Goals は「やらないことリスト」ではない

Non-Goal とは、妥当に目標になり得たが今回は目標でないものです。そもそも誰も期待していないものを書けば、欄を埋めただけです。

• 悪い Non-Goal: 「このシステムは宇宙船を制御しない」
• よい Non-Goal: 「マルチリージョン同時書き込みは今回の範囲外。単一リージョン書き込み + 非同期レプリケーションで行く」
• よい Non-Goal: 「既存 v1 API のレイテンシ改善は目標ではない。v2 経路のみを対象とする」

よい Non-Goal には共通点があります。読む人が残念がります。残念さがなければ、範囲を固定できていません。

4-2. Alternatives Considered の唯一のアンチパターン

最も多い失敗は、自分の案が勝つように作られた偽の代替案です。三つ並べて二つが明らかに悪いなら、その文書は代替案を検討したのではなく結論を装飾したのです。

各代替案に次の一行を強制すれば、大半は解決します。

代替案 B が選ばれるには、何が真である必要があるか?
→ 「書き込み QPS が今の 10 倍になり、チームが運用要員を 2 名確保できれば B が有利」

この一行は三つの仕事を同時にします。第一に、代替案を真面目に扱った証拠になります。第二に、半年後に状況が変わったとき、再検討条件がそのまま出てきます。第三に、レビュアーが反対する地点を具体化します。「B のほうがよくないですか」が「10 倍という前提が違います」に変わります。

4-3. 代替案に必ず含めるもの

何もしない案です。現状を維持したらどんなコストが発生し続けるのかを書くと、プロジェクトの正当性が検証されます。この欄を埋めている途中でプロジェクトが中止になることも実際にあり、それは文書が役割を果たした事例です。

5. レビューの運用

文書レビューはコードレビューとほぼ同じ壊れ方をします。グーグルのエンジニアリング慣行がコードレビューについてまとめた原則は、文書レビューにもそのまま当てはまります。

5-1. 品質より先に速度が壊れる

• 「Speed of Code Reviews」は「コードレビュー依頼への応答にかかってよい最大時間は一営業日」と明記します。集中作業中でなければ、依頼が来た直後に処理せよとも言います。
• 同じ文書は「コードレビュープロセスへの不満の大半は、プロセスを速くすることで実際に解消される」と述べます。
• さらに、遅いレビューは「クリーンアップやリファクタリング、既存変更のさらなる改善を萎縮させる」と指摘します。

文書に置き換えるとこうなります。レビューが遅い組織では、人は文書を書かなくなります。文書文化が死ぬ第一の原因は、執筆負担ではなく応答の遅さです。

5-2. 承認基準を下げないとレビューは回らない

「The Standard of Code Review」は「変更がシステム全体のコード健全性を確実に改善する状態になったら、完璧でなくても承認する側に寄せるべき」と言います。文書も同じです。承認基準は完結性ではなく改善の有無です。完璧な文書を待てば、文書は永遠にドラフトのままです。

同じ文書の残りの原則もそのまま有効です。技術的事実とデータが個人の好みに勝ちます。必須でない磨き上げの提案には「Nit: 」の接頭辞を付け、著者が無視できるようにします。そして「著者とレビュアーが合意に至らないことを理由に変更を放置するな」と明示します。文書レビューではこの条項が特に重要です。合意できないときに誰が決めるのかを先に決めておかないと、文書は永遠に開いたままになります。

5-3. 三段レビュー

「Design Docs at Google」が言う文書のライフサイクルは、作成と高速な反復 → レビュー → 実装と反復 → 保守と学習です。レビュー段階を三層に分けると通過率が大きく上がります。

1. 一人レビュー: 最も反対しそうな一人にまず送ります。ここで半分が落ちます。
2. 小グループレビュー: 直接影響を受ける 3〜5 名。非同期のコメントで進めます。
3. 広域告知: 残りにはリンクと決定期限だけを送ります。反対がなければ通過です。

会議は非同期で収束しないときだけ開きます。反対意見が二方向に割れ、コメントが 20 を超えたら、そのときが 30 分の会議を入れるときです。

5-4. コメントを三種類にラベリングする

• ブロッキング: このままでは進められない理由。解消しないと承認しない
• 質問: 理解できない箇所。回答で終了できる
• 好み: 自分なら別にするという意見。著者は無視してよい

ラベルがないと、すべてのコメントがブロッキングのように読まれます。文書レビューが怖い組織には、大抵このラベルがありません。

5-5. 決定期限

定足数ではなく期限を使います。「8 月 20 日 18 時までに反対がなければこの案で進めます」と文書の冒頭に書きます。定足数方式は忙しい一人が文書を無期限に止められるようにし、期限方式は沈黙を明示的な同意に変えます。

6. 決定には消費期限がある — ADR の状態遷移

ADR の核心は形式ではなく不変性です。すでに下された決定の本文を直すと、その決定がどんな制約の下で下されたのかが消えます。決定の根拠はその時点の制約に縛られているので、制約が変わったら決定を修正するのではなく、新しい決定を下して以前の決定を置換表示します。

Proposed ──承認──▶ Accepted ──置換──▶ Superseded (by ADR-0031)
    │                  │
    │ 却下             │ もう使わない (代替案なし)
    ▼                  ▼
 Rejected          Deprecated

• Proposed: 提案済み。レビュー中
• Accepted: 確定。今有効な決定
• Rejected: 検討したが採用しなかった。消さずに残します。 同じ提案が再び上がったとき、この記録が最も値打ちを持ちます
• Deprecated: もう従わない。代替案はなし
• Superseded: 新しい ADR が置き換えた。必ず置換先の ADR 番号を併記します

6-1. 再検討条件を決定と一緒に書く

日付で期限を切る方式(「一年後に再検討」)は大抵守られません。条件で切ってはじめてアラームが鳴ります。

# ADR-0012: 注文状態のストアに関係データベースを使う

- 状態: Accepted (2026-08-15)
- 決定者: 決済チーム
- 再検討条件: 注文テーブルが 5 億行を超える、または書き込み QPS が 3,000 を超えたとき

### 文脈
現在の注文量は一日 40 万件、書き込み QPS は最大 120。トランザクション境界が注文・決済・在庫にまたがる。

### 決定
関係データベースの単一インスタンス + 読み取りレプリカで行く。

### 結果
- よくなる点: トランザクション境界をコードで扱わずに済む
- 悪くなる点: 書き込みのスケールが垂直スケールに縛られる
- 監視する指標: 書き込み QPS、テーブル行数、レプリケーション遅延

再検討条件に書いた指標を実際のダッシュボードに載せると、文書は生きた状態で保たれます。この接続がなければ、条件はただの文です。

6-2. 4-2 節とのつながり

4-2 節で各代替案に強制した「この案が選ばれるには何が真である必要があるか」が、そのまま再検討条件になります。設計ドキュメントで一度書いた文が、ADR の期限条件として再利用される構造です。

7. 文書が古びる問題への対処

「Design Docs at Google」は、設計ドキュメントが「他のあらゆるドキュメントと同様、時間とともに現実とずれていく傾向がある」と認め、原本を更新するか、後続文書を付けてリンクする方式を示します。この問題はなくせません。管理方式を選べるだけです。

7-1. 三つの戦略と適用先

最も多い誤りは、設計ドキュメントを生きた文書として維持しようとすることです。設計ドキュメントは特定時点の判断の記録です。直し続けると「この文書はいつの真実か」を失います。実装が終わったら凍結し、変わった部分は冒頭の一行で知らせます。

> この文書は 2026-08-15 時点の設計です。キャッシュ層は 2026-11-02 に
> ADR-0031 で置き換えられました。現行の構造はそちらを見てください。

7-2. 古びを検知する安価な仕掛け

• 最終レビュー日: 更新日ではなくレビュー日を書きます。内容が変わらなくても「まだ有効」と確認した日付が必要です。
• 担当者不在の検知: 担当者が退職・異動したら、文書の状態を自動で「持ち主なし」に変えます。
• コードとの距離: 文書がコードリポジトリの中にあれば変更と一緒に目に入ります。別のウィキにあれば目に入りません。この一点が古びる速度を大きく変えます。
• リンク切れ点検: 文書内のリンクが切れていないか定期的に確認します。切れたリンクは、その文書が長く放置された最も信頼できる兆候です。

7-3. 削除も保守のうち

廃止した文書は消さず、状態だけを廃止に変えて検索から外します。消せばリンクが切れ、残せば誤った情報が流通します。状態表示 + 検索除外が折衷案です。

8. 文書が失敗する形

八つの失敗モードを、症状・原因・対処で整理します。

8-1. 実装マニュアル化

• 症状: 文書がコードを散文に移しただけ。トレードオフの段落がない
• 原因: 決定が終わった後に形式を埋めようとして文書を書いた
• 対処: 原文が言うとおり、この種の文書は書かずにコーディングを始めます

8-2. 承認の演劇

• 症状: 8 名が承認したのにコメントが 0 件
• 原因: レビューが通過儀礼になった。反対のコストが高い組織文化
• 対処: 一人レビューを前に置き、ブロッキング・質問・好みのラベルを導入して反対コストを下げます

8-3. 偽の代替案

• 症状: 三つの代替案のうち二つが明らかに悪い
• 原因: 結論を決めた後に根拠を作った
• 対処: 各代替案に「この案が勝つには何が真である必要があるか」を強制します

8-4. 範囲の無限拡張

• 症状: Non-Goals が空欄で、レビューコメントが新しい要求で埋まる
• 原因: 範囲を固定していない
• 対処: 読む人が残念がる Non-Goal を最低三つ書きます

8-5. 決定のない文書

• 症状: 背景説明は見事だが、何が決まったのか分からない
• 原因: 情報共有の文書と決定の文書を区別していない
• 対処: 文書の冒頭に「この文書が確定しようとしている決定」を一文で書きます

8-6. レビューの停滞

• 症状: ドラフトのまま三週間以上開いている文書がたまる
• 原因: 応答の遅さと決定権者の不在
• 対処: 一営業日の応答基準と決定期限を使います

8-7. チャットにしか残らない決定

• 症状: 文書には案 A、実際のコードは案 B、根拠は三か月前のチャット
• 原因: レビュー後の変更を文書に反映していない
• 対処: 実装中に設計が変わったら ADR を一枚追加することをリリース条件にします

8-8. コードより長生きして嘘をつく文書

• 症状: 新人が文書どおりに作ったのに実システムと違う
• 原因: 状態・レビュー日がなく、信じてよいか判断できない
• 対処: ヘッダの四行と廃止状態の明示を強制します

8-9. 設計ドキュメントはチームを遅くするという主張

これも論争点です。一方は執筆とレビューが着手を遅らせると言い、他方は誤った方向に三週間を燃やすコストのほうが二日の執筆より大きいと言います。軸は三つです。戻すコスト(安ければ文書より実験が速い)、関係者の数(多ければ文書なしに合意できない)、レビューの応答速度(遅い組織では文書が実際にボトルネックになる)。三つ目の軸が特に重要です。遅さの原因は文書そのものよりレビュー待ちであることが多く、だとすれば直すべきは文書ポリシーではなく応答時間です。

クイズ: 理解度を確認しましょう

おわりに

文書が残そうとしているのは説明ではなく、決定とその決定の条件です。条件が書かれていれば文書は自分で期限を知らせ、条件がなければ文書は静かに嘘になります。

実務で最も安価な改善を三つ挙げるとこうなります。第一に、ヘッダの四行(状態・最終レビュー日・担当者・決定期限)をすべての文書に強制します。第二に、すべての代替案に「この案が勝つには何が真である必要があるか」の一行を付けます。第三に、レビューの応答時間を一営業日と定め、実際に測ります。三つともテンプレートを増やさずに文書の寿命を大きく伸ばします。

形式は組織ごとに違ってよいはずです。しかし「何が決まったのか」「なぜそのときそう決めたのか」「いつ見直すべきか」の三つに答えられない文書は、形式が何であれ消える文書です。

参考資料

• Design Docs at Google — Industrial Empathy (Malte Ubl) — 設計ドキュメントの定義(実装戦略とトレードオフ中心)、「エンジニアの仕事はコード生産ではなく問題解決」という一文、標準セクション構成(Context and Scope / Goals and Non-Goals / The Actual Design / Alternatives Considered / 横断的関心事)、文書を書かなくてよい条件、文書のライフサイクル、文書が現実とずれる問題と対処を引用しました。2026-08-15 確認。
• The Standard of Code Review — Google Engineering Practices — 「全体のコード健全性を確実に改善するなら完璧でなくても承認」という原則、技術的事実が好みに勝つという原則、「Nit: 」接頭辞、合意できないことを理由に変更を放置するなという条項を、文書レビューに当てはめました。2026-08-15 確認。
• Speed of Code Reviews — Google Engineering Practices — 一営業日の応答基準、「不満の大半はプロセスを速くすることで解消される」、遅いレビューがクリーンアップとリファクタリングを萎縮させるという指摘を引用しました。2026-08-15 確認。
• 文書四類型の比較表、五つの判別質問、三段レビューの手順、コメントのラベリング、再検討条件をダッシュボードに接続する方法、八つの失敗モードは、上記資料にそのまま出てくるものではなく、この記事で整理した手順です。

関連記事

• このブログの関連記事: 文章で説得する — 設計ドキュメントと RFC が通る構造
• このブログの関連記事: エンジニアの書く力
• このブログの関連記事: コードレビューの対話術
• このブログの関連記事: 技術的負債をビジネスの言葉に
• 関連ツール: 協業 RPG

完全ガイドシリーズ

• 次の記事: API 設計完全ガイド: 戻せない決定から先に決める