- はじめに
- 前提
- ADRとは？ - 意思決定とその記録
- Design Docsとの差分
- いつ書く？
- ADR運用の前提条件
- フォーマット
- 意識していること
- メリットとデメリット
- なくてはならないもの？
- 注意点
- プロジェクトに根付かせるポイント
- 最後に
はじめに
本ブログでは、私が運用しているArchitectural Decision Record（ADR）についてご紹介します。
前提
筆者は主にアプリケーションレイヤーやソフトウェア開発の設計・運用の担当ではなく、
インフラレイヤーのアーキテクチャを設計・運用しています。
本記事の内容は筆者の独自の手法であり、全てのお客様に対して実施しているものではないことをご了承下さい。
また、本ブログの趣旨としてはADRについて詳細を深掘りするのではなく、 筆者が運用している独自のドキュメントがADRと類似する部分について、その差分や運用中に感じたことを言語化しています。
ADRとは？ - 意思決定とその記録
ADRは、システムのアーキテクチャに関する意思決定のプロセスを記録する手法です。
アーキテクチャの決定はシステム運用に大きな影響を与える重要なプロセスであり、その経緯をドキュメントとして残すことで、将来的な変更や運用継続において高いアジリティと整合性を担保できます。
AWSの公式ドキュメントにもADRについての規範ガイダンスがあります。
アーキテクチャ決定レコード (ADR) は、構築計画中のソフトウェアアーキテクチャの重要な側面に関してチームが取った選択について説明する文書のことです。
Githubが公開しているADRもぜひ参考にしてください。 Architectural Decision Records
Design Docsとの差分
Design Docsとは？
ADRと類似性の高いドキュメントとして、Googleが公開しているDesign Docsがあります。
経緯
私は以前、あるプロジェクトでDesign Docsを運用していましたが、
プロジェクトの初期段階の方針策定では運用していたDesign Docsのフォーマットに合致しない部分があることがわかりました。
当時は無理やり項目を書き換えてレビュー依頼し、方針策定のアウトプットとして仕上げましたが、
ふりかえるとそれは具体的な設計内容や詳細パラメータ、テストプランなどが欠けており、ほとんどDesign Docsとは言えない内容の成果物でした。
その後、ADRというドキュメント手法を知り、用途に合わせてADRとDesign Docsを使い分けることができるのではないかと考え、現在ADRを運用している。という経緯です。
再度強調しますが、本ブログで紹介する内容はADRやDesign Docsを忠実に再現しているわけではありません。
FYI
生成AIにADRとDesign Docs自体のそれぞれのドキュメントを読み込ませ、類似ポイントを抽出させて差分を確認できるようにしました。
### 目的と焦点
- **ADR**: 「アーキテクチャ決定（AD）とは、機能要件または非機能要件に対応する正当な設計選択であり、アーキテクチャ的に重要です。アーキテクチャ決定記録（ADR）は、単一のADとその理由を記録し、プロジェクト内で作成および維持されるADRの集合体は、そのプロジェクトの意思決定ログを構成します。」（Architectural Decision Records）
- **Design Doc**: 「Design Docsは、高レベルの実装戦略と重要な設計決定を文書化し、それらの決定において考慮されたトレードオフを強調します。」（Design Docs at Google）
### スコープ
- **ADR**: 「アーキテクチャ決定記録（ADR）は、単一のADとその理由を記録し、プロジェクト内で作成および維持されるADRの集合体は、そのプロジェクトの意思決定ログを構成します。」（Architectural Decision Records）
- **Design Doc**: 「Design Docsは、高レベルの実装戦略と重要な設計決定を文書化し、それらの決定において考慮されたトレードオフを強調します。」（Design Docs at Google）
### 形式と構造
- **ADR**: 「『軽量』ADRは、タイトル、ステータス、コンテキスト、決定、および結果で構成されます…」（Architectural Decision Records）
- **Design Doc**: 「Design Docsは非公式な文書であり、内容に厳密なガイドラインはありません。ただし、ある特定の構造が非常に有用であることが確立されています。」（Design Docs at Google）
### 使用時期と頻度
- **ADR**: 「ADRは、アーキテクチャ的に重要な決定が行われるたびに記録されます。これには、新しいシステムや大規模な変更が導入される際や、技術的なトレードオフが発生する場合が含まれます。ADRは、意思決定のプロセスを透明にし、後からその決定を参照するために使用されます。」（Architectural Decision Records）
- **Design Doc**: 「デザインドキュメントのライフサイクルのステップは以下の通りです：
1. 作成と迅速な反復
2. レビュー（複数回のラウンドがある場合もあります）
3. 実装と反復
4. 保守と学習」（Design Docs at Google）
### 詳細度と具体性
- **ADR**: 「選択肢の利点と欠点を考慮することが、選択されたオプションの理由を理解するために重要です。」（Architectural Decision Records）
- **Design Doc**: 「Design Docsは、ソフトウェアの設計において行ったトレードオフを記述する場所です。これらのトレードオフに焦点を当てることで、長期的な価値を持つ有用なドキュメントを作成します。」（Design Docs at Google）
### コラボレーションとレビュー
- **ADR**: 「レビューは多くの価値を追加する可能性がありますが、過剰な負担の危険性もあるため、賢明に取り扱う必要があります。」（Architectural Decision Records）
- **Design Doc**: 「レビュー段階では、Design Docsはオリジナルの著者および近しい共同作業者よりも広範なオーディエンスと共有されます。」（Design Docs at Google）
いつ書く？
ADRは取り扱うシステムの大小に関わらずあらゆる意思決定の側面で記載するとされています。
プロジェクトチームは、構造 (マイクロサービスなどのパターン)、機能以外の要件 (セキュリティ、高可用性、耐障害性)、依存関係 (コンポーネントの結合)、インターフェイス (API と公開済みの契約)、建設技術 (ライブラリ、フレームワーク、ツール、プロセス) に影響するソフトウェアのあらゆる側面について ADR を作成する必要があります。
引用元：プロジェクトチームはいつ ADR を作成する必要がありますか?
ADR運用の前提条件
個人的にADRを運用する前に決定しておくと良いと思う事項をあげます。
ステークホルダー
アーキテクチャの承認を得るための対象（企業、部門、担当者）を明確にし、承認期間も把握しておきます。
コスト要件
予算や予測される金額をステークホルダーに確認します。特にセキュリティ関連の場合、金額の根拠を示す材料として捉えます。
導入対象の要件
各種コストを見積もるために対象範囲を事前に確認します。
例えば、対象のクラウドアカウント、システム、サービス、本番/検証/開発環境、サーバーなどです。
確認・調査工数
アーキテクチャを決定するために必要な確認・調査作業を整理し、その作業時間を見積もります。
既存システムの改修や大規模なアーキテクチャの場合には確認・調査だけでも多くの工数が発生する可能性があり、事前にステークホルダーとイメージをすり合わせる必要も出てきます。
ステップに分けて整理することも検討して下さい。
- 例
- Step1. ：影響範囲を整理する（作業工数：x h or x 人日）
- Step2.：影響規模を調査する（作業工数：x h or x 人日）
- Step3.：整理・調査した内容を整理し、各種コストを見積もりする（作業工数：x h or x 人日）
フォーマット
Github上に有志が利用しているテンプレートを見つけましたのでぜひ参考にしてください。
まずはシンプルなフォーマットから始めるのがおすすめです。 architecture-decision-record/locales/en/templates/decision-record-template-by-michael-nygard/index.md at main · joelparkerhenderson/architecture-decision-record · GitHub
必要最低限のフォーマットから始めて、プロジェクトやチームの状況に合わせて肉付けするように フォーマットをブラッシュアップしていきます。
以下は私が運用しているADRフォーマットの一例です。
# タイトル ## 状態 提案済み、承認済み、拒否済み、非推奨、置き換え済みなどのステータスを記載します。 ドキュメントの読み手がこの意思決定は今現在どのような状態なのかを判断できる情報になります。 ## ステークホルダー - 記載者 - 承認者 ## コンテキスト ### 目的と背景 アーキテクチャ選定の目的と背景を記載します。 ### 前提 アーキテクチャを決定する上での前提条件を明確に記載します。 前提条件が曖昧だと適切なアーキテクチャの選定が難しくなります。 前提が定まっていない場合は洗い出してここを更新します。 ## 決定 提案したアーキテクチャを記載します。 承認となった場合はそのまま記載を残し、 拒否済み、非推奨の場合はここに理由を追記し、 置き換え済みのの場合は置き換えたアーキテクチャや別のADRへのリンクを記載します。 ## 影響 決定がプロジェクトとその成果物に及ぼす影響について記載します。 特に既存のアーキテクチャの変更の場合は重要な内容です。 ### 導入コスト アーキテクチャを導入する際に必要な作業コストを見積もります。 考慮事項：PoC検証の必要性、導入対象の総数、作業担当者の人数、作業担当者の習熟度、納期 ### ランニングコスト アーキテクチャを導入した後に発生する利用料金コストを見積もります。 AWSなどクラウドサービスの場合、月額の利用料金コストを記載します。 考慮事項：アーキテクチャを構成するサービス、SaaS、サーバースペック/サイズ ### 運用コスト アーキテクチャを導入した後に発生する運用コストを見積もります。 考慮事項：アーキテクチャを構成するサービスやSaaSなどのアップデート、サーバー追加/アーキテクチャ変更対応時の作業コスト、定常作業オペレーション ## 代替案 アイディアレベルのものから中間レビューで決定には至らなかったアーキテクチャなどを記載します。 必ず決定しなかった理由を添えるようにします。 ## メモ 意思決定プロセスはさまざまな情報を抜け漏れなく取り込む必要があります。 レビュー対象には含めずとも記録としては残しておきたい内容はここに書き溜めておきます。
意識していること
記載するにあたり、意識していることは以下のとおりです。
言語化とすり合わせ
個人的には、これが最も重要なポイントだと思います。
とにかく状況や背景をそのまま言語化することが大切です。
言語化や語彙力が得意でなくても、誤解を恐れずに記載し、レビューを通じて補完しながら認識をすり合わせてドキュメントの整合性を保ちます。
わからない、あるいはうまく表現できないという理由で意思決定の根拠や前提背景が抜け落ちてしまってはADRの意味がなくなってしまいますし、人間は忘れる生き物です。
誤解を恐れずにありのままを記載することでレビューする人は指摘や解釈のすり合わせができ、忘れても記載があれば思い出すきっかけになります。
ただし、仕様の誤りや認識齟齬が最後まで残ると大問題になるため、そのような事態を避けるために部分的にでもレビューをしてもらうことが重要です。
？やTBD、会話の引用を活用する
記載時点で不明瞭な点や不確定要素がある場合は素直に「？」や「TBD」（To Be Determined）を添えて記載するようにします。 また、コミュニケーションツール（SlackやBacklog）や会話で得た情報はそのまま引用として即時にドキュメントに取り込みんでおき、 後で全体の整合性を保つように調整します。
ドキュメントの読み手を意識する
ドキュメントは書いて終わりではなく、運用されてこそ意味があります。
読み手にとって理解しやすいようにシンプルに構成し、必要に応じて別のドキュメントに切り出してリンクを記載したり、詳細を折りたたむなど工夫をします。
メリットとデメリット
ADRを運用していない場合と比較してのメリットとデメリットを挙げます。
メリット
基本設計書や概念ドキュメントのベースとなる
基本設計書の作成段階でベースが出来上がっている状態となり、認識のすり合わせや引用情報として利用することができ、スムーズに進行することが可能になります。
後々の変更や運用において安全で迅速な対応が可能
例えば、Backlogでプロジェクト管理をしているケースを考えてみましょう。
ADRを運用していない場合、意思決定の過程はBacklogのコメントや会議のアジェンダとしてWikiページに記載されることがよくあります。
しかし、この方法では、後にその仕組みに変更を加える担当者が、意思決定によって不採用となったアーキテクチャを誤って適用してしまう可能性があります。
また、運用担当者が影響のある部分に手を加える際に、重要な背景情報が抜け落ちているためにインシデントが発生するリスクも高まります。
ADRが運用されていればそのようなリスクを抑えることができ、アーキテクチャ変更の際には有益な参考情報として対応をスムーズに進めることができます。
デメリット
とにかく時間がかかる
ドキュメントを書く際、頭の中のイメージを言葉や表現に変換して文章に起こすのはかなり時間がかかります。
また、TBDや前提が変更された場合、それに伴う依存箇所を探して全体の整合性を保つための更新にも時間がかかります。
細かく丁寧に書く必要はないと思いますが、、最低限、記載者自身が後で見返した時に説明できる内容であるべきです。
この作業は「慣れ」と「ドキュメントの執筆能力」に依存しますが、書き続けることで相手に伝わりやすい書き方や無駄のない文章の構成が徐々に身についてくると思います。
私もまだまだ改善の余地がありますが、2、3回運用してみると、最初よりも書き方のコツがつかめてきたと感じるようになりました。
なくてはならないもの？
ADRは必須ではありませんが、アジャイル開発や中小規模プロジェクトでは有用だと感じています。 一方で大規模なウォーターフォールプロジェクトのように初期段階で基本方針や基本設計書などのアウトプットがしっかりと納品資料として定義されており、 かつそのドキュメント内に前提や背景のコンテキストが含まれる場合はADRの必要性は低いかもしれません。
必要性に関する内容はADRにもDesign Dogにも記載されています。
ADR
ADRはシステムを設計する際に行われたアーキテクチャの決定を記録する方法です。すべてのプロジェクトに必須ではありませんが、アーキテクチャの変更や決定の詳細な記録が必要なプロジェクトにとって有益です。
Design Docs
設計ドキュメントを書くことはオーバーヘッドです。設計ドキュメントを書くかどうかの決定は、明確な設計、ドキュメント、および上級レビューを持つことの利点が、追加作業のコストを上回るかどうかという基本的なトレードオフに帰着します。
デメリットに記載した通り、ADRの運用は少なからず追加の時間が発生します。
ただし、アーキテクチャ決定後の運用を円滑にしたいという意図がプロジェクトメンバー間で明確に定義されていれば、ADRを採用する価値はあると思います。
注意点
万能ではない
ADRは意思決定の覚書であり、システムの運用やセキュリティを保証するものではありません。 ADRを採用したからといってシステムの運用がうまく回ったり直接的にセキュリティリスクを下る効果はありません。
また、ADR自体の運用がうまく回るかどうか、意味のあるドキュメントになるかどうかは 書き手の能力やプロセスの進め方に大きく左右されると思います。
方針迷子に注意
前提や背景が整理されていない状態でADRを記載すると、承認フローでの手戻りや無駄な確認作業が発生する可能性があります。
常に整理すべき事柄、その依存関係、確認期限、不透明な部分を意識し、
頻繁にステークホルダーとコミュニケーションをして方針迷子にならないように注意しましょう。
プロジェクトに根付かせるポイント
もしもこれからチームやプロジェクトにADRを推進する場合、 考慮するポイントを考えました。
フォーマットを決める
まずはフォーマットを用意します。
世の中のフォーマットに縛られすぎないように最小限の項目に絞ります。
必要最小限のものから始め、運用が回るようになったり改善点が浮上した時にフォーマットを修正していくと良いと思います。
フォーマットが決まったらテンプレート化して、書き手の負担を減らします。
書き手の意識
プロジェクトでADRの記載ルールを設けることは良いですが、書き手が窮屈にならないように、ルールに柔軟性を持たせることも重要ですし、書き手としても縛られすぎないように意識することも重要です。
運用に際して作業時間が増えたり認知負荷が上がりすぎると、これまでうまくいっていたことが疎かになり、精度が落ちる可能性があります。
ステークホルダーへメリットを実感してもらう
これが一番効果が高いですが、ハードルも高いと思います。
しかしADRやDesign Docsの本質からすると、ここまで達する必要があります。
意思決定の最終決断者や運用担当者にADRを共有し、適切なタイミングで引用情報として共有することで、最大の成果を得られます。
このブログもADRを根付かせる活動
一般的にADRやDesign Docsが普及されているかどうかはわかりませんが、
私の周りのプロジェクトでADRを採用しているケースはほとんどないのが現状です。
もし取り扱うシステムや進行中のプロジェクトにおいてもっと円滑に運用を進めたいといった意思があるならば、
ぜひ、本ブログを機に採用を検討してみてください。
最後に
個人的にはADRもDesign Docも運用してまだ間もない状況ですので、 もしより良いカイゼンや更新があればブログでご紹介したいと思います。
どなたかの参考になれば幸いです。
