RFCからADRへ：決定に至る過程とその理由を保持する

誰も再構築できなかった決定

新しいテックリードは合理的な質問をします：なぜすべてのサービスがそのキューを通じて請求システムと通信するのですか？ADRがあります — ADR-014、4文、11ヶ月前に書かれました。文脈：「信頼できる請求統合が必要でした。」決定：「キューを使用する。」結果：「いくつかの追加のレイテンシ。」技術的には記録です。何も答えていません。

あなたはそこにいたので、ADR-014が言っていないことを知っています：2つのSlackチャンネルと熱いPRスレッドでの3週間の議論；その後引き上げられたレート制限のために負けた同期APIオプション；今は誰も見つけられないベンチマークで返答されたスタッフエンジニアの異議。議論は行われました。記録はその後、金曜日に1人の記憶をもとに書かれました。

これは、真に良い実践の文書化された、ほぼ普遍的な失敗モードです。AWSの指示的ガイダンスとMicrosoftのWell-Architectedドキュメントの両方がADRを推奨しており、両者ともその苦痛を指摘しています：それらを最新の状態に保つには時間がかかり、チームや選択肢が増えるにつれて管理が複雑になります。根本的な原因は構造的です：議論と記録が異なる場所に存在するため、記録は常に情報が失われた転写になります。解決策は、それらを同じ場所にすることです。この実践はエンジニアリング特有のものでも、ADR特有のものでもありません。Googleは設計文書を要求します — 問題、提案されたアプローチ、考慮された代替案、トレードオフ — これは重要な技術作業が始まる前に書かれ、レビューされるべきものであり、これは会社自身のSoftware Engineering at Googleに示された実践です。これはADRと同じ規律であり、1ステップ早く適用されます：ADRは設計文書が導き出した選択を記録します。両者は同じ理由で同じように失敗し、両方とも同じ動きで修正されます — 記録が存在する場所で議論を行い、その後に一方を他方に転写するのではなく。以下のすべてのステップは、両方のアーティファクトをカバーしていると考えてください。

なぜADRsは腐るのか

ADRコミュニティ自身の資料からの一文が全体の診断を示しています：RFCは通常、合意に達することに関するものであり、ADRは達成された合意を記録します。 二つのアーティファクト、二つの瞬間 — そしてそれらの間のすべてが漏れ出します。「明らかに」間違っている代替案は記録されず（明らかでなくなるまで）。最終的なデザインを形作った異議は、閉じたスレッドのPRコメントとしてのみ生き残ります。コンテキストセクションは最後に、最悪の形で、負けた人によって書かれます。決定を生み出すべき会議は、要約を生み出すだけで、決定を持続可能にする理由付け — 決定品質チェーン全体が依存するもの — は、まさに転写によって落ちてしまいます。

ステップ 1–3: 提案、文脈、選択肢

1. 1提案を根本的な主張として述べる — 提案された決定、質問ではなく: "すべての請求書の書き込みを耐久性のあるキューを通じてルーティングします." この文は将来のADRのタイトルです。 チェックポイント: 根本が存在し、1文で、提案者によって作成されています。
2. 2コンテキストは別々のプロ・アーギュメントとして。 決定を必要とする各要因 — 信頼性要件、請求システムのレート制限、監査義務 — はそれぞれ根本的な議論の一部です。単一の「コンテキスト」段落は挑戦されることはありませんが、3つの別々のコンテキスト主張はそれぞれ個別に疑問を呈したり、確認したり、否定したりすることができます。 チェックポイント: ≥2のコンテキストアーギュメント、それぞれが1つの要因。
3. 3すべてのオプションには独自のノードがあります。 キュー、同期API、バッチジョブ — 兄弟の引数、それぞれに独自の利点と欠点があります。利点/欠点は親に対して相対的であるため、オプションの欠点はそのオプションに付随し、決定には付随しません。拒否することを期待するオプションも含めてください：拒否された兄弟が来年の「なぜ私たちはただ…しなかったのか」という問いに答えます。チェックポイント：読者が尋ねる可能性のあるすべてのオプションが存在します。

ステップ4–6: 記録を残すRFCラウンド

今、レビューラウンドです — 通常、チャット、コメント、廊下に散らばる部分です。ここでは、レビューアとオプションの著者との間で4ターンの対話として構成された3種類の交換が行われます。

ステップ7: 決定する — そして評価が何でないか

意思決定者は選択肢に評価を付けます：それぞれにラベル付けされた評価があります。この分布は本物の証拠です — その部屋がどのように立っていたか、記録に残っているか、電話をかける前のことです。しかし評価は決定ではありません。名前のある人間が最終的に決定し、その決定が分布に反する場合、決定ノードでその説明が行われます。（その名前のある人間が誰であるべきか、そして議論の前に役割を割り当てる方法は独自の分野であり、意思決定権のチュートリアルを参照してください。）

ステップ8–9: 書く必要のなかったADR

ここに報酬があります。記録は後から書く文書ではありません — それは選択されたオプションのノードと、それに既に付随しているすべてのものです：コンテキスト引数（Context）、却下された兄弟（Options Considered）、完了したチェーン（議論、著者と共に）、評価（部屋の状況）、およびその根拠を持つ決定引数（Decision）。何も書き起こされないため、書き起こしによって失われるものはありません。

1. 1受け入れている結果を記録してください。 既知の欠点 — 追加のレイテンシー、キューの運用負担 — は、選択されたオプションの子供として続き、決定者によって認識されます。それらを書き留めることが、好みではなく決定であることを示します。チェックポイント: 記録に受け入れられた結果が1つ以上。
2. 2あなたの組織がリポジトリ追跡ADRを必要とする場合はエクスポートしてください。 多くの組織がそうしており、正しいです — コードの隣にあるマークダウンADRがコンプライアンスの成果物として残ります。ツリーから4つのセクションの要約を書いてください（5分、金曜日ではありません）、完全な議論のためにディスカッションにリンクを戻します。チェックポイント：リポジトリADRはツリーを引用し、ツリーは理由を保持します。

意見が異なっても、記録に残してコミットする

アマゾンが有名にしたパターン — 異議を唱えてコミットする — には可読性の問題があります：後になって、異議が本物であり、聞かれ、回答されたことが、押しつぶされたのではなく、どうやって誰が知るのでしょうか？チェーンメカニクスがそれに答えます。完全に4ターンを経て、合意なしで完了したレビューのチェーンは、まさにその証拠です：異議が提起され、回答され、押し進められ、再度回答され、記録に残された後に、異議を唱えた者がコミットしました。異議を唱えた者は、聞かれたことが文書化されており — これが後にコミットすることを単なる従順ではなく合理的にする理由です。

ステップ10: 削除せずに上書きする

決定は時代を経ます。同期オプションを無効にしたレート制限が引き上げられたとき、正しい選択は置き換えるものを参照する新しい決定です — 何が変わったのかを示すADR-014のノードに関連付けられた新しい引数です。古い決定は読みやすいままであり、その理由は新しい決定が何を覆しているのかを知るための正確な根拠です。

明示的に管理すべき一つの正直なギャップ：組み込みのADRステータスフィールドはありません。提案済み / 受け入れ済み / 置き換え済みは議論の一級の状態ではなく、置き換えはリンクによってモデル化されており、その慣習はあなたのチームが維持するものです。製品がそれを強制することを仮定するのではなく、チームの作業合意に明記してください。

正直な限界

• ✗これは、あなたのリポジトリ内のADRsを置き換えるものではありません。あなたの組織がコードの隣にバージョン管理されたADRsを必要とする場合。要約をエクスポートしてコミットしてください。マークダウンが苦手な部分、つまり議論にはツリーを使用してください。
• ✗ADRステータスフィールドはありません。 提案/受け入れ/置き換えは、製品が強制するものではなく、あなたが維持するリンクの慣習です。
• ✗チェーンは4回のターンです。 深い建築的な意見の不一致には呼びかけが必要です; チェーンはそれ以前に試みられたことの記録です。
• ✗評価は単一のラベル付き値であり、重み付けされた多基準スコアリングではありません。
• ✗誰も良い文脈を書くことはありません。 構造は良い記録のコストを下げますが、判断を提供するわけではありません。

実践的なレッスン

• ✓1つのRFC、1つの議論。 四半期全体のアーキテクチャを覆うメガツリーに抵抗しましょう — スーパセッションリンクは、ネスティングよりも決定をより良く接続します。
• ✓存在するものから種をまく。 決定が多いトランスクリプトや古いADRフォルダーを抽出すると、議論にスタートを切ることができる — インポートされたとラベル付けされているため、ライブの議論が区別できるままになる。
• ✓レビュアーの名前を彼らのチェーンに付けて、そのままにしておいてください。 帰属は責任であり、匿名の建築に対する異議は民間伝承に変わります。
• ✓結果のセクションは決定者のものであり、他の誰のものでもありません。 受け入れた人によって書かれた受け入れた欠点は、レビュアーの警告とは異なる重みを持ちます。

ADR-014、応答するバージョン

新しいテックリードの質問に戻ります。再構築されたバージョンでは、ADR-014はノードです：その理由を伴うキューの決定、三つのコンテキストフォース（そのうち一つは今や古くなっています — 明らかに）、古いレート制限を名指しした致命的なコン名を持つ拒否された同期APIの兄弟、スタッフエンジニアを含む四つの完了したレビューのチェーン、そして証拠として添付されたベンチマーク。テックリードは10分間読み、レート制限が変更されたのを見て、古いノードにリンクされた上位提案を開きます。誰もSlackを掘り起こしません。それが全ての約束です：チェーンは合意に達し、ツリーはそれを記録します — そしてその記録は、あなたが尋ねられるとは思っていなかった質問に答えます。