本文へ移動
Engineer
メニュー
デザイン
日本語

Engineer / 用語集

アーキテクチャ決定記録

設計の選択とその理由を短く残す記録

どのようなものか

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

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

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

なぜ重要なのか

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

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

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

実際の活用例

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

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

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

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

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

問題が起きるところ

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

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

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

参考資料

お問い合わせ

必要なことを整理している段階ですか?

うまくいっていないことや、つくりたいものをお聞かせください。何が必要か、おおよそいくらかかるか、私たちが適任かどうかをお伝えします。

時間単価は1,400 DKKから(VAT別)で、ご依頼期間が長いほど下がります。

welcome@engineer.company +45 50 10 61 84 デンマーク、コペンハーゲン