設計文書とアーキテクチャ決定記録

翻訳についての注記: 本ドキュメントは英語原文 20-production-readiness/01-design-documents-and-decision-records.md を日本語に翻訳したものです。コードブロックおよびMermaidダイアグラムは原文のまま維持しています。

TL;DR

設計を証明するのはコードだが、設計を決定できるのは文書だけだ。設計文書は、アーキテクチャ上の選択をレビュー可能にする最も安い成果物であり、変更がまだ移行作業ではなく段落1つの修正で済んでいるうちに間に合う。アーキテクチャ決定記録(ADR)は、次のエンジニアが自信満々にその選択を元に戻す前に「なぜこの選択が存在するのか」を伝える最も安い成果物だ。文書化済み: 実際の設計は合理的な順序では生まれない。ParnasとClementsは、合理的設計プロセスは事後に捏造されるものだと指摘した。発見・行き止まり・制約が入り混じって届くからだ。これは省くべき理由ではなく、意図的に書き上げるべきだということの根拠になる。誰が文書を書くかが、どの創作がチームの共有モデルになるかを決める。

寿命の異なる2つの成果物は、別の仕事を担う。文書化の失敗の大半は、一方を他方の仕事に使うことから生まれる。設計文書は説得的・比較型・使い捨てであり、目的は決定がなされた時点で終わる。整理されない設計文書の山は負債だ。ADRは記述的・単一トピック・事実上永久であり、いま真実になった1つの制約を、それを生んだ力とともに記録し、編集ではなくsupersede(置き換え)で終わらせる。設計文書しか書かないチームは2四半期で「なぜ」を失う。ADRしか書かないチームは決定を正しく議論しない。ADRには、実質的な長所を持っていた却下案2つを入れる余地がないからだ。

両方の品質基準は反証可能性だ。反対する読み手は、特定の文を指して議論できなければならない。つまり形容詞ではなく数値、「we decided」ではなく名前のある担当者、明示されたスコープ境界、検討した内容と敗因の列挙、そして答えを変えるはずの証拠を1行で書く。参照設計: 本章のテンプレートは2ページの結論ブロックを冒頭に置き、レビュアーが途中で打ち切れるようにする。最低2つの真剣な代替案を必須とし、それぞれに名前と日付を付けた未解決の問いで閉じる。問いの担当者が書かれていない文書は議論の招集にすぎず、日付がある文書だけが議題になる。

文書が成果物である理由

シニアエンジニアの成果物はコード量でも図の上手さでもない。着地する前に帰結が理解されている決定の流れだ。図・プロトタイプ・スプレッドシート・ホワイトボードはいずれもその流れへの入力であり、書き残された決定だけが、その場に居なかった人によるレビュー、後から来たチームによる引用、インシデント後の監査を可能にする。組織のアーキテクチャとは実質ところ、再構築できる決定の集合だ。書き残されていないものは再炎上するか静かに破られる。どちらも高い。再炎上はKafkaについて1四半期もう一度議論するコストを、放置は誰も所有しないサポートキューを生む。

決定の変更コストは急こう配かつ不均等に上がる。だからこそ成果物は手間に見合う。

決定の状態	巻き戻しコスト	説得が必要な人
2案を比べた段落	数分。ファイルを編集	著者とレビュアー1名
レビュースレッド付きの承認済み文書	数日。新文書と移行ノート	元案を承認した全員
フラグの裏でリリース済み	スプリント1回。デュアルライトかアダプタ	所有チーム、さらにサポート教育
リリース済みで他チームが依存	1〜4四半期	消費側の全チーム、さらに移行計画
リリース済みで顧客にも見える	事実上固定	プロダクト、法務、既存インテグレーション

推論: この比率が、経験豊富なエンジニアの不均衡なほどの文書時間を説明する。案の比較に厳密さを与える1日は、表の2行目以降と比べれば安く、同じ1日をプロトタイプの磨き込みに使っても得られるものは概して少ない。「プルリクエストで決めよう」がアーキテクチャとして失敗するのも同じ理由だ。プルリクエストは実装を意図に対してレビューできるが、一度も書かれなかった意図はレビューできない。

執筆は列挙を強制する。これが実際の機構だ。「キャッシュはそれなりに新鮮であるべき」という文は、会話では無限に生き延び、紙の上で死ぬ。紙は欠けた数値を可視化するからだ。文書が表面化させる定量的な主張(要求レート、カーディナリティ、保持期間、尾の遅延目標、テナント数、爆発半径)は、すべて暗黙的な決定ではなくなる。

各成果物が担当する範囲

その成果物が可能にする決定と、合意が必要な人物で名前を呼ぶ。6つの成果物で表面のほとんどをカバーでき、不適切に使うとそれぞれ別の仕方で壊れる。

成果物	答える問い	寿命	アンブロックする決定
1ページもの/ナラティブメモ	そもそも作る価値はあるか。いくらかかるか	予算が付くか却下されるまで	この仕事に人を付けるべきか
設計文書	どの制約のもとでどの案を、どんな帰結で採るか	実装まで。以降はアーカイブ	何を作り、どう形づくるか
アーキテクチャ決定記録	いま何が真かで、代替案は何に負けたか	年単位。編集ではなく置き換え	後続の変更が許されるか
アーキテクチャ記述/システム概要	実在するものは実際どう繋がっているか	生きた文書。システムと同時にバージョン管理	オンボーディング、影響分析、監査範囲
オペレーション/ローンチレビュー	想定の負荷と現在の体制で安全に運用できるか	ローンチまで。変更時に再実施	トラフィックの前に出してよいか
ランブック	午前3時にオペレーターは何をするか	生きた文書。インシデントごとに改訂	このチームがページャを持てるか

この3つのルールが混線を止める。

• 説得と記録は混ぜない。 設計文書は議論し、ADRは述べる。ADRに生存中の案を並べた比較表があるなら、それはヘッダーを失った設計文書だ。
• 決定より長生きする文書は削除せず印を付ける。 印は3度目の再設計を止める思考の軌跡を守る。削除してよいのは、その成果物が一度も決定を運んでいない場合だけ。
• 1成果物に1担当者を冒頭に書く。 担当者不在の生きた文書はURL付きの噂、古くなった担当者付き文書は有用だ。失効期日が見えるから。

大きなシステムではこれを1つのモデルに対するビューとして形式化する。ISO/IEC/IEEE 42010は、アーキテクチャ記述がステークホルダー・その関心事・それぞれに応答するビューポイントを名指しすることを要求する。空白を隠せないようにするためだ。実務上の利点は「これはどのビューの話か」でレビュアーの不満を事前に整理できることだ。デプロイビューに対する容量指摘は範囲内、同じ指摘がデータフロービューに向けられていれば誤送信のレビューになる。

設計文書の解剖

Title, author, status, reviewers, decision owner, date
1. Verdict (max 2 pages)
   - The recommendation in one paragraph
   - Constraints that are not negotiable (contracts, budgets, deadlines, compliance)
   - Requirements with numbers, and the non-goals that were explicitly dropped
   - What this decision does NOT cover
2. Background and forces
   - Current system as it behaves, not as it was designed
   - Measured baseline: p50/p99, error rate, cost per unit, headroom
   - The specific pain, expressed as a failure the team can reproduce
3. Options considered (at least two that could have won)
   Per option: mechanism, capacity ceiling, failure behavior, migration path,
   operational burden, cost, and the one condition under which it is the right answer
4. Decision and consequences
   - Why this option wins under these constraints specifically
   - What gets worse: latency, cost, complexity, on-call load, blast radius
   - Reversibility: what would it cost to change this in 12 months
5. Plan and seams
   - Interfaces that stay stable if the decision turns out wrong
   - Milestones with observable exit criteria
   - Rollout, dual-run, and rollback mechanics
6. Open questions
   - Each item carries a name and a date, or it is not an open question
7. Appendix
   - Data for the skeptic: benchmarks, arithmetic, vendor limits, prior incidents

品質の大半は次の6つの執筆ルールが作る。

1. 結論を最初に置く。 レビュアーの注意は順位で配分される。9ページ目に推奨案へ到達する文書はチュートリアルとして読まれ、スタイル指摘が返る。
2. 数値化できない文は削除する。 「読み取りが書き込みを支配する」は「30日間の実測で読み取り8k/s・書き込み60/s、p99は41ms」に変わる。第2版は間違えうる。それがレビュー可能にする条件だ。
3. ノンゴール(やらないこと)を書き出す。 レビューでのスコープ拡大の大半は、著者がすでに捨てることにした問題をレビュアーが解こうとすることから生まれる。一度書いておけばスレッドは消える。
4. すべての代替案を最強の形で書く。 弱い説明で負けた案があるなら、決定は実際にはなっていない。ローンチ後により上手い文書でもって再燃される。
5. 帰結のセクションを正直に書く。 欠点が「なし」の設計は考えられていない。劣化に名前を付けることが文書全体の信頼買い、次の計画サイクル向けのトレードオフを事前登録する。
6. 選択だけでなく可逆性も書く。 可逆な決定は最も近い場所で速く決めるべきで、不可逆な決定こそ文書とレビューと遅延に値する。

参照設計: 採用した案ごとに「これが真なら心変わりする」行を1つ残す。サンクコスト・ドリフトに対する最も安い防御だ。将来の反証を議論から、予定された再決定に変える。

接触に耐える決定記録

ADRは今後の仕事を拘束する決定を記録する。フォーマットが意図的に地味なのは、数百件維持できる理由でもある。

ADR-0142: Order events are published through the transactional outbox

Status: accepted (2026-03-11). Supersedes ADR-0088.
Context: order state lives in PostgreSQL and three consumers need change events.
         Dual writes were attempted in Q4 and lost 11k events during a failover.
Decision: publish inside the same transaction as the state change, then tail the
          outbox table with CDC. At-least-once delivery; consumers are idempotent.
Consequences: writers pay one extra row per event and outbox lag becomes a metric
              that must be alerted on. No exactly-once end to end; the inbox pattern
              covers effect boundaries where duplicates are unacceptable.
Alternatives rejected: CDC directly from WAL (no schema coupling but no transactional
                       guarantee for derived events), dual write (empirically broken).

4つのルールがコレクションを信頼できるものにする。

• 承認後は変更しない。 訂正は置き換える新記録として届き、旧記録のステータスは superseded by ADR-nnn になる。履歴を編集すると、ADRが唯一の目的とするもの、つまり「当時チームが何を信じていたか」を知る能力を破壊する。
• 番号付きで索引付き、索引は生成する。 連番IDがあれば「なぜこれをやったのか」が1回の検索で答えになる。ディレクトリ一覧とタイトル表は、誰も維持しない分類体系に勝つ。
• 拘束する対象の隣に置く。 それを変更するプルリクエストと同じレビューに載せれば、制約のある経路の変更がADRを参照しているかをCIで問える。推論: 近接配置こそドリフトを可視化する。別ウェアハウスの記録は、最後にそれを思い出した人の頻度ちょうどで腐る。
• 90秒で読める長さに。 背景は10行以内。読むために前提知識の参照が必要なADRは設計文書の付録であり、付録は読まれない。

記録に値するかどうかは、次のどれが真かで判定する。戻すのが難しい。変更が高い。有能な新人を驚かせる。他チームの選択肢を拘束する。本気で論争になった。この3つ以上に当てはまるものは記録に値する。すでに2度議論された決定もそうだ。3回目は必ず来る。

何をしなかったかの記録も同じ価値を持つ。「サービスメッシュは採用しない。ノードあたり40k rpsでサイドカーは却下した」は漂移のクラスを丸ごと防ぎ、部外者が自前のRFCで持ち込みがちな問いに先に答える。

文書を真実に保つ

文書の腐りは規律の問題ではなくインセンティブの問題だ。書く人が、古くなったコストを支払う人であることは稀だ。3つの機構が主な仕事を担う。

• ヘッダーに失効と担当者。 生きた文書は owner、last reviewed、review cadence を持つ。レビュー期日を超えた文書は仕様ではなく有効性不明な主張として扱われ、最初の画面でそれと分かる。
• 生成できるものは生成する。 依存グラフ、API表面の一覧、トピックとコンシューマの一覧、容量数値、ダッシュボード、SLO表はコードかテレメトリから出す。手書きの写しは1四半期で間違え、その誤りが本当に重要な部分への信頼まで汚染する。
• 記録の手入れを変更に束ねる。 制約のあるインターフェースを変えるプルリクエストは影響を受ける記録を名指しし、そうでなければCIが失敗させる。これは本の章一覧がファイルから乖離しないようにする機構と同じだ。導出か検査かを必ず選び、記憶に頼らない。

これが置き換える失敗モードは「不可視の分岐」だ。1つのシステムについて3つの文書があり、それぞれ別の四半期について正しい。分岐を発見したら、負けた側は明示的に削除してポインターを残す。新しいものだけを静かに残すと、次のエンジニアが間違った方に最初に出会う。

文書化済み: ポストモーテムは、欠落した記録の最大の供給源だ。インシデントの根本原因が文書化されていない前提だったなら、是正処置は可能な限り「記録とテスト」であり、インシデントをなぞらえ直すウェアハウスページではない。書き下せない前提こそ壊れる。

レビューの機構

レビューは締切のある決定手続きであり、壊れる仕方は正確に2つ: 検証が少なすぎるか、終わらない検証か。どちらも「意見を求める」のではなく依頼を明示することで直る。

依頼	レビュアーが負うもの	典型的な遅延
「問題設定は間違っていないか」	スコープと要求に関する指摘のみ	24時間
「AかBを選んで。A寄りです」	意見ではなく立場。無反応は同意を意味する	48時間で担当者が決定
「何を壊せるか探して」	失敗モード、容量上限、移行の欠落	司会者を指名して3日
「ローンチ承認」	領域ごとのチェックリスト証拠: 容量・セキュリティ・可観測性・コスト	リリース方針に従いブロッキング

レビューを安く保つ4つの機構は次のとおり。

1. 非同期が先、会議は最後。 書かれた文書への書かれたコメントなら3人が並列に考えられる。会議では13人が最初に話した人に同意する。カレンダーは生き残った1つの未決のために使い、招待状にはまさにその1件だけを書く。
2. すべてのコメントに重大度ラベル。 ブロッカー(障害かデータ損失を起こす)、メジャー(明記された要求を満たさない)、nit(スタイル)、curious(未答の問い)。ラベル選びを強制されるとレビュアーは論文を書きにくくなり、著者は意図を推測せずにトリアージできる。
3. 文書に添付される決定ログ。 解決したスレッドは1行になる。何を、誰が、どの証拠で決めたか。ここからADRが生まれることが多い。そして再炎上を終結させる成果物がこれだ。
4. 決定者とエスカレーション経路を指名する。 合意がないなら責任のある担当者が決め、異議を記録する。「反対しても従う」は、反対が先に書き残されていなければ機能しない。書かないと同じ議論は18か月後に新人と一緒に戻ってくる。

推論: レビュー遅延はスケジュール上の煩わしさではなく設計への入力だ。決定に5日のカレンダーがかかり巻き戻しが1日なら、その決定はチームへ委譲すべきだ。記録に1時間かかり、取り消しに4四半期かかるなら、システム横断の文脈を持つレビュアーの前に出すべきだ。

文書文化の失敗モード

アンチパターン	症状	修正
文書の劇場	長い。決定なし、日付なし、担当者なし	結論と依頼のない文書を差し返す
ADRスパム	「Postgresを使った」を再述する記録が200件	難しい/高い/驚かせる/論争になった決定だけを記録する
形だけのレビュー	コメントゼロの数分で承認	承認ごとにリスクを1つ名指しか「X,Y,Zではリスクなし」を要求
あしあと文書	決定を正当化するために後から書かれる	日付とステータスを正直に。事後的な記録はその旨を明記
委員会による設計	誰も提案していないハイブリッドに案が溶ける	担当者が1人で決め、異議は平均せず記録する
テンプレートの崇拝	全セクションが埋まっているが議論がない	結論と案の比較だけを見る。未使用セクションは削除
永遠の下書き	実装されながら11か月間 draft	ドラフト状態は実装を止めるか、失効させる
プロトタイプによる決定	最初のデモが議論に勝つ	2つ目のプロトタイプの前に比較表を必須にする
プルリクエストの部落決定	根拠がクローズ済みスレッドにしかない	今後のコードを拘束する決定は記録へ昇格させる

共通する根本原因は、文書を設計作業ではなく報告として扱っていることだ。報告は網羅性で評価され、著者のマネージャーに還元される。設計文書は「決定を変えたか」で評価され、1年後にそのシステムを運用する人に還元される。文書数を測るチームは量を得る。帰結のセクションを読むチームは決定を得る。

機能しているかの測定

方向性のシグナルだけを置き、いずれも個人向けのダッシュボードに載せない。

• 巻き戻し率: 承認された決定のうち2四半期以内に置き換えられた割合はどれか。極低いかつ手戻りが多いなら誰も書いていない。高いかつシステムが安定しているなら、安く探索できている。
• 問いから決定までの時間。全件平均ではなく、最も高価な10決定だけを追いかけるとよい。
• 予見済みインシデント率。直近のSev-1 10件のうち、制約が書かれていて無視されたものと、誰も書かなかったものはそれぞれいくつか。前者はレビューの質を、後者は文書のカバレッジを示す。修正は別ものだ。
• レビュー遅延と手戻り率はセットで見る。レビューが速いのに手戻りが増えているなら、承認は儀式になっている。

推論: これらは指標として昇格させれば悪用される。巻き戻し率を最適化するチームは置き換えの記録をやめ、カバレッジを最適化するチームは文書の劇場を生む。それは1つ前の表の2行上の失敗モードだ。

主要な要点

1. 合理的な説明は意図的に書く。設計の発見は散発的で、誰が文書を書くかがチームの共有モデルを決める。
2. 説得と記録を分ける。設計文書は案の間で議論して期限切れになり、決定記録はいま真であることを述べ、編集ではなく置き換えで終わる。
3. あらゆる主張を反証可能にする。読み手が二通りに解釈しうる文には数値・出典・明示的な仮定のいずれかを付ける。
4. 勝ちえたはずの代替案を2つ以上、加えてノンゴールを書く。案が1つの文書は進捗報告であり、レビューもそう扱われる。
5. 帰結と可逆性を記録する。「どの制約のもとでどの案が勝つか」という一文が次の設計を救う。
6. 記録は短く、番号付き、変更不可、索引付き、そして拘束するコードの隣に。長い記録は読まれ、遠い記録は見つからない。
7. 生成できるものは生成し、残りは変更に束ねる。担当者、レビュー日、このプルリクエストがどの記録に従うかを問うCIチェック。
8. レビューは決定手続きとして回す。明示的な依頼、重大度ラベル、決定者の指名、書かれた決定ログ。会議は13の意見ではなく、生き残った1つの対立を解決する。
9. ポストモーテムを欠落記録の主供給源として扱う。壊れた未文書化の前提はすでにインシデントで代価を払済みだ。
10. この実践を巻き戻し率・決定遅延・予見済みインシデント率で判断する。文書の量で決して測らない。

参考文献

• Parnas, D., and Clements, P. "A Rational Design Process: How and Why to Fake It." IEEE Transactions on Software Engineering, 1986 — 設計は反復的な推測で進み、記録された合理的構造は意図的に構築される成果物だという元の議論
• Nygard, M. "Documenting Architecture Decisions." 2011 — ほぼすべてのADRツールの子孫となった書式。文脈・決定・帰結、そして置き換えによる変更不可性
• ISO/IEC/IEEE 42010:2022, "Systems and software engineering - Architecture description." — ステークホルダー、関心事、ビューポイントと、そのどれを対象とするかを記述に要求する規則
• Brown, S. "The C4 Model for Visualising Software Architecture." 2011 onward — 図の高度設定と、1枚の図が3つのスケールの問いに答えられない理由
• Bryar, W., and Carr, B. "Working Backwards." St. Martin's Press, 2021 — スライドではなくナラティブメモ、論を散文で書かせる6ページ構成
• Sharma, T., Bosworth, A., Zaharia, M., and Chakraborty, A. (eds). "Software Engineering at Google." O'Reilly Media, 2020 — 設計文書、コードレビューの規範、担当者を持つ成果物としての文書工学
• Ousterhout, J. "A Philosophy of Software Design." 2nd ed. Yaknyam Press, 2021 — 設計決定が返済するか積み上げるかの対象としての複雑性、挙動ではなく意図の記録としてのコメント
• Skelton, M., and Pais, S. "Team Topologies." IT Revolution Press, 2019 — 決定に委員会ではなく所有チームが必要であることを示す相互作用モードと認知負荷