はじめに
ある時、プロジェクトの開発に一区切りついた私は、パワーポイントでそのアーキテクチャや詳細設計についてまとめていました。
その流れで、ドキュメンテーションについて上司と話していると、ポロっとこんな言葉が。
ドキュメンテーションって結局陳腐化しちゃうんですよね。。。
ADR というのをやりたいけど、それはそれで仕組みがしっくりこなくて。。。
陳腐化。
確かに、実装が変わるたびにドキュメントもメンテナンスし続けるというのは、なかなか難しいことですよね。わかります。
あれ…でも、そもそもADRってなんだ…？
簡単にググってみても裁判関係の情報しか出てこないんだが。
上司は裁判やろうとしてるのか…？ いやまさか。
わからないので調べてみることにしました。
ADRとは
ADR は「Architectural Decision Record」の略で、**「システムの設計について、何を・なぜそう決めたのかを残しておく記録」**とのことです。
システム開発では、さまざまな設計上の判断をしますよね。
たとえば、
- データベースには何を使うか
- 認証方式をどうするか
- どのクラウドサービスを利用するか などなど。
こうした判断の直後であれば、「なぜそれを採用し、他を不採用にしたのか」がはっきりしているでしょう。
ですが、半年後や1年後になるとどうでしょうか…？
会議やチャットで話しただけだったり、当時の担当者しか経緯を知らなかったりして、「なんでこの構成にしたんだっけ？」という部分がうやむやになってしまう…。
そこで、アーキテクチャ上の重要な判断について、
- どんな背景や課題があったのか
- どんな選択肢があったのか
- 最終的に何を選んだのか
- なぜそれを選んだのか
- その決定によってどんな影響があるのか
といった内容を記録しておくのがADRなんです！
…裁判の話じゃなかった。。。。
ADRに書くこと
ADRには、単に「何を採用したか」だけではなく、その判断に至った背景や理由も残します。
たとえば、
認証にはMicrosoft Entra IDを使用する
だけでは、現在の設計は分かっても、なぜその方式を選んだのかまでは分からないですよね。
そこで、たとえば次のように記録します。
独自認証も候補として検討したが、Microsoft 365とのSSOが必要であり、認証情報を自前で管理するコストも避けたかったため、Microsoft Entra IDを採用した。
こうしておけば、あとから見た人も「なぜEntra IDなのか」を理解できますね。
ADRの書き方にはいくつかありますが、基本的には次のような内容を記録するようにするとよいと言われています。
- Status：この意思決定の状態
- Context：どんな背景や課題があったのか
- Decision：最終的に何を選んだのか
- Consequences：その判断によってどんな影響があるのか
Statusには、たとえば次のようなものがあります。
| Status | 意味 |
|---|---|
| Proposed | 提案中 |
| Accepted | 採用済み |
| Rejected | 不採用 |
| Deprecated | 現在は非推奨 |
| Superseded | 別のADRによって置き換えられた |
たとえば、先ほどのMicrosoft Entra IDの例をADRとして書くと、次のようになります。
# ADR-001: 認証基盤としてMicrosoft Entra IDを採用する
## Status
Accepted
## Context
ユーザー認証の方式を決める必要がある。
候補として、独自認証とMicrosoft Entra IDを検討した。
Microsoft 365とのSSOが必要であり、認証情報を自前で管理するコストも避けたい。
## Decision
認証基盤としてMicrosoft Entra IDを採用する。
## Consequences
### メリット
- Microsoft 365とのSSOを利用できる
- 認証情報を自前で管理する必要がない
### デメリット
- Microsoft Entra IDへの依存が生じる
- アプリ登録やテナント設定に関する知識が必要になる
このように書いておくことで、意思決定の履歴を残しておくことができるわけですね。
ADRはどう管理するのか
ADR は Gitのようなソースコード管理、Google Docs、Jiraなどのプロジェクト管理ツール、Wikiなど、さまざまな方法で管理できるとされています。
| 管理方法 | 管理イメージ |
|---|---|
| Git | ADRをMarkdownなどのファイルとしてリポジトリに保存する |
| Wiki | WikiにADRごとのページを作成する |
| ドキュメント管理ツール | Google DocsやConfluenceなどでADRを管理する |
| チケット管理ツール | Jiraなどで意思決定をチケットとして管理する |
| ADR管理を支援するツール | ADRの作成・検索・表示などを支援するツールを利用する |
| 複数の方法を組み合わせる | Gitを原本として、Web上から閲覧できるようにするなど |
このように管理方法にはいくつか選択肢がありますが、その中でもよく見かけるのが、Gitで管理する方法です。
ADRがコードと同じく「変更される成果物」で、しかもMarkdownと相性がいいというのが主な理由のようですね。
- コードの近くに置ける
- 履歴を残せる
- 差分を見やすい
- Pull Requestでレビューできる
- 実装とADRを一緒に変更できる
ADRは陳腐化しないのか？
ここまで調べて ADR についてはなんとなくわかってきました。
では、 ADR を使ったらドキュメントの陳腐化は防げるのでしょうか…？
もちろん、ADRも陳腐化しないわけではありませんが、一般的な詳細設計書と比べると実装変更の影響を受けにくいという特徴があるといえるでしょう。
たとえば、
認証方式としてMicrosoft Entra IDを採用する
という設計判断があったとします。
普通のドキュメントに、
認証方式はMicrosoft Entra IDとする
だけ書いてあると、後から別方式に変わった時点で、その記述は更新が必要になります。
一方ADRでは、
Microsoft 365とのSSOが必要だったため、Microsoft Entra IDを採用した
という当時の判断理由を残すのが目的です。
現在の正しい設計状態を説明するための文書というより、意思決定の履歴を残す文書なので、設計が変わったからといって過去のADR自体が無意味になるわけではない、ということです。
そういう意味では陳腐化はしにくいと言えます。
それでも「仕組みがしっくりこない」のはなぜか
なんか、ここまで調べていると ADR 、めっちゃよさそうじゃないですか！
でも、上司が「仕組みがしっくりこない」って言ってたのはなんででしょうか。。。。
1つのプロジェクト内でのファイルの管理が大変！
たとえば、一度AcceptedになったADRでも、後から別の判断に置き換わることがあります。
その場合は、古いADRを消すのではなく、
- 新しいADRを作成する
- 古いADRを
Supersededに変更する - 新旧のADRを紐付ける
- 一覧やインデックスにも変更を反映する（手動管理の場合）
といった管理が必要になります。
つまり、1つ意思決定が変わっただけでも、1ファイル直して終わり、とはならないわけです。。。。。
結構多いですよね。。。
会社全体でADR使おうとしたらもっと大変！
会社全体でADRを運用しようとすると、さらに考えることが増えてきます。
たとえば、
- プロジェクト固有のADR
- 会社全体に関わるADR
の両方が必要になるケースです。
プロジェクト固有のADRであれば、そのプロジェクトのGitリポジトリに置けばよさそうですが、
全社的に認証基盤はこの方式を採用する
といった会社全体に関わる意思決定は、特定のプロジェクトだけに置くわけにはいきません。
そうなると、
- プロジェクトのADR → 各リポジトリ
- 全社ADR → 別の場所
というように、ADRの置き場所が分かれます。
利用する側からすると、設計を考えるたびにプロジェクト側と全社側の両方を確認する必要が出てくるわけです。。。
そして、プロジェクト側と会社側とで置き場所が分かれると、
- このプロジェクトに関係するADR
- 認証に関係するADR
- 現在
AcceptedになっているADR - 過去に
SupersededになったADR
などを、プロジェクト単位・会社全体をまたいで検索したくなりそうです。
そうなると、単純にGitリポジトリへMarkdownを置くだけではなく、複数の場所にあるADRをまとめて検索・一覧できる仕組みも欲しくなってきます。
検索や閲覧のしやすさを考えれば何らかのツールを使う方法も考えられますが、
プロジェクトのADRはコードの近くに置きたい
でも会社全体のADRも一緒に探したい
という両方をうまく満たす仕組みを考えるのは、なかなか簡単ではなさそうです。
さらにさらに、「全社ADRとプロジェクトADRで判断が違う場合は？」、「1つの全社ADRの変更が複数プロジェクトに影響する場合は？」…と、色々考慮すべきパターンが多くありそうです…。。。
うーーーん、、、、ADRそのものはシンプルですが、「どう書くか」よりも、「どう更新し、整理し、使い続けるか」というところまで考えると、結構継続的な運用が難しい側面もありそうですね…。
まとめ
今回調べてみて、ADRは「なぜその設計にしたのか」を残すという点で、比較的陳腐化しにくいドキュメントの形だということはわかりました。
設計が変わったあとも意思決定の記録として価値が残るというのはいいところでしたね。
一方で、運用を続けていけるのかという視点が大切だということに気づかされました。
その運用方法の考慮も、自分のプロジェクトではどうかというのみならず、他のプロジェクトも含めるとどうか、会社全体でだとどうかと広い視点で考えると、意外と奥が深いものだなと感じました。
ドキュメントは「作ること」よりも、どうすれば無理なく維持し続けられるかまで含めて設計することが大切なのかもしれません。