> For the complete documentation index, see [llms.txt](https://docs.wantedly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wantedly.dev/fields/dev-process/adr.md).

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

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

## ADR とは

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

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

## なぜ ADR を書くのか

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

* 新たに参加したメンバーが意思決定の背景を理解し、意思決定を行ったメンバーと同じ視点で議論することができます
* 意思決定の背景を記録することにより、将来振り返った際に意思決定が適切であったかを判断し、軌道修正することができます
* コーディングエージェントに「なぜこうなっているか」を伝えるコンテキストとして機能し、決定済みの設計を蒸し返したり、意図に反する実装をしたりすることを防げます

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

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

## ADR になにを書くのか

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

まず、意思決定のすべてを ADR にするのではなく、影響範囲に応じて書く場所を使い分けます。コーディングエージェントを使った開発では実装のたびに大量の意思決定が発生するため、この線引きがないと参照されないドキュメントが積み上がってしまいます。

| 意思決定の影響範囲         | 書く場所        |
| ----------------- | ----------- |
| 局所的な変更に閉じる        | コードコメント     |
| 特定の機能に閉じる         | その機能のドキュメント |
| システム全体・複数の機能に影響する | ADR         |

判定の目安は「他の機能を作るときにこの判断をまた参照・踏襲するか?」です。複数の機能やシステム全体から繰り返し参照されるなら ADR に書き、その機能でしか意味を持たないならその機能のドキュメントに留めます。また「ページング戦略」「認証方式」のような関心事単位で ADR を立て、「○○機能の API 設計」のような機能単位では立てないようにすると、採用・非推奨・置き換えの履歴を 1 箇所で追えるようになります。

ADR 本体は、ウォンテッドリーでは主に以下のフォーマットをもとに書くことを推奨しています。

```
# <title>

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

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

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

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

## ADR をどこに書くのか

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

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

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

連番はファイル名が異なるため Git ではマージ時に衝突を検知できず、並行する作業ブランチが同じ番号を採ってしまう事故が起きます。コーディングエージェントによって ADR の作成頻度が上がると起きやすくなるため、本文が空でも番号だけ確保する Pull Request を先に出すなど、番号を予約してから書き始める仕組みを用意しておくとよいです。予約の結果として欠番が出ても、詰めずにそのまま運用します。

コードやドキュメントから ADR を参照するときは、ファイル名と同じ「ADR001」の表記に統一します。表記が揺れると、人もコーディングエージェントも参照元から本体へ辿れなくなります。

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

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

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

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

コーディングエージェントに ADR を書かせる場合は、次の 2 点に注意します。

* 書くべきケースと不要なケースを、AGENTS.md や CLAUDE.md のようなエージェントが常に参照する指示ファイルに明示しておきます。前述の影響範囲の基準をそのまま書いておけば、エージェントが自律的に判断できます
* 推測で書かせないようにします。エージェントは人間が言っていない理由や却下した選択肢をもっともらしく補完しがちです。検討の実態と異なる ADR は読み手に誤った背景を伝えてしまうため、曖昧な箇所は人間に確認してから書くようルールに含めます

また、ADR は書くだけではエージェントに読まれず、かといって全 ADR を毎回コンテキストに載せることもできません。ADR 本体は意思決定の単一の情報源として 1 箇所に置いたまま、指示ファイルに ADR の置き場所と参照方法を書き、領域ごとのガイドには根拠となる ADR を「結論の要約 + リンク」の形で引用しておくと、エージェントは必要なときだけ原文を辿れるようになります。

## ref

* <https://adr.github.io/>
* [architecture-decision-record/locales/en/templates/decision-record-template-by-michael-nygard at main · joelparkerhenderson/architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/locales/en/templates/decision-record-template-by-michael-nygard)
* [アーキテクチャの「なぜ？」を記録する！ADRってなんぞや？ - Qiita](https://qiita.com/fuubit/items/dbb22435202acbe48849)
* [O'Reilly Japan - ソフトウェアアーキテクチャの基礎](https://www.oreilly.co.jp/books/9784873119823/)

#### 話を聞きに行きたい

* Slack: [#engineering](https://wantedly.slack.com/archives/C92AZFA2D)

#### もっと知りたい

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

* [infrastructure/adr · wantedly/infrastructure - (internal only)](https://github.com/wantedly/infrastructure/tree/master/adr)
* [dev/docs/frontend/adr · wantedly/dev - (internal only)](https://github.com/wantedly/dev/tree/master/docs/frontend/adr)
* [dev/docs/backend/adr · wantedly/dev - (internal only)](https://github.com/wantedly/dev/tree/master/docs/backend/adr)