arch-adr

1行の要約

1つのアーキテクチャ上の決定を記録する、簡潔で構造化されたドキュメントです。何を決定したか、なぜか、どの代替案を退けたか、そしてどのような結果が生じるかを記録します。決定した時点で作成し、リポジトリに永久に残します。

このスキルを使う場面

• 将来のメンテナーが理由を知らなければ、後から疑問を持つようなアーキテクチャ上の選択全般。例：データベースの選定、メッセージングシステムの選定、ヘキサゴナルアーキテクチャとレイヤードアーキテクチャの選択、モノリスではなくマイクロサービスを選ぶこと。
• 代替案を実際に検討したうえで退けた決定。その理由を記録することに最も価値があります。
• オンボーディング：新しく参加したメンバーはADR一式を読むことで、アーキテクチャがどのように現在の状態になったかを理解できます。

このスキルを使わない場面

• 戦術的なコードレベルの決定（data class と class のどちらを使うか、ファイルの整理方法など）。細かすぎるため、書くコストがメリットを上回ります。
• 現実的な代替案がない決定（Pythonしか使わないチームでJavaとPythonのどちらを使うかは、決定とは言えません）。
• 事後に「2年前に行った決定についてADRを書こう。理由は覚えていないけれど」という場合。価値はタイムスタンプにあります。後から日付を遡って記録しても、価値は低くなります。

主な内容

標準的なADRの構成（Michael Nygardのオリジナルテンプレート）：

• タイトル。 短い名詞句にします。「プライマリストアとしてPostgreSQLを使う」や「注文サービスにヘキサゴナルアーキテクチャを採用する」などです。
• ステータス。 proposed / accepted / deprecated / superseded by ADR-NNN。
• コンテキスト。 状況、作用する力、制約は何か。なぜ今この決定が必要なのか。
• 決定。 何を決定したか。「検討中です」のような議論ではなく、「〜します」のように肯定的な主張として記述します。
• 結果。 この決定から何が生じるか。良い面と悪い面、受け入れることになる制約、新たに生じる問題を記述します。
• (任意) 検討した代替案。 ほかにどのような案があったか。それぞれを退けた理由。

ファイル構成。

docs/adr/
├── 0001-use-postgresql.md
├── 0002-adopt-hexagonal-architecture.md
├── 0003-event-bus-via-rabbitmq.md
├── 0004-replace-rabbitmq-with-kafka.md  (supersedes 0003)
└── README.md      ← index of ADRs

番号は順番に付け、再利用しません。ADRを置き換える場合、新しいADRから古いADRを参照し、古いADRのステータスをsuperseded by ADR-NNNにします。古いADRもツリーに残します。履歴を残すことが目的です。

長さ。 1ページに収めます。ADRが2ページになる場合、おそらく2つの決定を扱っているため、分割するべきです。

ツール。 adr-tools（シェル）、adr-manager、MADRテンプレート、Log4brainsは、いずれもADRの生成やインデックス作成を行います。大規模なチームでは便利ですが、小規模なチームならMarkdownを手書きすれば十分です。

生きたドキュメントと決定ログ。 ADRは決定ログであり、受け入れた後は変更しません。「生きたドキュメント」は別のものです（READMEやアーキテクチャ図など）。ADRの決定内容を更新せず、新しいADRで置き換えてください。

決定のヒューリスティクス

• 決定を実装する前にADRを書きます。明確に考えることを促します。
• 決定が自明に思えてもADRを書きます。「自明」とは、慎重に考えていないことを意味する場合がよくあります。
• 代替案は簡潔かつ具体的に記述します。「Kafkaを検討しましたが、現時点ではストリーミングのユースケースがないため採用しませんでした」などです。
• 番号は順番に付け、変更しません。番号を振り直さず、削除した番号も再利用しません。
• ADRはWikiではなくリポジトリに置きます。バージョン管理され、レビューを受け、コードとともに引き継がれます。

アンチパターン

• アーキテクチャWikiページ。 すぐに実態と乖離します。チームメンバーが入れ替わると維持されず、レビュー担当者も読みません。
• 誰も覚えていない決定について、事後に書かれたADR。 タイムスタンプは重要です。後から補っても価値は限られます。
• 代替案のセクションを隠したADR。 価値の大半はなぜXを退けたかにあります。それがなければ、ADRは単なる宣言にすぎません。
• 古いADRの決定内容を更新すること。 履歴が損なわれます。更新せず、新しいADRで置き換えてください。
• 戦術的な決定に対して何百件ものADRを書くこと。 ADRが扱うのはアーキテクチャ上の決定です。ファイル整理の選択すべてにADRが必要なわけではありません。一式を読みやすく保てるよう、基準を高く設定してください。

関連項目

• arch-fitness-functions — フィットネス関数は「何を」を強制し、ADR は「なぜ」を記録します。併用してください。
• その他すべての arch-* スキル — ほとんどのアーキテクチャ上の決定は ADR に記録する価値があります。

参考資料

• Michael Nygard「Documenting Architecture Decisions」（2011 年のエッセイ）— ADR の原点となる説明です。
• MADR テンプレート — 最新の Markdown ADR テンプレートです。
• adr-tools — Joel Parker Henderson のシェルツールです。
• Richards & Ford『Fundamentals of Software Architecture』第 19 章（アーキテクチャ上の決定）。