1.6 意思決定記録

概要と動機

意思決定記録とは、重要な決定を、その文脈と結果とともに捉えた文書です。最もよく知られた形はアーキテクチャ決定記録(ADR)で、アーキテクチャ上重要な一つの選択、それがなぜ行われたか、そこから何が続くかを記録する、短く、できれば不変のメモです。プロジェクトの記録全体は決定ログ(ADL)であり、それを維持する規律はアーキテクチャ知識管理(AKM)の一部です。本章は1.5章の意思決定とガバナンスの実践を土台とし、意思決定記録を大規模にどう書き、保管し、維持するかに焦点を当てます。

動機は単純で、痛い目に遭って学ぶことになりがちです。長寿命のシステムで最も高くつく問いは、数か月あるいは数年後に、その場にいなかった人々から発せられる「いったいなぜこんなふうに作られたのか」です。コードは、システムが何をするかを示します。テストは、それが機能することを示します。しかしどちらも、検討して退けた代替案ではなくなぜこの道を選んだのかを捉えません。意思決定記録がなければ、その理由は人の入れ替わりとともに蒸発します。チームは決着済みの問いを蒸し返し、良い決定を悪い理由で覆し、あるいは悪い決定を恐れから維持します。意思決定記録は、理由を保存する、未来への安上がりな手紙です。

大規模なチームにとって、これは記憶の補助であると同時に調整のツールです。大企業は、重なり合う選択をする数十のチームを抱えています。共有された決定ログは、あるチームが苦労して得た理由を再利用可能な資産に変え、互換性のない食い違う決定を防ぎます。政府や規制された環境では、意思決定記録はほぼ必須です。監査人、監督機関、後任の契約者はみな、アーキテクチャ上重要な要求と、それに対してなされた選択を結ぶ、追跡可能な理由を必要とします。よく維持された決定ログは、保証し監査できるシステムと、できないシステムとを分けることがよくあります。

主要原則

何だけでなくなぜを記録します。 文脈と退けられた代替案が要点です。
一つの記録に一つの決定。 各記録を具体的で自己完結したものに保ちます。
包括的で使われないものより、小さく軽いもの。 存在する一枚の記録は、書かれない報告書に勝ります。
すべてにタイムスタンプを付けます。 コスト、制約、ベンダーは変わります。主張には日付を付けます。
現実的には、生きたログを好みます。 不変性は理想ですが、実際には日付付きのメモで修正します。
略語より言葉。 「ADR」より「決定」のほうが、貢献を招きます。
決定を発見可能に、可能ならテスト可能にします。 適切な瞬間に適切な記録を表に出し、フィットネス関数で保証します。

推奨事項

本質的な構造を捉える

良い意思決定記録には、いくつかの本質的なセクションがあります。自分で発明するのではなく、既知のテンプレートを適応させてください。

タイトル: 短い現在形の命令形の句(「台帳にPostgreSQLを使う」)。
ステータス: 提案中、承認済み、置き換え済み、非推奨。
文脈: この決定を必要とする状況、力学、ビジネス上の優先事項、制約。それが扱うアーキテクチャ上重要な要求を含めます。
決定: 下された選択を、平易に述べます。
結果: 何が楽になり何が難しくなるか、引き起こされる後続の決定、受け入れたリスク。

人気のあるテンプレートには、Michael Nygardのもの(シンプルで広く採用されている)、TyreeとAkermanのもの(より精巧で、重み付けされた代替案がある)、MADR(Markdown Any Decision Records、選択肢とその長所短所に強い)、Y-statements(一文の構造化形式)があります。記録が比較可能になるよう、組織で一つに標準化してください。コピー&ペースト用のテンプレートは12.3章を参照してください。

具体的で、日付があり、ほぼ不変な記録を書く

各記録は、ちょうど一つの決定について書きます。個々の主張、特に移ろいやすいもの(価格、スケーリングの数値、ベンダーの機能、ライセンス条件)にタイムスタンプを付けます。理論上、記録は不変であるべきです。決定が変わるときは、古いものを置き換える新しい記録を書き、履歴を保存します。実際には、多くのチームが生きた文書のアプローチのほうがうまくいくと感じています。既存の記録に新しい情報を、日付スタンプと、それが決定の後に届いたというメモとともに挿入します。どちらも正当です。不変スタイルは監査証跡に強く、生きたスタイルは日々のチームの知識に向いています。意図して選び、一貫させてください。

記録を仕事のある場所に置く

意思決定記録を、コードと並べてバージョン管理に置きます。決定ごとに一つのMarkdownファイルを収めたdecisions/(またはadr/)ディレクトリで、小文字でダッシュ区切りの命令形の動詞句で名前を付けます(choose-database.md、format-timestamps.md)。これにより履歴、レビュー、差分が無料で得られ、理由がそれが説明するものの隣に保たれます。チームがウィキ、Googleドキュメント、Jira風のトラッカーを好むなら、代わりにそれらを使います。ツールよりも習慣のほうがはるかに重要です。軽量なコマンドラインツール(adr-toolsなど)で、記録の雛形作成と索引化ができます。

「決定」と名付け、アーキテクチャを超えて広げる

多くのチームからの実践的な洞察ですが、ラベルは重要です。「アーキテクチャ」という言葉に反発する開発者やマネージャーもいて、「記録」は後付けの事務作業のように感じられることがあります。ディレクトリを単に「decisions」と改名するだけで、スイッチが入ることがよくあります。チームは、ベンダーの選択、計画の決定、スケジュールの決定、データやコンプライアンスの決定まで、同じテンプレートで記録し始めます。人は略語より言葉から速く学び、枠組みが「必須の書類を提出する」ではなく「未来のチームメイトの思考を助ける」であるとき、より多く貢献します。

ライフサイクルとガバナンスを定義する

意思決定記録がスケールするには、周辺のプロセスに合意します(ここは1.5章のガバナンスが実践と出会う所です)。

誰が起票でき、何がそれを正当化するか: 通常は事情に通じた貢献者なら誰でも。将来の開発者がなぜを必要とするときに記録を起こし、リスクが低く、自己完結的で、すでに文書化されている選択は省略します。
ライフサイクル: 開始 → 調査 → 評価 → 実装 → 維持 → 廃止のような単純な流れで、段階間を移るための受け入れ基準(問題の明確化、代替案の検討、トレードオフの文書化、ステークホルダーとの協議)を伴います。
役割: 提案者、調査者、レビュアー、承認者、そして記録を定期的に(少なくとも年1回)見直し、最終的な廃止を進める責任あるメンテナ。
ガバナンス: 合意、対立、エスカレーション、拒否権がどう機能するか、およびコンプライアンス上の制約。行動への偏りや反対しつつコミットするといった原則に拠り、より重いプロセスは、不可逆で影響範囲の大きい(「一方通行の扉」)決定のために取っておきます。

決定をテスト可能に、発見可能にする

意思決定記録は決定を文書化し、フィットネス関数はそれを保証します。継続的インテグレーション(CI)で実行される自動チェックで、決定が依然として成り立っているかを検証します(「すべての状態変更はイベントを発行しなければならない」「どのモジュールもこれらの境界を越えてインポートしてはならない」。ArchUnitなどのツールを使います)。これにより、ガバナンスは定期的な手作業のレビューから、継続的でスケーラブルな執行へと変わり、規制や監査の目標にとって特に価値があります(3.1、4.6、8.5章)。そして適切な記録を適切な瞬間に表に出します。開発者が統治対象のコードに触れたときに、関連する決定をプルリクエストに添えるツールは、人がドキュメントフォルダを読むことを期待するよりはるかに優れています。

トレードオフ: 長所と短所

選択	長所	短所
軽量なADR(Nygard/MADR)	書くのが速く、実際に書かれる。儀式が少ない	重大で論争的な決定には厳密さが足りない
重量級のテンプレート(Tyree-Akerman)	重み付けされた代替案。大きく高価な選択に強い	遅い。日常的な記録を妨げうる
不変 + 置き換え	きれいな監査証跡。履歴が保存される	記録が増える。読者は連鎖をたどる必要がある
生きた文書(日付付きの修正)	現在の単一の信頼できる情報源。維持しやすい	監査上の説明が弱い。静かな編集のリスク
リポジトリ内のMarkdown	バージョン管理され、レビュー可能で、コードの隣にある	開発者以外には親しみにくい
ウィキ / ドキュメントツール	すべての役割がアクセスできる	履歴とレビューが弱い。コードとずれる

中心的な緊張は厳密さと採用です。誰にも使われない最も厳密な仕組みは何も記録しません。皆が使う最も軽い仕組みは価値を積み重ねます。軽量を既定とし、重いプロセスは、高価で元に戻しにくい少数の決定のために取っておきます。

チームで議論すべき問い

それが統治するコードに開発者が触れた瞬間に、適切な意思決定記録が届くようにするには、誰も開かないフォルダに眠らせないために、どうしますか。書き込み専用のログは、振る舞いを決して変えない理由を記録します。これは意思決定記録が失敗する最も一般的な形です。存在はするのに、重要なときに誰も読まないのです。相反する考慮は労力です。記録を自動的に表に出す(統治対象のコードを編集したときにプルリクエストに添える)には、ウィキやドキュメントフォルダにはないツールへの投資が必要だからです。議論には証拠を持ち込んでください。最近、誰かが決着済みの問いを覆したり蒸し返したりしたとき、関連する記録はその瞬間に発見可能でしたか、それとも埋もれていましたか。数十のチームを抱える大きな組織では、発見可能性こそが、あるチームが苦労して得た理由を、私的なアーカイブではなく再利用可能な資産に変えます。記録をコードの隣のバージョン管理に保存し、プルリクエストのフローに接続して、仕事が行われる場所に記録が現れるようにするかを決めてください。
各記録の責任あるメンテナは誰で、ログが確信に満ちた誤情報に朽ちていくのを何が防ぎますか。 決定ログの危険な失敗モードは、空のフォルダではなく、コスト、ベンダーの機能、制約が何年も前に静かに陳腐化した記録でいっぱいのフォルダです。すべての記録には、周期的に(少なくとも年1回)それを見直し、置き換えや廃止を進める責任ある所有者が必要です。さもなければ、ログは人々が選択的に引用し、ほとんど信頼しない民間伝承に腐ります。証拠を持ち込んでください。記録のうち日付のないものがいくつあるか、いくつが、その後変わったベンダーや価格を述べているか、それぞれが最後にいつ見直されたか。政府や規制された環境では、これはより鋭く効きます。不変で置き換えの連鎖が追える記録こそが、監査人と後任の契約者が追跡可能な理由として頼るものだからです。ライフサイクルを明示的に決め、移ろいやすい個々の主張にタイムスタンプを付け、メンテナを割り当てて、ログが墓場ではなく生きた資産であり続けるようにしてください。
すべてのチームで一つのテンプレートに標準化すべきですか。そして、最も賭け金の高い決定は実際にどれほどの厳密さを必要としますか。 比較可能性は本物の利点です。すべてのチームが同じ形(Nygard、MADR、またはそれに類するもの)を使えば、新しいチームは三つの先行する記録を見つけて、一か月の議論ではなく一日の午後で理由を採用できます。中心的な緊張は厳密さと採用です。誰も使わない最も重いテンプレートは何も記録せず、皆が使う最も軽いものは価値を積み重ねるからです。証拠を持ち込んでください。記録は実際に書かれているか、そして別に、大きく、論争的で、高価な決定のうち、軽量な形式が代替案の比較を飛ばしたために分析が不十分だったものはあるか。チームをまたいで重なり合う選択を調整する大企業では、共有テンプレートと検索可能な索引が、食い違う互換性のない決定を防ぎます。一般的な場合は軽量を既定とし、重み付けされた代替案を伴うより重い形式に値する一方通行の扉の決定を、あらかじめ合意しておきます。
意思決定記録の起票を実際に正当化するものは何で、ある選択には不要と言う権限は誰にありますか。 ハードルを高くしすぎれば、重要な選択の背後にある理由が蒸発します。低くしすぎれば、ログは人々が本当に必要とする記録を埋もれさせる些事で満たされます。大きな組織では、不明確な閾値は、各チームが独自に即興することを意味し、カバー率にむらが生じ、記録がないことが重要でない決定を意味するとは誰も信頼できなくなります。議論には証拠を持ち込んでください。記録されたが、その必要がなかった最近の決定と、記録されず、のちに再発見のコストを払わされた痛い決定です。平易なテストに合意してください。たとえば、将来の開発者がなぜを必要とするときに記録し、リスクが低く、自己完結的で、すでに文書化されている選択は省略する、などです。規制された環境や政府では、勘定が変わります。監査の命令が、チームが書く価値があると判断するかどうかにかかわらず、アーキテクチャ上重要なすべての要求について記録を要求することがあるので、どの決定が譲れないかを最初に名指ししてください。
あなたの記録は、決定の瞬間に捉えられた本物の理由ですか。それとも、義務を満たすために後から書かれた書類仕事ですか。 チケットを閉じるために事後に作られた記録は、選ばれた選択肢を美化し、実際に比較された代替案を静かに省いてしまいがちです。それはまさに、将来の読者が最も必要とする情報です。相反する圧力は本物です。決定の前や最中になぜを書くことは出荷より遅く感じられ、退けた道を書面で認めることには、一部のチームが欠いている心理的安全性が要るからです。最近の記録のサンプルを持ち寄り、文脈と退けられた代替案が、本物の熟慮に読めるか、後付けの正当化に読めるかを正直に問うてください。大きなチームでは、空虚な記録は、ないよりも悪いものです。ログは信頼できないと人々に教えるからです。企業や政府の監査では、この区別は鋭く効きます。監督機関と後任の契約者は、本当に検討されたことを反映した理由に依存しており、芝居のように読める記録は、ログが提供するために存在する保証を損なうからです。
定期的な手作業のレビューが違反を見つけてくれると信じるのではなく、最も賭け金の高い決定のうち、どれを自動のフィットネス関数で保証できますか。意思決定記録は選択を文書化しますが、数年にわたって数十人の開発者がコードに触れるうちに、その選択が静かに侵食されるのを防ぐのは、継続的インテグレーションで実行される自動チェックだけです。トレードオフは投資です。フィットネス関数(ArchUnitなどのツールを使う)を書き維持するにはエンジニアリングの時間がかかり、多くの決定、特にプロセスやベンダーの選択は、機械的にテストすることがそもそもできません。証拠を持ち込んでください。境界に関する決定(モジュール依存、イベント発行、データアクセスの規則)のうち、静かに破られ、レビューの終盤や本番でようやく見つかったものはどれか。多数のチームを抱える大企業では、フィットネス関数は、ガバナンスを中央のボトルネックから、全員を遅くせずにスケールする継続的な執行へと変えます。規制された環境や政府では、自動化された常時稼働のチェックは、レビューの署名よりはるかに強い監査証拠です。誰かがかつて承認したことではなく、決定が今日も成り立っていることを証明するからです。

セクター別の視点

スタートアップ。 習慣だけに絞ってください。メインリポジトリのdecisions/フォルダと、将来の自分が疑問に思うであろう判断をするたびに書く、二つのセクション(文脈と選択)のメモです。ライフサイクル、役割、承認者はすべて省きます。維持できないプロセスは、放棄するプロセスだからです。最初の採用者が「なぜこのように作られているのか」と尋ねずに済む一つの記録が、すでに実践全体の元を取っています。

小規模事業者。 専任のアーキテクトがおらず時間もないので、専用ツールを買うのではなく、チームがすでに働いている場所、つまりウィキ、共有ドキュメント、リポジトリのどれにでも記録を置いてください。ツールよりも習慣のほうがはるかに重要なので、障壁を下げます。ディレクトリをadrではなくdecisionsと名付け、ベンダーや自作か購入かの選択を、技術的な選択と同じ息で捉えます。外部の契約者に頼る場合、なぜあるベンダーやプラットフォームを選んだかの短い日付付きの記録は、あとで誰も説明できない選択に縛られることへの安上がりな保険です。

大企業。 仕事は多数のチームにわたる調整です。一つのテンプレートに標準化し、検索可能なチーム横断の索引を公開し、重要な境界に関する決定をフィットネス関数で裏付けて、違反がレビューを待たずにビルドを失敗させるようにします。各記録に、見直しの周期とともに責任あるメンテナを割り当て、ログが民間伝承に朽ちるのではなく生きた資産であり続けるようにします。うまくやれば、難しい選択についてのあるチームの理由は、次のチームが蒸し返す代わりに午後で採用できる資産になります。

政府。 調達規則、透明性、公的な説明責任が、意思決定記録をほぼ必須にします。アーキテクチャ上重要なすべての要求に、不変で置き換え済みの記録を求め、それぞれが選択を、それが満たす命令やコンプライアンス統制に結びつけるようにして、監督機関が再構成ではなく追跡可能な理由を見つけられるようにします。公共システムは複数年、複数ベンダーにわたる寿命を持つので、よく維持されたログは、後任の契約者がシステムがなぜその形なのかを理解し、決着済みの所を蒸し返さずに作業を続けられるようにするものであることがよくあります。

事例

スタートアップ。 5人のスタートアップは、メインリポジトリに素朴なdecisions/フォルダを加え、将来の自分たちが疑問に思う判断を誰かがするたびに、二つのセクション(文脈と選択)のメモを書きます。ライフサイクルも役割も承認者もありません。コードの隣になぜを書く習慣だけです。六か月後に最初の採用者が加わると、彼女はフォルダ全体を一時間で読み、「なぜこのように作られているのか」と尋ねなくなります。この軽量なログは一件あたり数分しかかからず、チームが大きくなるずっと前から効いてくる、再発見の税から彼らを救います。

大企業。 30のエンジニアリングチームを抱える小売業者は、各リポジトリでMADR形式の記録を標準化し、検索可能な中央索引を加えます。新しいチームが「モノレポかマルチレポか」に直面したとき、文脈と結果を備えた三つの先行記録を見つけ、一か月の議論ではなく一日の午後で理由を採用します。重要な境界に関する決定(サービスのオーナーシップ、データアクセス規則)はArchUnitのフィットネス関数で裏付けられるため、違反はレビューで拾われるのではなく、ビルドを失敗させます。これは、中央のボトルネックなしにスケールするガバナンスです。

政府。 給付システムを近代化するある機関は、アーキテクチャ上重要なすべての要求にADRを求め、それぞれが決定を、それが満たす命令やコンプライアンス統制(アクセシビリティ、データの所在地、監査可能性)に結びつけます。記録は不変で置き換えられ、監督のレビューを満たす追跡可能なログを生みます。決定的なことに、それは後任の契約者がシステムがなぜその形なのかを理解することも可能にし、公共プログラムに典型的な複数年、複数ベンダーの寿命にわたる連続性を保ちます(4.6、10.4章)。

ビジネスケース: 動機、ROI、TCO

意思決定記録は書くのに数分、レビューにさらに数分かかります。見返りは、避けられた再決定のコストと、避けられた誤った覆しのコストです。どちらも、長寿命のシステムでは大きく、繰り返し発生します。チームが決着済みの問いを蒸し返すたび、あるいは背後の制約を誰も覚えていないために健全な選択を覆すたびに、シニアエンジニアの時間で、しばしばインシデントで、代償を払います。決定ログは、その繰り返される税を、一度限りの書き込みに変えます。

総所有コストの点で、意思決定記録は、保てる最もてこの効くドキュメントの一つです。最も人の入れ替わりに敏感な資産、すなわち理由を狙うからです。オンボーディングは速くなります(新しい採用者はコードだけでなくなぜを読みます)。モダナイゼーションはより安全になります(3.6章: 本質的な決定と付随的な決定を見分けられます)。監査は安くなります(証拠がすでに存在します)。保たないコストはどのダッシュボードにも見えず、退職のたびに静かに積み重なります。経営層に訴えるには、最近の高価な再発見、あるいはインシデントを起こした覆された決定を挙げ、その修正を導入するコストがほぼゼロであることを指摘してください。

アンチパターンと落とし穴

なぜなしに何を記録する: 文脈と退けられた代替案という肝心の点を省くこと。
事後の書類仕事: 思考のためではなく義務を満たすために書かれた記録。空虚に読め、誰も信頼しません。
複数の決定を詰め込んだ巨大文書: 誰もたどれず、きれいに置き換えられない一枚の巨大なページ。
日付のない主張: かつて真だったコストや制約が、時間を超えたものとして示されること。
静かな編集: 日付付きのメモなしに決定の履歴を変更し、監査証跡を破壊すること。
書き込み専用のログ: 作られても関連する瞬間に表に出されず、振る舞いに影響しない記録。
略語による門番: 「ADR」や「アーキテクチャ」にこだわり、貢献を妨げること。
ライフサイクルなし: 見直されず、置き換えられず、廃止されない記録が、誤情報に朽ちること。

成熟度モデル

レベル1(開始): 決定は人々の頭、チャットのスレッド、コミットメッセージの中にあり、記録は反応的で場当たり的で、理由は人の入れ替わりで日常的に失われます。
レベル2(発展): 一部のチームは、個人が思い出したときに、さまざまな形式とテンプレートで記録をつけます。実践はチーム間で一貫せず、共有のログ、命名、プロセスはありません。
レベル3(標準化): 単一のテンプレート、リポジトリ内の保管、定義されたライフサイクルとガバナンス(起票/省略の基準、役割、見直しの周期)が文書化され、組織全体で一貫して適用されています。記録は静かに編集されるのではなく、見直され、置き換えられます。
レベル4(管理): 決定ログはベースラインに対して測定されます。カバー率(アーキテクチャ上重要な決定のうち記録を持つものの割合)、鮮度(周期内に見直された記録の割合と、日付のない、または古い主張の数)、発見可能性(関連する記録が、統治対象のコードを変更した開発者に実際に届いた頻度)です。責任あるメンテナは、これらの指標に基づいて行動し、逸話ではなく証拠に基づいて古い記録を置き換え、カバー率のギャップを埋めます。
レベル5(オーケストレーション): 検索可能なチーム横断の決定ログが日々の仕事に統合されています。関連する記録は、それが統治する変更に自動的に表れ、重要な決定は継続的インテグレーションのフィットネス関数で保証され、ログはオンボーディング、モダナイゼーション、監査を支える生きた資産として機能します。組織は実践そのものを継続的に改善し、システムとその制約が変わるにつれて記録を廃止、置き換え、再スコープし、決定のポートフォリオが増えるにつれて厳密さを投じる場所を再配分します。

議論のためのアイデア

あなたのチームが最後に、元の理由を誰も覚えていなかったために覆したり蒸し返したりした決定は何でしたか。
adr/ディレクトリをdecisions/に改名すると、誰が貢献し、何が記録されるかは変わるでしょうか。
あなたの重要な決定のうち、今日、自動のフィットネス関数で保証できるのはどれですか。
不変 + 置き換えか、生きた文書か。あなたの監査義務と文化に合うのはどちらで、それはなぜですか。
新しい採用者(あるいは後任の契約者)は、現在、あなたのシステムがなぜその形なのかを、どうやって知りますか。
あなたのチームで、意思決定記録の起票を正当化するものは何で、起票しないことを正当化するものは何ですか。

要点

意思決定記録は、一つの重要な決定を文脈と結果とともに捉えます。何だけでなくなぜです。
記録は具体的で、タイムスタンプがあり、軽量に保ちます。一つのテンプレート(Nygard、MADRなど)に標準化します。
コードの隣のバージョン管理に保存します。貢献を広げるため「decisions」と名付けることを検討してください。
ライフサイクルとガバナンス(起票/省略の基準、役割、見直しの周期)を定義します。重いプロセスは一方通行の扉の決定のために取っておきます。
決定を、変更の瞬間に発見可能にし、可能なら、フィットネス関数でテスト可能にします。
ROIは、避けられた再発見と誤った覆しのコストです。TCOの論拠は、人の入れ替わり、モダナイゼーション、監査が重要な所で最も強くなります。1.5章(意思決定とガバナンス)と3.1章(アーキテクチャの基礎)を参照してください。

参考文献とさらなる読み物

Michael Nygard, “Documenting Architecture Decisions” (2011): the foundational lightweight ADR.
MADR: Markdown Any Decision Records project (adr.github.io/madr).
Jeff Tyree and Art Akerman, “Architecture Decisions: Demystifying Architecture” (IEEE Software, 2005).
Olaf Zimmermann, “Y-Statements” and “Architectural Decision Making” (ozimmer.ch).
Joel Parker Henderson, Architecture Decision Record (ADR): templates, examples, and teamwork guidance (github.com/joelparkerhenderson/architecture-decision-record).
ThoughtWorks Technology Radar: “Lightweight Architecture Decision Records.”
Neal Ford, Rebecca Parsons, Patrick Kua, Pramod Sadalage, Building Evolutionary Architectures (fitness functions).
AWS Prescriptive Guidance, “ADR process”; Red Hat, “Why you should use ADRs.”
Wikipedia, “Architectural decision” and “Architecturally significant requirements.”