アーキテクチャ決定記録

どのようなものか

アーキテクチャ決定記録は、システムに長く影響する技術的な選択と、その
理由を短くまとめたものです。英語の architecture
decision record から ADR
と略します。チームが何を選んだか、どの条件で判断したか、ほかにどんな
現実的な案を検討し、どのような影響を受け入れたかを残します。対象に
は、データを管理するサービス、システム間の境界、連携方法、障害時の振
る舞いなどがあります。後から参加した人も、設計がその形になった理由
と、今も有効な前提を確かめられます。

最初は少数の項目で始められます。番号と日付があれば、別の文書や変更か
ら参照できます。状態欄は、提案中、採用済み、別の決定に置き換わった状
態を示します。背景では問題と制約を説明し、決定の欄では実施することを
示します。結果には利点だけでなく、引き受ける作業も書きます。新しい
サービスの運用、長めの移行期間、データ移行の事前練習などが該当しま
す。代替案は、それぞれを選ぶ理由が読み取れる程度に説明します。

置き場所は、関係者が普段使っている場所にします。コードの近くに
Markdown
で保管し、決定を実装した変更から参照するチームもあります。複数のリポ
ジトリで作業するなら、共通の索引を作る方法もあります。大切なのは、参
照先が安定していて、理由を単独で読めることです。長い測定結果や試験の
記録は別に残し、判断の根拠になった箇所へリンクできます。

なぜ重要なのか

コードから現在の仕組みは読み取れますが、過去の選択の理由は一部しか見
えません。新しい担当者が二つのデータベースを見て、重複しているのでま
とめようと考えることがあります。実際には、取引先が出力形式を変える間
に、影響を限定するため分けたのかもしれません。記録があれば、当時守り
たかったもの、選んだ理由、見直すきっかけを確認できます。同じ調査を毎
回やり直す手間も減ります。

記録は具体的な異論を出す助けにもなります。たとえば、新しい依存先を使
えば、スケジューラーを自作せずに済むという案があります。一方、障害時
には当番がその状態を復旧できなければなりません。レビュー担当者は、必
要な権限があるか、当番体制で作業を引き受けられるかを質問できます。運
用するチームも、決める前に同じ説明を読めます。引き継ぎの際には、約束
したことと責任の範囲が分かります。

書く量は、判断をやり直す負担に合わせます。画面の短い文言の変更なら、
変更履歴を見れば足りることが多いでしょう。注文台帳をどのサービスが管
理するか、重複支払いをどう扱うかという判断は、複数のチームに関係しま
す。案を思い出せるうちに、当時把握していた制約や検証結果を日付ととも
に残します。後で別の情報が得られても、その時点の選択を当時の条件の下
で評価できます。

実際の活用例

ポートフォリオのプラットフォーム設立時の技術判断では、製品の方向性を
固めながら主要技術を選んだ仕事を紹介しています。このような選択は、後
から意図を確かめる価値があります。以下は、データ管理の判断を記録する
ための架空の例です。

配送サービスに注文データベースと公開ステータスページがあるとします。
発送イベントの一部が遅れて届きます。利用者は自分の注文だけを参照でき
る必要があります。チームは、許可した項目だけを渡す別の読み取り用モデ
ルからステータスを表示すると決めました。注文データベースを直接読む案
なら、構成が少なくなり、通常は新しい情報が出ます。ただし、正式な注文
台帳の近くで公開トラフィックと新しい権限境界を扱う必要が生じます。夜
間出力を流用する案は導入しやすいものの、当日中の変更を表示できませ
ん。

影響を作業に結び付けます。サポートには、表示の遅れが大きいときに内部
の手順へ切り替えるための指標が必要です。契約テストで許可していない項
目の追加を検知できます。更新処理と警報には責任者を置きます。忙しい二
週間にわたり遅延が合意した上限を超えた場合や、分離要件が変わった場合
は、判断を見直します。記録にレビューと試験を結び付けておけば、新しい
案を検討するときも、元の選択の理由をたどれます。

置き換えに合意したら、別の記録を作って相互に参照します。旧版の障害を
調べる人には当時の理由が必要です。短い題名、日付、状態を並べた索引が
あれば、すべての変更履歴を読み直さずに現在の決定を見つけられます。

公開側は、ステータスを返す前に、その利用者が指定した注文を参照できる
か確かめます。他の顧客の注文が拒否されることと、許可された応答に含ま
れる項目の両方を試験します。

問題が起きるところ

選んだ案だけを丁寧に説明し、ほかの案を極端に単純化すると、後から読ん
でも判断を評価できません。そのとき実際に有力だった理由を書きます。主
要な主張は、判断に使った測定、規格、制約に結び付けます。条件が変われ
ば選択も変わり得ることが具体的に分かります。

費用や運用責任が記録から抜ける場合もあります。別のデータベースや共有
キューを導入すれば、ほかの担当者の仕事が増えます。運用や保守を引き受
ける人、権限境界を確認する人を明らかにします。その場ですぐ確かめられ
ない影響については、何をいつ観察できるかを書きます。

記録は、決めている最中に書ける長さに保ちます。頻繁に改訂する操作手順
には別の置き場所を用意し、参照先を示します。判断が変わったときは、以
前の理由を残して現行の選択へ進めるようにします。短い記録であっても、
理由と根拠が残っていれば後日の調査に使えます。

参考資料

  * AWS のアーキテクチャ決定記録の作成手順

  * Microsoft Azure Well-Architected の意思決定記録

  * 英国政府のアーキテクチャ決定記録フレームワーク

hこのページのウェブ版	URL:https://engineer.company/ja/glossary/architecture-decision-record/	engineer.company	70
