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

Wantedly では、フレームワークやアーキテクチャの選定について、ADR を用いてドキュメンテーションしています。この章では、ADRの概要とその重要性、そしてADRを記述する際のガイドラインを説明します。

ADR とは

ADR(Architecture Decision Record) とは、アーキテクチャに関する重要な意思決定を記録するための文書です。なぜその決定が行われたのかを説明し、将来同じ問題に直面した際にその背景を理解・議論することができるようになります。

アーキテクチャの意思決定には、システムが何を達成すべきかといった機能要件や、パフォーマンスやセキュリティ、つかいやすさといった非機能要件があります。 ADR では機能要件・非機能要件に対するどちらの解決策を記録することができます。

なぜ ADR を書くのか

ADR を書くメリットは主に以下の2点です。

新たに参加したメンバーが意思決定の背景を理解し、意思決定を行ったメンバーと同じ視点で議論することができます
意思決定の背景を記録することにより、将来振り返った際に意思決定が適切であったかを判断し、軌道修正することができます

Wantedly では、日々 GitHub 上で議論を行い、様々な意思決定を行っています。しかし Issue ではなく ADR というフォーマットで意思決定を記録することで、次のようなメリットを享受できます。

意思決定のプロセスが明確になる Issue では個人の意見とチームの意見が混ざってしまい、議論しが難しくなることがあります。一方 ADR では Pull Request を通してレビューが行われるため、意思決定のプロセスが明らかになります。
意思決定の検索性、到達しやすさが向上する Issue は設計以外の情報も蓄積しており、意思決定を探すのが難しくなることがあります。ADR は意思決定だけが時系列に並べているため、過去の履歴を辿りやすくなっています。
状況把握が容易になる Issue は意思決定が当時の状況に基づいているため、現在の状況との差異がわかりにくいです。ADR は継続してメンテナンスされるため、現在の状況が反映された状態で保持されます。

ADR になにを書くのか

ADR は上記の目的を達成するため、適切な情報を記録しておく必要があります。一方で、継続的にメンテナンスされなければ意味がなく、書くためのコストや更新するためのコストが大きすぎると運用されなくなってしまう可能性があるため、ADR に書くべき情報は最小限に抑えるべきです。 Wantedly では主に以下のフォーマットをもとに ADR を書くことを推奨しています。

# <title>

## Status
<!-- 現在のステータス。検証中、広く使ってよい、廃止、非推奨など。 -->
<!-- もちろんさまざな状況があるので、上記のように一言で表さず背景も組み合わせて書いてもよいです。 -->

## Context
<!-- このライブラリを導入する背景や、このアーキテクチャを選定するに至った背景 -->
<!-- 解決したい課題を記入する -->

## Decision
<!-- どういう決定をするか -->

## Consequences
<!-- この決断をしたことによって生じた結果。 -->
<!-- e.g. ○○がよくなった、生産性があがった、XX が難しくなった、別の課題が生まれた。 -->

ADR をどこに書くのか

ADR には組織レベルとリポジトリレベルの 2 つのレベルがあります。組織レベルの ADR は、Wantedly の全てのプロジェクトで共通の決定に関する ADR を記録します。具体的には基盤となるようなフレームワークやアーキテクチャの選定に関する ADR です。これらは、Wantedly の全てのプロジェクトで共通の決定であるため、wantedly/dev の docs 以下に領域ごとに配置します。(例: wantedly/dev の ./docs/frontend/adr)

リポジトリレベルの ADR は、各プロジェクトで行われた意思決定を記録します。プロジェクト内に閉じるライブラリの選定やディレクトリ構成、設計方針やコーディング規約などが該当します。これらは、プロジェクトごとに異なるため、各プロジェクトのリポジトリに配置します。(例: 各リポジトリの ./docs/adr)

それぞれの ADR にはディレクトリ内で一意な連番を付与して管理します。連番は作成された順序に関わるだけで、他に特別な意味はありません。具体的には次のようなフォーマットです。 ./adr/ADR001-datetime-library.md

ADR をいつ、どのように書くのか

次のようなタイミングで ADR を書くことを推奨しています。

新規プロジェクトの始まり
新規ライブラリやフレームワークの導入時
既存のライブラリやフレームワークの廃止時
システムの設計やアーキテクチャに関する議論を行ったとき

ADR は存在することに自体に価値があります。最初はテンプレをコピーし、埋められる情報を埋めることから初めて構いません。 Pull Request を作成したらプロジェクトのメンバーや Chapter のメンバーにレビューを依頼し、必要に応じて加筆していきます。

ref

話を聞きに行きたい

Slack: #engineering

もっと知りたい

社内の ADR については以下のリポジトリを参照してください。

前へ上長承認が必要な作業次へ作業ログを残す意味

最終更新 5 か月前