Architecture Decision Recordarc42 による決定記録テンプレート
1. はじめにと目標
要件、推進要因の簡単な説明、要件の抜粋(または要約)。主要なステークホルダーにとって 最も優先度の高い、アーキテクチャに対する上位 3 つ(最大 5 つ)の品質目標。重要な ステークホルダーの表と、アーキテクチャに関する彼らの期待。
1.1 要件の概要
内容
機能要件、推進要因の簡単な説明、要件の抜粋(または要約)。(あることが望ましい)要件 文書へのリンクと、それをどこで見つけられるかの情報。
動機
エンドユーザーの視点から見ると、システムはビジネス活動のサポートを改善したり、 品質を向上させたりするために作成または変更されます。
形式
簡単なテキストによる説明。おそらく表形式のユースケース形式。要件文書が存在する場合は、 この概要はそれらの文書を参照する必要があります。
これらの抜粋はできるだけ短くしてください。この文書の可読性と、要件文書との 潜在的な冗長性とのバランスを取ってください。
1.2 品質目標
内容
その達成が主要なステークホルダーにとって最も重要である、アーキテクチャに対する 上位 3 つ(最大 5 つ)の品質目標。本当にアーキテクチャのための品質目標を意味しています。 プロジェクトの目標と混同しないでください。両者は必ずしも同一ではありません。 ISO 25010 標準は、関心を持つ可能性のあるトピックの優れた概要を提供しています。
動機
最も重要なステークホルダーの品質目標を知っておく必要があります。それらは根本的な アーキテクチャ上の決定に影響を与えるからです。これらの品質について非常に具体的に し、流行語を避けてください。アーキテクトとして、自分の仕事の品質がどのように 判断されるかを知らなければ…
形式
最も重要な品質目標と具体的なシナリオを優先度順に並べた表。
1.3 ステークホルダー
内容
システムのステークホルダー、つまり次のようなすべての人、役割、または組織の明示的な概要
アーキテクチャを知っておくべき
アーキテクチャについて納得させる必要がある
アーキテクチャまたはコードを扱う必要がある
仕事のためにアーキテクチャの文書を必要とする
システムまたはその開発に関する決定を下す必要がある
動機
システムの開発に関与する、またはシステムの影響を受けるすべての関係者を知っておく 必要があります。そうしないと、開発プロセスの後半で嫌な驚きに遭うことがあります。 これらのステークホルダーが、あなたの作業とその成果の範囲と詳細レベルを決定します。
形式
役割名、人名、およびアーキテクチャとその文書に関する期待を記した表。
2. 制約
設計と実装の決定、または関連するプロセスに関する決定において、チームを制約する あらゆるもの。個々のシステムを超えて、組織や会社全体に有効な場合もあります。
内容
ソフトウェアアーキテクトの設計と実装の決定、または開発プロセスに関する決定の 自由を制約するあらゆる要件。これらの制約は、個々のシステムを超えて、組織や 会社全体に有効な場合があります。
動機
アーキテクトは、設計上の決定でどこが自由で、どこで制約を守らなければならないかを 正確に知っておく必要があります。制約には常に対処しなければなりませんが、 交渉可能な場合もあります。
形式
説明付きの制約の簡単な表。必要に応じて、技術的制約、組織的・政治的制約、 規約(たとえば、プログラミングやバージョン管理のガイドライン、文書や命名規則)に 細分化できます
3. コンテキストとスコープ
システムを(外部の)コミュニケーション相手(隣接システムとユーザー)から区切ります。 外部インターフェースを指定します。ビジネス/ドメインの視点(必須)または技術的な 視点(任意)から示されます
内容
システムのスコープとコンテキストは、その名が示すとおり、システム(つまりスコープ)を すべてのコミュニケーション相手(隣接システムとユーザー、つまりシステムのコンテキスト) から区切ります。それによって外部インターフェースを指定します。
必要に応じて、ビジネスコンテキスト(ドメイン固有の入力と出力)と技術的コンテキスト (チャネル、プロトコル、ハードウェア)を区別します。
動機
コミュニケーション相手とのドメインインターフェースと技術的インターフェースは、 システムの最も重要な側面の 1 つです。それらを完全に理解していることを確認して ください。
形式
さまざまなコンテキスト図
コミュニケーション相手とそのインターフェースのリスト。
3.1 ビジネスコンテキスト
内容
すべてのコミュニケーション相手(ユーザー、IT システムなど)の仕様。ドメイン固有の 入力と出力、またはインターフェースの説明付き。任意で、ドメイン固有の形式や 通信プロトコルを追加できます。
動機
すべてのステークホルダーは、システムの環境とどのようなデータが交換されるかを 理解する必要があります。
形式
システムをブラックボックスとして示し、コミュニケーション相手とのドメイン インターフェースを指定するあらゆる種類の図。
あるいは(または追加で)表を使用できます。表のタイトルはシステム名で、3 つの列には コミュニケーション相手の名前、入力、出力が含まれます。
3.2 技術的コンテキスト
内容
システムを環境に接続する技術的インターフェース(チャネルと伝送媒体)。さらに、 ドメイン固有の入出力のチャネルへのマッピング、つまりどの入出力がどのチャネルを 使用するかの説明。
動機
多くのステークホルダーは、システムとそのコンテキストの間の技術的インターフェースに 基づいてアーキテクチャ上の決定を行います。特にインフラストラクチャやハードウェアの 設計者がこれらの技術的インターフェースを決定します。
形式
たとえば、隣接システムへのチャネルを記述する UML 配置図と、チャネルと入出力の関係を 示すマッピング表。
4. ソリューション戦略
アーキテクチャを形作る基本的な決定とソリューション戦略の要約。技術、最上位の分解、 最上位の品質目標を達成するためのアプローチ、関連する組織上の決定を含めることができます。
内容
システムのアーキテクチャを形作る基本的な決定とソリューション戦略の短い要約と説明。これには次が含まれます
技術的な決定
システムの最上位の分解に関する決定。たとえば、アーキテクチャパターンやデザインパターンの使用
主要な品質目標をどのように達成するかに関する決定
関連する組織上の決定。たとえば、開発プロセスの選択や特定のタスクの第三者への委任。
動機
これらの決定は、アーキテクチャの礎石を形成します。それらは、他の多くの詳細な決定や 実装ルールの基礎となります。
形式
これらの主要な決定の説明は短くしてください。
問題の記述、品質目標、主要な制約に基づいて、何を決定したか、なぜそのように 決定したかの動機を述べてください。詳細は以降のセクション(構造的な詳細は セクション 5、横断的概念はセクション 8)を参照してください。
ソリューションアプローチのリストまたは表を使用できます。
5. ビルディングブロックビュー
システムの静的な分解、ソースコードの抽象化。適切な詳細レベルまで、ホワイトボックス (ブラックボックスを含む)の階層として示されます。
内容
ビルディングブロックビューは、システムのビルディングブロック(モジュール、コンポーネント、 サブシステム、クラス、インターフェース、パッケージ、ライブラリ、フレームワーク、 レイヤー、パーティション、ティア、関数、マクロ、操作、データ構造など)への静的な分解と、 それらの依存関係(関係、関連など)を示します。
このビューはすべてのアーキテクチャ文書で必須です。家に例えると、これは間取り図です。
動機
抽象化によって構造を理解しやすくすることで、ソースコードの概要を維持します。
これにより、実装の詳細を明かすことなく、ステークホルダーと抽象的なレベルで コミュニケーションできます。
形式
ビルディングブロックビューは、ブラックボックスとホワイトボックス(下図参照)の 階層的なコレクションとその説明です。
5.1 システム全体のホワイトボックス
ここでは、次のホワイトボックステンプレートを使用して、システム全体の分解を記述します。これには次が含まれます
概要図
分解の動機
含まれるビルディングブロックのブラックボックスの説明。これについては、次の選択肢を提供します:
含まれるすべてのビルディングブロックとそのインターフェースの短く実用的な概要のために、1 つの表を使用する
ブラックボックステンプレート(下記参照)に従って、ビルディングブロックのブラックボックスの説明のリストを使用する。ツールの選択によっては、このリストはサブチャプター(テキストファイル内)、サブページ(Wiki 内)、またはネストされた要素(モデリングツール内)になり得ます。
(任意:)ビルディングブロックのブラックボックステンプレートでは説明されないが、ホワイトボックスを理解するために非常に重要な重要インターフェース。
インターフェースを指定する方法は非常に多いため、そのための特定のテンプレートは提供しません。
最良の場合は、例や単純なシグネチャで十分でしょう。
5.2 レベル 2
ここでは、レベル 1 の(一部の)ビルディングブロックの内部構造をホワイトボックスとして 指定できます。
システムのどのビルディングブロックが、そのような詳細な説明を正当化するほど 重要かを決める必要があります。網羅性よりも関連性を優先してください。重要、意外、 リスクが高い、複雑、または変動しやすいビルディングブロックを指定してください。 システムの通常の、単純な、退屈な、または標準化された部分は省略してください
5.2.1 ビルディングブロック 1 のホワイトボックス
ビルディングブロック 1 の内部構造を指定します。
ホワイトボックステンプレート(上記参照)を使用してください。
6. ランタイムビュー
重要なユースケースや機能、重要な外部インターフェースでのやり取り、運用と管理、 およびエラーと例外の動作を網羅した、シナリオとしてのビルディングブロックの動作。
内容
ランタイムビューは、次の領域のシナリオの形で、システムのビルディングブロックの具体的な動作とやり取りを記述します:
重要なユースケースや機能: ビルディングブロックはそれらをどのように実行するか?
重要な外部インターフェースでのやり取り: ビルディングブロックはユーザーや隣接システムとどのように協調するか?
運用と管理: 起動、開始、停止
エラーと例外のシナリオ
備考: 可能なシナリオ(シーケンス、ワークフロー)を選ぶ主な基準は、そのアーキテクチャ上の関連性です。多数のシナリオを記述することは重要ではありません。むしろ代表的な選択を文書化すべきです。
動機
システムのビルディングブロック(のインスタンス)が実行時にどのように仕事を行い、通信するかを理解する必要があります。主に、静的モデル(ビルディングブロックビュー、配置ビュー)を読んで理解することに消極的、またはそれが難しいステークホルダーにアーキテクチャを伝えるために、文書にシナリオを記録します。
形式
シナリオを記述するための表記法は数多くあります。たとえば
番号付きの手順リスト(自然言語)
アクティビティ図またはフローチャート
シーケンス図
BPMN または EPC(イベントプロセスチェーン)
状態機械
など。
6.n ランタイムシナリオ n (1, 2, 3, など)
ランタイム図またはシナリオのテキストによる説明を挿入します。
この図に示されたビルディングブロックインスタンス間のやり取りの注目すべき側面の説明を挿入します。
7. 配置ビュー
環境、コンピューター、プロセッサー、トポロジーを含む技術的なインフラストラクチャ。 (ソフトウェアの)ビルディングブロックのインフラストラクチャ要素へのマッピング。
内容
配置ビューは次を記述します:
システムを実行するために使用される技術的インフラストラクチャ。地理的な場所、環境、 コンピューター、プロセッサー、チャネル、ネットワークトポロジーなどのインフラストラクチャ 要素およびその他のインフラストラクチャ要素を含む。
(ソフトウェアの)ビルディングブロックのそれらのインフラストラクチャ要素へのマッピング。
システムは、開発環境、テスト環境、本番環境など、異なる環境で実行されることがよく あります。そのような場合は、関連するすべての環境を文書化する必要があります。
特に、ソフトウェアが複数のコンピューター、プロセッサー、サーバー、またはコンテナーを持つ 分散システムとして実行される場合、あるいは独自のハードウェアプロセッサーやチップを 設計・構築する場合は、配置ビューを文書化してください。
ソフトウェアの観点からは、ビルディングブロックの配置を示すのに必要なインフラストラクチャの 要素を記録すれば十分です。ハードウェアアーキテクトは、それを超えて、記録する必要がある 任意の詳細レベルまでインフラストラクチャを記述できます。
動機
ソフトウェアはハードウェアなしでは動作しません。この基盤となるインフラストラクチャは、 システムや一部の横断的概念に影響を与える可能性があり、実際に与えます。そのため、 インフラストラクチャを知っておく必要があります。
形式
おそらく、最上位レベルの配置図は、自身のインフラストラクチャを 1 つのブラックボックスとして 技術的コンテキストとして、セクション 3.2 に既に含まれています。このセクションでは、追加の 配置図を使用して、そのブラックボックスにズームインします。
UML はそのビューを表現するための配置図を提供しています。インフラストラクチャがより複雑な場合は、おそらくネストした図とともに、それを使用してください。
(ハードウェアの)ステークホルダーが UML 配置図以外の種類の図を好む場合は、 インフラストラクチャのノードとチャネルを示せるものであれば、どのような種類でも 使わせてください。
7.1 インフラストラクチャ レベル 1
(通常は図、表、テキストの組み合わせで)次を記述します:
システムの複数の場所、環境、コンピューター、プロセッサーなどへの配布と、それらの間の物理的な接続
この配置構造の重要な正当化または動機
インフラストラクチャの品質および/またはパフォーマンス特性
ソフトウェア成果物(ビルディングブロック)のインフラストラクチャ要素へのマッピング
複数の環境または代替の配置については、関連するすべての環境について arc42 のそのセクションをコピーしてください。 **
7.2 インフラストラクチャ レベル 2
ここでは、インフラストラクチャ レベル 1 の(一部の)インフラストラクチャ要素の内部構造を含めることができます。
選択した各要素について、レベル 1 の構造をコピーしてください。
8. 横断的概念
システムの複数の部分(→ 横断的)に関連する、全体的で主要な規則とソリューション アプローチ。概念はしばしば複数のビルディングブロックに関連します。ドメインモデル、 アーキテクチャパターンとスタイル、特定の技術の使用規則、実装規則など、さまざまな トピックを含めます。
内容
このセクションでは、横断的概念(プラクティス、パターン、規則、またはソリューションの アイデア)を説明します。このような概念はしばしば複数のビルディングブロックに関連します。 さまざまなトピックを含む場合があります。
動機
概念は、アーキテクチャの概念的整合性(一貫性、均質性)の基礎を形成します。したがって、 システムの内部品質を達成するための重要な貢献です。
ここは、そのような概念を一貫して指定するためにテンプレートで用意された場所です。
これらの概念の多くは、複数のビルディングブロックに関連する、または影響を与えます。
形式
形式はさまざまで構いません:
任意の構造のコンセプトペーパー
特に技術的概念のための実装例
アーキテクチャビューの表記法を使用した横断的なモデルの抜粋またはシナリオ
このセクションの構成
システムに最も必要なトピックのみを選び、このセクションでそれぞれにレベル 2 の見出し(例: 8.1、8.2 など)を割り当てます。
- 前述の図のすべてのトピックを網羅しようとしないでください。
背景
システム内のいくつかのトピックは、複数のビルディングブロック、ハードウェア要素、 または開発プロセスに関わることがよくあります。このような横断的なトピックは、 関係するビルディングブロック、ハードウェア要素、または開発プロセスの説明で 繰り返すよりも、一箇所に集約して伝達または文書化する方が容易な場合があります。
特定の概念はシステムのすべての要素に関わり、他の概念は少数の要素にのみ関連する 場合があります。
9. アーキテクチャ上の決定
根拠を含む、重要、高コスト、重大、大規模、またはリスクの高いアーキテクチャ上の決定。
内容
根拠を含む、重要、高コスト、大規模、またはリスクの高いアーキテクチャ上の決定。 ここでの「決定」とは、与えられた基準に基づいて 1 つの代替案を選択することを意味します。
アーキテクチャ上の決定を、この中央のセクションに文書化すべきか、それともローカルに (たとえば、あるビルディングブロックのホワイトボックステンプレート内に)文書化する方が よいかは、ご自身の判断で決めてください。冗長なテキストは避けてください。アーキテクチャの 最も重要な決定を既に記録したセクション 4 を参照してください。
動機
システムのステークホルダーは、決定を理解し、たどり直せる必要があります。
形式
すべての重要な決定について ADR(アーキテクチャ決定記録)
重要度と結果で並べたリストまたは表、または
決定ごとに別々のセクションとして、より詳細な形式で
背景(ADR について)
より小さな文書は、読みやすく、作成しやすく、保守しやすいです。アーキテクチャ上の 決定に関して、開発チームはしばしば次の状態になります:
決定については、たとえばソースコードに見えるので知っているが、
その決定の背後にある動機を知らない(Nygard 2011 を参照)
したがって、いくつかの重要な決定を、その動機、理由づけとともに文書化する必要があります
決定に関する私たちの提案
アーキテクチャ上重要な決定、つまり、構造、品質特性、重要な(特に外部の)依存関係と インターフェース、または構築技術に影響を与える決定の集合を保持してください (この提案をしてくれた Michael Nygard に感謝します)。
10. 品質要件
高レベルの概要を提供する品質ツリーとともに、シナリオとしての品質要件。最も重要な 品質目標は、セクション 1.2(品質目標)で記述されているはずです。
内容
このセクションには、関連するすべての品質要件が含まれます。
これらの要件の最も重要なものは、既にセクション 1.2(品質目標)で記述されているため、 ここでは参照のみにする必要があります。このセクション 10 では、重要度が低く、 完全に達成されなくても高いリスクを生じない(が、あれば嬉しい)品質要件も記録する 必要があります。
動機
品質要件はアーキテクチャ上の決定に大きな影響を与えるため、どのような品質が ステークホルダーにとって本当に重要なのかを、具体的かつ測定可能な方法で知って おく必要があります。
さらなる情報
https://quality.arc42.org にある包括的な Q42 品質モデルを参照してください。
10.1 品質要件の概要
内容
品質要件の概要または要約。
動機
しばしば、何十もの(あるいは何百もの)詳細な品質要件に遭遇します。この概要 セクションでは、たとえばカテゴリやトピックを記述して(ISO 25010:2023 または Q42 によって提案されているように)要約するよう努めてください
これらの要約された記述が既に正確で、十分に具体的で、測定可能である場合は、 セクション 10.2 を省略してもかまいません。
形式
各行にカテゴリまたはトピックと品質要件の短い説明を含む簡単な表を使用します。 あるいは、マインドマップを使用してこれらの品質要件を構造化することもできます。
文献では、品質属性ツリーという考え方も記述されています。これは、一般的な用語 「品質」をルートに置き、「品質」という用語をツリー状に精緻化するものです。 [Bass+21] はこの目的のために「Quality Attribute Utility Tree」という用語を導入しました。
10.2 品質シナリオ
内容
品質シナリオは、品質要件を具体的にし、それらが(受け入れ基準の意味で)満たされて いるかどうかを判断できるようにします。シナリオが具体的で測定可能であることを 確認してください。
特に有用なシナリオは 2 種類あります:
使用シナリオ(アプリケーションシナリオまたはユースケースシナリオとも呼ばれる)は、 特定の刺激に対するシステムの実行時の反応を記述します。これには、システムの 効率やパフォーマンスを記述するシナリオも含まれます。 例: システムは、ユーザーのリクエストに 1 秒以内に反応する。
変更シナリオは、システムまたはその直近の環境の変更や拡張の望ましい効果を 記述します。例: 追加の機能が実装される、または品質属性の要件が変更され、 変更の労力または期間が測定される。
形式
詳細なシナリオの典型的な情報には、次のものが含まれます:
短い形式(Q42 モデルで好まれる):
コンテキスト/背景: どのような種類のシステムまたはコンポーネントか、環境または状況は何か?
ソース/刺激: 誰または何が動作、反応、または行動を開始またはトリガーするか。
メトリクス/受け入れ基準: 尺度またはメトリクスを含む応答
長い形式のシナリオ(SEI と [Bass+21] で好まれる)はより詳細で、次の情報を含みます:
シナリオ ID: シナリオの一意の識別子。
シナリオ名: シナリオの短く説明的な名前。
ソース: シナリオを開始するエンティティ(ユーザー、システム、またはイベント)。
刺激: システムが対処しなければならないトリガーとなるイベントまたは条件。
環境: システムが刺激を受ける運用上のコンテキストまたは条件。
成果物: 刺激の影響を受けるシステムのビルディングブロックまたはその他の要素。
応答: 刺激に対する反応としてシステムが示す結果または動作。
応答の尺度: システムの応答を評価する基準またはメトリクス。
関連項目
2023 年 1 月以降、arc42 は実用的な品質モデルを提供しています。これは、品質要件に #flexible、#efficient、#usable、#operable、#testable、#secure、#safe、#reliable などのハッシュタグやラベルを付けることを提案しています。
11. リスクと技術的負債
既知の技術的リスクまたは技術的負債。システム内またはその周辺にどのような潜在的な 問題が存在するか? 開発チームは何に悩まされているか?
内容
特定された技術的リスクまたは技術的負債の、優先度順のリスト
動機
「リスク管理は大人のためのプロジェクト管理である」(Tim Lister、Atlantic Systems Guild)
これは、アーキテクチャにおける技術的リスクと技術的負債の体系的な検出と評価の モットーとすべきものです。これは、全体的なリスク分析と対策計画の一部として、 管理層のステークホルダー(たとえば、プロジェクトマネージャー、プロダクトオーナー)に 必要とされます。
形式
リスクおよび/または技術的負債のリスト。おそらく、リスクを最小化、軽減、回避する、 または技術的負債を削減するための推奨される対策を含みます。