背景
ソフトウェア開発における意思決定を記録するための手法、Architecture Decision Record (ADR)。その有用性は広く知られていますが、多くの場合、テンプレートは英語で提供されています。
これまで私もADRの導入を検討する中で、テンプレートの存在は認識していたものの、日本語での具体的な活用例が少ないと感じていました。そこで、先日、既存のADRテンプレートを日本語に翻訳し、実際にコントリビュート（自分なりに試してみること）してみました。
本記事では、その翻訳とコントリビュートの過程で得られた学びを共有したいと思います。
翻訳先は以下から見ることができます。
また、ADRの作成に便利なツールadrowseも作ったので、ADRの実践例としても興味深いと思うのでぜひ見てみてください！
翻訳を通して深まったADRの理解
この記事を書く前にもいろいろな記事を見ていましたが（例：https://qiita.com/fuubit/items/dbb22435202acbe48849）
日本語で見つかる記事はどれもMichael Nygard による意思決定記録テンプレートに沿ったものでした。
ですが、いざ翻訳してみると、それだけではなく様々なユースケースを想定したテンプレートがあったり、それの運用についても触れられているドキュメントもあり、ADRというものの解決方法がとても多いということがわかりました。
このリポジトリ自体はあちこちの記事や論文を集めたものですが、作者の情報収集能力からくる素材の豊富さに目から鱗が落ちます。
他にもなぜ働くのかやキュー戦略も書かれているのでこの作者はフォローすべきです。
翻訳してみて得られた教訓8選
1. ADRの作成とADRの所有権
ADRは誰でも作れますが、所有者は明確に決めないといけません。ADRの所有者はADRを維持管理する必要があります。
維持管理を誰がやるのか責任を持つ人がいないとADRのフローがうまく回りません。
以下はADRのフロー図です。
ADRオーナーがレビューにおいて中心的な役割を果たしていると思います。
今まで日本語の記事ではADRオーナーについて触れられていなかったのでこの考え方は新鮮でした。
レビューについてのプロセスは普段のレビューに関しても役立つから読むといいかもしれません。
レビュー会議は、ADRを読むための専用の時間枠を設けることから始めます。平均10～15分あれば十分です。この時間内に、各チームメンバーはドキュメントを読み、不明な点があればコメントや質問を追加します。レビューフェーズの後、ADR所有者は各コメントを読み上げ、チームと話し合います。
レビュープロセスのスケジュール変更はADRオーナーの責任です。
2. 良いADR作成のための提案
これだけでも読んでほしい記事です。
良いADRの特徴：
- 根拠を示すこと: 特定のADを実施する理由を説明します。これには、「背景」（下記参照）、様々な選択肢の長所と短所、機能の比較、費用対効果の検討などが含まれます。
- 具体的であること: 各ADRは、複数のADではなく、1つのADについて記述する必要があります。
- タイムスタンプ: ADRの各項目がいつ作成されたかを明確にします。これは、コスト、スケジュール、規模感など、時間の経過とともに変化する可能性のある要素において特に重要です。
- 変更不可であること: ADR内の既存の情報を変更しないでください。代わりに、新しい情報を追加してADRを修正するか、新しいADRを作成して既存のADRを置き換えます。
- なぜそう決めたのか
- どういった決定なのか
- いつの決定なのか
- それは書き換えられていないか
といったことはADRの存在意義にも近いものです。
これは常に意識しておきたいところで、コミットメッセージにも通じるものがあると思います。
3. ADRはリンクさせる
ADRの中には大きなADRがあってそれがさらに小さいADRを引き起こすこともあります。
小さい意思決定が大きな意思決定の結果導かれたものならば、それをドキュメントに含めておくことで、後からその変更がなぜ行われたのか分かりやすくなります。
さらに言うと、どの決定がどれくらいの重要度があるかというのは、新しく来た人やその分野に精通していないとわからないことです。
ある決定Aがあって、それが決定Bと矛盾していると違和感のもとになります。
決定Cがあって、そちらのほうが重要になり、決定Aはそちらの方を優先したとわかっていればすんなり理解できます。
別の選択肢があればそちらの提案が十分に検討されていないのであれば別の決定の道もあります。
ADRがどう関連しているかはわかりやすくしましょう。
とはいえ、ドキュメントのメンテナンスって誰もやりたがらないので、所有者を決めてメンテナンスさせるのはやはり重要なのですね。
4. 「結果」セクションの導入
最も簡素で日本でも広まっているADRテンプレートといえば、Michael Nygardによるテンプレートですが、そこには「影響」のセクションはあっても「結果」のセクションはありません。
その決定が何をもたらしたのか、というのを記すのはADRの中に書いてしまうのが一番手っ取り早いです。
それはイミュータブルにするという原則に反しているかもしれませんが、結果セクションはADRではないという解釈をすれば大丈夫そう。
また、事後レビュープロセスがあればそこで何かした記録を残したいと思うのでそれをどこかに置いておくためにも「結果」セクションは重要です。
5. 「他の選択肢」セクションについて
まだ参画して間もないとこれはなぜこうなったかという疑問とともに、なぜこれをしなかったのかという疑問が生まれます。そしてそれは往々にしてどこのドキュメントにも書いていませんし、きちんとした検討もされていないことが多いです。最終レビュー中に「…について検討しましたか？」という質問は避けたいものですが、これは信頼性の低下を招き、他のアーキテクチャ上の決定に疑問を投げかけることになります。このセクションは、他者の意見を聞いて、それを受け止めたうえで現在の意思決定に至ることを保証します。
書かれていれば、「背景」のセクションの中に書いてもいいかもしれませんが、書いていない、ということはなしにしたい情報ですね。
6. ADRの置き場所
チームによっては、「ADR」という略語よりも「決定」という名称を好むところもあります。とあるチームでは、「decisions」というディレクトリを使うことで、まるで電球が点いたかのように、ベンダーの決定、計画の決定、スケジュールの決定など、より多くの情報をディレクトリに入力し始めました。これらの情報はすべて同じテンプレートを使用できます。私たちは、略語（「ADR」）よりも単語（「decisions」）の方が学習が早くなる、また「record」という単語を削除することで作業中のドキュメントを作成する意欲が高まる、そして一部の開発者やマネージャーは「architecture」という単語を嫌う、という仮説を立てています。
実際に先ほどあげたadrowseではdocs/decisionsをデフォルトのディレクトリにしてます。
ここに意思決定ログを置いていますが、ArchitectureのAは専門的な感じがして、他人事のように聞こえてしまうので入れていません。
ADRなので設計に関するログだけ入れればいいかというとそうではなく、なぜそうなったかを知りたいがためにADRを入れているわけで、事後報告を入れているわけではないのです。
単に「decisions」とすることは設計のその前にある企業やユーザー、社会課題を考えることでもあるのです。
（図はオニオンモデルにおける要求モデル）
7. ADRには、少なくとも1つの関連する承認済みユースケースが必要
ADRを承認するには何らかのユースケースを置くようにするというルールを設けているところもあります。
個人的にはこれは厳しいものでもあり、あるに越したことはないのですが、ドメインエキスパートがユースケースを言語化できる訓練を受けていなかったり、言語のほうが整っていないことも新しい領域ではままあることです。
これについては厳しくて導入しづらいルールだなと思いました。
8. 意思決定の整理
意思決定ログが数百個、数千個とたまってくるとさすがに整理したいという気持ちにかられると思います。
統合、プレゼンテーション、データといった単純なグループ分けを用いて、一連の意思決定を整理したり、より洗練されたアーキテクチャオントロジーもあります。意思決定をグループ化すれば、システムが情報を必要とする事象に対応する意思決定を「イベント」の下にグループ化することができて、より抽象度が高く包括的な問題に対処できます。
おすすめテンプレート
手っ取り早く取り入れたい人向け！ Michael Nygard による意思決定記録テンプレート
一番簡単なテンプレートで、日本語でもよく見るテンプレートです。以下の4つだけのセクションでできており、最も手軽に始めることができます。
# タイトル
## ステータス
提案済み、承認済み、却下済み、非推奨、置き換え済みなど、どんなステータスか？
## 背景
この決定または変更の動機となっている問題は何か？
## 決定
提案または実施する変更は何か？
## 影響
この変更によって、何が簡単になり、何が難しくなるか？
導入しやすくて後で役に立つ！ アレクサンドリアパターンの意思決定記録テンプレート
オックスフォード大学のクリストファー・アレキサンダーが1979年に「The Timeless Way of Building」で触れたアレクサンドリアパターンを元にしたテンプレートです。
最初に要点を説明しつつ、詳細を説明することでストーリー性のある決定ログに仕立てることができます。
また、結果について触れられているテンプレートでもあります。
## はじめに
* プロローグ（要約）
* 議論（背景）
* 解決策（意思決定）
* 成り行き（結果）
## 詳細 ##
* プロローグ（概要）
* 宣言の要約：
* （ユースケース）の状況において、<br>
（懸念事項）に直面し、<br>
（品質）を達成するために、<br>
（欠点）を受け入れ、<br>
（オプション）を決定しました。
* 議論（背景）
* 影響する力（技術的、政治的、社会的、プロジェクト的）についての説明をする。
* 解決しようとしている問題を説明するストーリーを書く。
* 解決策
* この決定がどのように問題を解決するかを説明する。
* 結果
* 決定の長期的な結果について説明する。
* うまくいったか、うまくいかなかったか、変更されたか、アップグレードされたかなどについて説明する。
細かくて大規模向け！ Planguageを使用した意思決定記録テンプレート
Planguageは、品質特性を可視化するためにGilbが提案したテンプレート形式の表記言語です。
詳細はこれを見てほしいのですが、細かいことがたくさん書いてあり、まさしく大規模なところや厳密性が要求されるところで役に立つテンプレートです。
* タグ: 一意で永続的な識別子
* 要点: 要件または対象となる領域の簡潔な要約
* 要件: 要件自体の詳細を記述したテキスト
* 根拠: 要件を正当化する根拠
* 優先度: 優先度とリソースの要求に関する記述
* 利害関係者: 要件によって実質的に影響を受ける関係者
* ステータス: 要件のステータス (ドラフト、レビュー済み、コミット済みなど)
* 所有者: 要件の実装責任者
* 作成者: 要件を作成した人物
* リビジョン: 記述のバージョン番号
* 日付: 最新のリビジョン日
* 前提条件: 現在または将来、不正確であれば問題を引き起こす可能性のあるもの
* リスク: 誤動作、遅延、その他の悪影響を引き起こす可能性のあるもの
* 定義: 用語の定義 (用語集を使用することをお勧めします)
Bizの人向け！ ビジネスケース用意思決定記録テンプレート
コスト分析やSWOT分析の結果も含まれておりまさしくビジネス向けのテンプレート。
ADR自体がDevよりの言葉なので、何も言わなければDevよりに話が及びそうだけれども、これならBiz側も使えるテンプレートなので、
Bizも一緒にやろう！(その前の分析が大変だけど)
## トップレベル
* 役職
* ステータス
* 評価基準
* 検討すべき候補者
* 各候補者の調査と分析
* 基準を満たしているか満たしていないか、またその理由
* コスト分析
* SWOT分析
* 意見とフィードバック
* 推薦
## ロウレベルの詳細な説明
**タイトル**:
* Gitのコミットメッセージのように、50文字未満の短いフレーズ。
**ステータス**:
* 提案、承認、拒否、非推奨、置き換えなどのいずれか。
**評価基準**:
* 概要: 発見したい内容とその理由を簡潔に説明してください。
* 詳細
**検討すべき候補**
* 要約：候補をどのように発見したかを簡潔に説明し、外れ値があれば注意喚起してください。
* すべての候補と関連する選択肢をリストアップしてください。潜在的な解決策として何を評価していますか？
* 詳細
**各候補者の調査と分析**
* 要約：調査方法を簡潔に説明し、パターン、クラスター、外れ値に注目してください。
* 基準を満たしているか満たしていないか、またその理由を記載してください。
* 要約
* 詳細
* コスト分析
* 要約
* 例
* ライセンス（契約合意や法的義務など）
* トレーニング（スキルアップや変更管理など）
* 運用（サポートや保守など）
* 計測（帯域幅やCPU使用率など）
* SWOT分析
* 要約
* 強み
* 弱み
* 機会
* 脅威
* 社内の意見とフィードバック
* 要約
* 例
* チームによる（できれば担当者が作成）
* 他のステークホルダーからの意見
* 品質特性、すなわち横断機能要件
* 外部からの意見とフィードバック
* 要約
* 意見提供者は誰ですか？
* 他に検討した候補は何ですか？
* 何を作成していますか？
* 例
* B2B または B2C
* 社外向けまたは従業員専用
* デスクトップまたはモバイル
* パイロット版または本番環境
* モノリス版またはマイクロサービス版
* 候補をどのように評価しましたか？
* なぜそれを選んだのですか？
* その後、どのような変化がありましたか？
* 例
* 選んだもののパフォーマンスはどうですか？
* 実際の運用環境におけるユーザートラフィックの何パーセントが選んだものを経由していますか？
* 継続的デリバリーパイプライン、コンテンツ管理システム、分析機能、メトリクスなど、どのような統合が行われていますか？
* 現在の知見を踏まえて、人々にどのようなアドバイスをしますか？
* 逸話
**推奨事項**:
* 概要
* 詳細
実例を知りたい人向け! madrプロジェクト
実際にmadrプロジェクトで使われているテンプレート。
実例がここにあってどう使われているか知りたい人におすすめ。
ちゃんとディレクトリもdocs/decisionsにあってうれしい。
# [解決された問題と解決策の短いタイトル]
* ステータス: [提案 | 却下 | 承認 | 非推奨 | … | [ADR-0005](0005-example.md) に置き換え]等 <!-- 省略可能 -->
* 決定者: [決定に関与した全員をリストアップ] <!-- 省略可能 -->
* 日付: [決定が最後に更新された YYYY-MM-DD] <!-- 省略可能 -->
技術的なストーリー: [説明 | チケット/課題の URL] <!-- 省略可能 -->
## 背景と問題提起
[背景と問題提起を、例えば2～3文で自由記述してください。問題を質問形式で明確に表現してもよいでしょう。]
## 意思決定推進者 <!-- 省略可能 -->
* [推進者1、例: 力、直面している懸念事項、…]
* [推進者2、例: 力、直面している懸念事項、…]
* … <!-- 推進者の数は異なる場合があります -->
## 検討対象となるオプション
* [オプション 1]
* [オプション 2]
* [オプション 3]
* … <!-- オプションの数は異なる場合があります -->
## 意思決定結果
選択された選択肢：「[選択肢 1]」。[理由。例：k.o.基準を満たす唯一の選択肢、意思決定要因 | フォースフォースを解決する | … | が最善の結果をもたらす（下記参照）]。
### 肯定的な結果 <!-- 省略可能 -->
* [例：品質特性の満足度の向上、フォローアップの意思決定が必要、 …]
* …
### 否定的な結果 <!-- 省略可能 -->
* [例：品質特性の低下、フォローアップの意思決定が必要、 …]
* …
## オプションの長所と短所 <!-- 省略可能 -->
### [オプション 1]
[例 | 説明 | 詳細情報へのポインタ | …] <!-- 省略可能 -->
* 良い。なぜなら [議論 a]
* 良い。なぜなら [議論 b]
* 悪い。なぜなら [議論 c]
* … <!-- 長所と短所の数は変化する可能性があります -->
### [オプション 2]
[例 | 説明 | 詳細情報へのポインタ | …] <!-- 省略可能 -->
* 良い。なぜなら [議論 a]
* 良い。なぜなら [議論 b]
* 悪い。なぜなら [議論 c]
* … <!-- 長所と短所の数は変化する可能性があります -->
### [オプション 3]
[例 | 説明 | 詳細情報へのポインタ | …] <!-- 省略可能 -->
* 良い。なぜなら [議論 a]
* 良い。なぜなら [議論 b]
* 悪い。なぜなら [議論 c]
* … <!-- 長所と短所の数は変化する可能性があります -->
## リンク <!-- 省略可能 -->
* [リンクの種類] [ADR へのリンク] <!-- 例: [ADR-0005](0005-example.md) によって絞り込まれました -->
* … <!-- リンクの数は異なる場合があります -->
おまけ：Jeff TyreeとArt Akermanによる意思決定記録テンプレート
難しい話の多いテンプレート。
REMAPモデルとかRoseモデルとか調べても日本語はおろか優しい記事もなかった。
頑張りたい人むけ？
これは、[Capital One FinancialのJeff TyreeとArt Akerman著『Architecture Decisions: Demystifying Architecture』](https://www.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf)に掲載されているアーキテクチャ意思決定記述テンプレートです。
* **課題**: 取り組んでいるアーキテクチャ設計上の課題について説明し、なぜ今その課題に取り組むのかという疑問を残さないようにしてください。最小限のアプローチに従い、ライフサイクルの様々な段階で対処が必要な課題のみを取り上げ、文書化してください。
* **決定**: アーキテクチャの方向性、つまり選択した立場を明確に述べてください。
* **ステータス**: 決定のステータス（保留中、決定済み、承認済みなど）
* **グループ**: 統合、プレゼンテーション、データといった単純なグループ分けを用いて、一連の意思決定を整理することができます。また、John Kyaruzi氏とJan van Katwijk氏による、イベント、カレンダー、場所といったより抽象的なカテゴリを含む、より洗練されたアーキテクチャ[オントロジー](https://ja.wikipedia.org/wiki/%E3%82%AA%E3%83%B3%E3%83%88%E3%83%AD%E3%82%B8%E3%83%BC_%28%E6%83%85%E5%A0%B1%E7%A7%91%E5%AD%A6%29)を使用することもできます。例えば、このオントロジーを用いて、システムが情報を必要とする事象に対応する意思決定を「イベント」の下にグループ化することができます。
* **前提**: 意思決定を行う環境における根本的な前提（コスト、スケジュール、テクノロジーなど）を明確に記述します。環境上の制約（一般的なテクノロジー標準、エンタープライズアーキテクチャ、一般的に採用されているパターンなど）によって、検討できる選択肢が制限される可能性があることに注意してください。
* **制約**: 選択された代替案（決定）が環境にもたらす可能性のある追加の制約をすべて記録します。
* **立場**: 検討した立場（実行可能な選択肢または代替案）をリストアップします。これらの説明には長い説明が必要になることが多く、モデルや図表が必要になる場合もあります。これは網羅的なリストではありません。しかし、最終レビュー中に「…について検討しましたか？」という質問は避けたいものです。これは信頼性の低下を招き、他のアーキテクチャ上の決定に疑問を投げかけることになります。このセクションは、他者の意見を聞いたことを確認するのにも役立ちます。他者の意見を明示的に述べることで、その支持者をあなたの決定に賛同させることができます。
* **論拠**: 実装コスト、総所有コスト、市場投入までの時間、必要な開発リソースの可用性など、あるポジションを選択した理由を概説します。これは、おそらく決定自体と同じくらい重要です。
* **影響**: REMAPメタモデル（注：Representation and Mainte
nance of Process Knowledge）が示すように、決定には多くの影響が伴います。例えば、ある決定によって、別の決定を行う必要性が生じたり、新しい要件を作成したり、既存の要件を変更したり、環境に新たな制約が生じたり、顧客とスコープやスケジュールの再交渉が必要になったり、スタッフの追加トレーニングが必要になったりする可能性があります。決定の影響を明確に理解し、明確に伝えることは、承認を得てアーキテクチャ実行のロードマップを作成する上で非常に効果的です。
* **関連する決定**: 多くの決定は関連していることは明らかであり、それをここで列挙します。ただし、実際には、トレーサビリティマトリックス、決定木、またはメタモデルの方が有用であることがわかりました。メタモデルは、複雑な関係を図式で示すのに役立ちます（[Rose](https://www.ibm.com/docs/ja/rsm/7.5.0?topic=migration-rational-rose-model)モデルなど）。
* **関連する要件**: 決定はビジネス主導で行う必要があります。説明責任を示すために、決定を目標または要件に明示的にマッピングします。これらの関連要件をここで列挙することもできますが、私たちの経験上、トレーサビリティマトリックスを参照する方が便利であることがわかりました。各アーキテクチャ決定が各要件の達成にどのように貢献しているかを評価し、さらにすべての決定において要件がどの程度達成されているかを評価できます。ある決定が要件の達成に貢献しない場合は、その決定は行わないでください。
* **関連成果物**: この決定が影響を与える関連するアーキテクチャ、設計、またはスコープに関するドキュメントの一覧。
* **関連原則**: 企業内で合意済みの原則がある場合は、決定がそれらの原則の1つ以上と整合していることを確認してください。これにより、ドメインまたはシステム間の整合性を確保できます。
* **メモ**: 意思決定プロセスには数週間かかる場合があるため、共有化プロセス中にチームが議論したメモや問題点を記録しておくことが有用であることがわかりました。
感想
コントリビュートによる実践的な学び
翻訳したテンプレートを使って、過去のプロジェクトにおける技術的な意思決定をいくつか記録してみました。このプロセスを通じて、以下の点を実感しました。
- 意思決定の可視化: 当時は当たり前のように進めた決定も、改めて文章化することで、その背景や理由が明確になりました。
- 議論の活性化: チームメンバーと過去のADRを共有することで、当時の議論を振り返り、より深い理解につながりました。
- 知識の継承: 新しいメンバーがプロジェクトにjoinする際、過去の意思決定とその理由をスムーズに伝えるための貴重なドキュメントになると感じました。
今後の展望
今回のコントリビュートを通じて、日本語でのADR活用の可能性を強く感じました。今後は、今回作成した日本語テンプレートをチーム内で共有し、実際の開発プロジェクトで本格的に導入していく予定です。
また、今回の学びを活かし、より洗練された日本語テンプレートを作成し、コミュニティにも共有できればと考えています。
ADRの導入を検討されている方、特に日本語での情報が少ないと感じている方の参考になれば幸いです。
adrowseについて
テンプレートを配置するツールはあちこちあって一番有名なのがこれ。
こういったものも悪くはないけれど、日本語のものはない！！
ドキュメントに関しては日本人は日本語で書くので英語のテンプレートなんか用意してもうれしくない！
それにadr-toolsの場合、シェルスクリプトでできているのでWindowsでは動かない！
幅広い人に書いてほしいのに言語やOSで縛られてはいけない！とそう思ったので自分で作りました。
もちろんADRと戦っている例もありますし、こういった機能追加してほしいとかあったらissueお願いします！