こんにちは。みらい翻訳のtoshと申します。

私は社内でSRE-SWEというチームに所属しており、主に既存システムのアーキテクチャ刷新をミッションとしています。

具体的な業務としてはアーキテクチャ刷新に必要な基盤の整備やガイドラインの制定を実施しています。

その中で、基盤やガイドラインの共有方法や整備の仕方に対してチーム内で課題感を持っていたところ、とあるメンバーからアーキテクチャデシジョンレコード（以下ADR）が提案されました。

軽量なフォーマットで書きやすく、テキストベースであるため差分管理も簡単であるADRはチーム内でもすぐに受け入れられ、ADRを必要に応じて書くこととそのフォーマットが決定しました。

今回はADRの紹介と実際に利用しているフォーマットを紹介します。

アーキテクチャディシジョンレコード(ADR)とは

こちらのGithub リポジトリには以下のように記載があります。

An architecture decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

こちらを弊社から提供しているChrome拡張のみらい翻訳にかけた結果は以下の通りです。

アーキテクチャ意思決定記録 (ADR) は、アーキテクチャに関する重要な意思決定とそのコンテキストおよび結果を記録したドキュメントです。

アーキテクチャの内容は重要ですが、それがどのように意思決定されて、どのような背景で行われたのかがわかっていないと守る意義がわからなくなる可能性があると考えています。守る意義がわからないアーキテクチャやルールは、遵守する立場からするとかえって邪魔なものに感じてしまうことがあると考えています。

また、アーキテクチャやルールは適切にメンテナンスされなければ陳腐化してしまうことがあると考えています。私も過去に制定されて数年放置されたコーディング規約を邪魔だと感じた経験があります。どれが本当に守らなければいけないもので、どれが陳腐化して無効となっているのかも管理できるようにすべきだと考えています。ADRはこのような事象にも対応できるものとなっています。

ADRのフォーマット

実際に以下のフォーマットを利用してADRを書いています。

# タイトル


# ステータス


# コンテキスト 


# 決定


## 決定理由


# 影響


# コンプライアンス


# 代替案


# 備考

| 著者 | 承認日 | 更新日 | 更新内容の概略 |
| ---- | ---- | ---- | ---- |
| xxx | xxxx/xx/xx | xxxx/xx/xx | xxxxxxxxx |

各項目の説明

以下は各項目の説明と弊社内でのルールを記載しています。

タイトル

そのままの意味です。弊社では連番を振るようにしています。

ステータス

コメント募集、提案済み、承認済み、破棄のいずれかを書くようにしています。

ステータス	説明
コメント募集	ステークホルダーからのコメントを受け付けている状態
提案済み	レビュワーにレビュー依頼済み
承認済み	レビュワーからの承認済み
破棄	新たな決定に取って代わられた状態新たな決定へのリンクを貼ること

コンテキスト

決定に関わる背景・前提知識を書きます。

決定

決定とその理由を書きます。また、詳細な決定理由を任意のフォーマットで記載します。他候補との比較と他候補を選定しない理由（決定と他候補の間で何がトレードオフなのか）を説明します。

影響

この決定による影響を書きます。チーム内外問わず記載し、この決定に対して何がトレードオフとなっているのかを明らかにします。

コンプライアンス

この決定をどのように順守させるのか、チェックの方法を明らかにしておきます。チェックの方法とは、例えば以下のようなものがあります。

チームメンバーがコードレビューで確認する
CIにテストケースを組み込む

基本的には自動的にチェックがされるのが望ましいと考えていますが、レビュー等の人力のものでも可としています。

代替案

決定を守れない場合の代替案があれば記載しておきます。

備考

フォーマットに記載した表のフォーマットで記載します。また、以下のようなルールも制定しています。

ステータス承認済みになったバージョンの「-」を承認日に編集する
ステータス編集はレビューイーが実施すること
変更があれば、更新日降順になるように行を追加する
承認日の編集は行追加不要とする
変更による行追加は適度な単位でマージしてよいものとする
例えば、コメント募集〜承認済みとなるまでに複数のコメントを受け付けて訂正することが想定されるが、まとめて「コメント修正」といった1行のみの追加としてもよい

参考資料

主にこちらの書籍を参考にルールを作りました。

O'Reilly Japan - ソフトウェアアーキテクチャの基礎

導入してよかったこと

まだ導入して間もないですが、チーム内で以下のような声が上がっています。

選定理由の全体をドキュメントに書くとドキュメント全体のボリュームが大きくなるため端折ってしまうことがあるが、ドキュメントと別の資料となることで比較検討した時のことを詳細に書きやすくなった
過去の決定が議事録じゃないところに残ってると探しやすいし安心感がある
選ばなかった選択肢に何があってそれが何がだめだったのかが残っている
- 何度も同じ話が蒸し返されないようになる
- 選ばなかった理由を書けるフォーマットになっていることで、レビューに通るレベルのはっきりとした比較検討せざるを得なくなる