こんにちは、@enzerubankです。
この記事はEngineering Manager Advent Calendar 2023の18日目の記事です。
最近はADRs（Architecture Decision Records）を書いてみたという資料をチラホラ見かけるので、うちのチームでも導入してみたいなと思い、調べたことをまとめてみました。
ADRsとアジャイル開発
ADRsは特に2011年のMichael Nygard氏による紹介から普及しました。
このブログ内ではアジャイル開発における必要最小限のドキュメントの必要性について述べられています。
アジャイル開発で最も重要なドキュメントはソースコードです。ただソースコードだけでは「なぜこの設計にしたのか」「なぜ他の設計にしなかったのか」といったような設計判断の根拠はわかりません。
そのため日々の意思決定の積み重ねのログを残しておくと、最終形であるソースコードと合わせてみることで、理解を深めることができるようになります。
ドキュメントの運用については以下のカケハシさんの記事がわかりやすいです。本記事のADRsは日時属性を持つストック情報であり、その当時のコンテキストを後世に伝えるために役立ちます。
ADRsのフォーマット
ADRsのフォーマットはMichael Nygard氏のブログで以下のように紹介されています。
## Title （タイトル）
## Context （コンテキスト）
## Decision （決定事項）
## Status （ステータス）
## Consequences （決定による影響）
本記事では実際に書く際の例を記載しました。
Title （タイトル）
ADRsの内容を一文で記述します。
例: ADR 001: モジュラーモノリスアーキテクチャへの移行
Context （コンテキスト）
その決定がなされた背景や状況を説明します。
例:
現在20〜30名のエンジニアチームで一つの大規模なモノリシックアプリケーションの開発を行っているが、ビジネスの成長に伴い、複雑さとメンテナンスの難しさが増してきた。特に次のような問題が顕著。
- コードベースの複雑性:
- アプリケーションのコードベースが巨大化し、新しい開発者が理解しにくくなっている。これは、新機能の追加や既存機能の更新に時間がかかる原因となる。
- スケーラビリティの問題:
- モノリシックな構造では、システムの特定の部分に対する負荷が増えると、全体のパフォーマンスが低下する可能性がある。
- 継続的なデプロイメントの困難:
- 小さな変更であっても、全アプリケーションを再デプロイする必要があり、リスクとコストが高くなってきている
Decision （決定事項）
アーキテクチャに関する決定事項を記述します。
例: 以下の理由からモジュラーモノリスアーキテクチャへの移行を決定
- モジュール化された構造:
- アプリケーションを複数の独立したモジュールに分割し、それぞれが特定のビジネス機能やサービスを担当。これにより、システム全体の複雑さを減らし、開発者が特定の部分に焦点を当てやすくなる。
- 独立した開発とデプロイメント:
- 各モジュールは独立して開発・デプロイできるように設計されるため、小さな変更や新機能を迅速にデプロイできるようになり、全体のデプロイメントリスクが減少する。
- マイクロサービスへの段階的な移行
- 将来的にマイクロサービスに移行する際にモジュール化されることで、移行がしやすくなる。
Status （ステータス）
ADRsの意思決定がどの状態かを記述する。以下の3種類から選択します。
例: 以下の3つから選択する
- Proposed （提案中）
- 提案中の状態
- Accepted （受理）
- 同意することを意思決定した状態
- Rejected （拒否）
- 同意しないことを意思決定した状態
Statusの例はこちらを参考にしましたが、シンプルに3つに絞りました。
Consequences （決定による影響予測）
決定を適用した後の影響について予測を記載します。
メリットだけではなくデメリットも考慮して慎重に評価します。
例:
- メリット
- 開発の効率化
- スケーラビリティの向上
- 柔軟性の向上
- デメリット
- 初期の投資と労力がかかる
- 継続的なメンテナンスが必要
ADRsの導入事例
導入するに至って他社の事例をいくつか調べてみました。
ADRsを書くときのコツについては一休さんのブログが良かったです。
さいごに
事例をいくつか調べてみて以下の気づきが得られました。
- 「軽量でとにかく書いてみよう」のポリシーは大切（一休さんのブログを参考にする）
- 対象者のスコープは開発者とする
- アーキテクチャの議論だけではなく開発プロセスもADRsでログを残す
- Design Docsは全体として今どうなっているかを示すもの、ADRsは当時のコンテキストを示す
ADRsについてもまずはとにかくやってみると良さそうです。
やってみて随時改善していきましょう。
PharmaXエンジニアチームのテックブログです。エンジニアメンバーが、PharmaXの事業を通じて得た技術的な知見や、チームマネジメントについての知見を共有します。 PharmaXエンジニアチームやメンバーの雰囲気が分かるような記事は、note（note.com/pharmax）もご覧ください。
Discussion