📑

ADR (Architecture Decision Record) 始めました

に公開
アーキテクチャ
ドキュメント
ADR
idea

こんにちは。
ご機嫌いかがでしょうか。
"No human labor is no human error" が大好きな吉井 亮です。

私達のグループでは3つのプロジェクトと5つのクラウドサービスのインフラを Terraform で管理しています。
1つのリポジトリにプロジェクトごとのディレクトリを切って運用しています。

今はまだ小さなチームということで、それぞれの担当者がプロジェクトコードを全て理解しています。
しかし、チームが大きくなり人数が増えてきたり、異動や退職によるメンバー変更の際に、コードへの理解度が落ちシステムの保守性が低下するリスクが潜んでいます。

そこで、ADR (Architecture Decision Record) を100％作成する運用にチャンレンジしています。

ADR とは

ADRとは、アーキテクチャに関する重要な決定事項とその背景、結果を記録したドキュメントです。

Michael Nygard 氏が Documenting Architecture Decisions を公開し広まりました。
昔から同じ発想のドキュメントは存在していました。日本だと「設計書」「議事録」「チケット」のような名称で意思決定の記録はしていたと思います。
ただ、分量が大きいドキュメントは読まれない・更新されない運命にあり、有効性の証明が難しいものになりがちです。
小さくモジュール化されたドキュメントであれば読まれる・更新される可能性が高くなるはずです。そういった改善で産まれたので ADR だと理解しています。

アーキテクチャ決定時のアンチパターン

アーキテクチャ決定時のよく発生するアンチパターンがあります。私も経験と反省があります。

決定が行われない（優柔不断）：
間違った選択をすることを恐れ、何の決定も行われない。

根拠不明な決定（議論の繰り返し）：
正当性なく決定が行われ、なぜその決定が行われたのか理解されない。その結果、同じトピックが複数回議論されることになる。

決定の知識喪失：
決定がリポジトリに記録されないため、チームメンバーが決定が下されたことを忘れたり、知らなかったりする。
新しく参加したメンバーが、なぜその技術が選ばれたのか、歴史的背景を理解できずに苦労している。

重要なこと

ADR を作成する目的、価値は 「その決定に至った理由と背景を文書化すること」 にあります。
決定の事実だけを書いただけでは不十分です。理由と背景が欠けることでアンチパターンにあるような問題が発生します。

要件が変わってもメンバーが変わっても理由と背景が理解できれば、その決定の上に新しい判断を積み重ねていくことが可能になります。

ADR テンプレート

様々なテンプレートが公開されています。Michael Nygard 氏のテンプレートも存在します。
何れもシンプルで大きすぎないことを意識しているように感じます。
私達のグループでは Michael Nygard 氏のテンプレート をベースに運用を開始しています。
運用しながら他のテンプレートを参考にしつつ改善していく予定です。

# タイトル

## ステータス

提案済み、承認済み、却下済み、非推奨、置き換え済みなど、どんなステータスか？

## 背景

この決定または変更の動機となっている問題は何か？

## 決定

提案または実施する変更は何か？

## 影響

この変更によって、何が簡単になり、何が難しくなるか？

ADR Templates
architecture-decision-record

ADR をどこに置くか

プロジェクトチームによって異なると思います。
Notion、GWS、Confluence、GitHub Wiki、リポジトリ直下など様々な選択肢があります。

私達のグループでは、GitHub リポジトリに配置しています。理由は単純で AI Coding Agent が参照する場所に置いたほうが何かと可能性がありそうだからです。
リポジトリに置いておけばレビュープロセスも自然に確立できます。更新履歴も GitHub History で確認できます。

ADR のライフサイクルとプロセス

ADR プロセスは、以下のフェーズで構成されます。

  1. アーキテクチャ上の決定の特定: プロジェクトに影響を及ぼす重要なアーキテクチャ上の決定を特定する。
  2. ADR の作成: プロジェクト担当者が ADR を作成し、Pull Request を作成する。
  3. ADR のレビュー: プロジェクトメンバーでレビューする。チームは ADR を承認、拒否、または改善のためのアクションポイントを特定する。拒否された場合は、将来の議論を防ぐために拒否理由が追加される。
  4. ADR の承認: チームが ADR を承認すると、ADR はマージされる。
  5. 変更と置き換え: 既存の ADR を変更する必要がある場合は、新しい ADR のレビュープロセスを確立する

イミュータブルであることが推奨されていますが、私達のグループでは変更可能にしています。Pull Request や History で変更履歴と承認プロセスを確認できるためです。

まとめ

ADR を単なる文書とは考えていません。チームの記録を持続させ、意思決定のプロセスを改善し、より成熟したモダンなエンジニアリングを実現するための手段と考えています。
アーキテクチャの何を決めたかではなく、なぜ決めたかを記録することは関係者全員の共有財産になります。根気強く ADR を育てていき文化にまで昇華できればと考えています。

Discussion