Zenn
🤔

ADR（Architecture Decision Record）、始めました。

2024/08/26に公開
デザイン
architecture
tech

ADRを採用した設計フェーズの改善事例：効果的な意思決定の記録と共有について

こんにちは。
今回は、私のチームが設計フェーズで直面していた課題を解決するために、ADR（Architecture Decision Record）を採用した経緯と、その効果（期待値）についてご紹介したいと思います。

設計フェーズでの課題

私が担当しているチームでは、クラウドベースの営業支援ツール／顧客管理システムを開発しています。このサービスは、ノーコードで組み立て可能であり、顧客分析機能や多様なカスタマイズが可能なダッシュボードなどの特徴を持っています。
チームは現在50人弱のエンジニアで構成されており、アジャイル開発手法とGitHubを中心としたツールを使用しています。常にユーザーのニーズに応えるため、新機能の追加や既存機能の改善を継続的に行っています。

しかし、設計フェーズで以下のような課題に直面していました：

  1. 属人化: それぞれ機能ごとに設計担当者が分かれており、その人がいないと設計の意図や背景が分からない状況でした。
  2. 不十分な議論: チーム内で設計に関する議論が十分に行われず、多様な意見やフィードバックが反映されにくい状況でした。
  3. ドキュメント不足: 設計の内容や理由が適切にドキュメント化されず、後から参照することが困難でした。

これらの課題は、設計の品質や一貫性を低下させるだけでなく、チーム内のコミュニケーションやコラボレーションにも悪影響を及ぼしていました。私たちは、これらの課題を解決するための効果的な方法を模索していました。

ADR（Architecture Decision Record）との出会い

そんな中、私たちはADR（Architecture Decision Record）という手法に出会いました。ADRとは、ソフトウェアやシステムのアーキテクチャにおける重要な意思決定とその背景、理由、結果などを文書化するための手法です。

ADRを採用することで、以下のようなメリットが得られます：

  • アーキテクチャの理解や共有が容易になる
  • 過去の決定の履歴や根拠を参照できる
  • アーキテクチャの品質や一貫性が向上する
  • アーキテクチャに関する議論や合意形成が促進される

ADRの一般的な構成要素は以下の通りです：

  1. タイトル: 決定の内容を簡潔に表す
  2. コンテキスト: 決定を行うに至った背景や状況、関係する要素や制約などを説明する
  3. 決定: 決定したアーキテクチャの方針や手法、技術などを記述する
  4. ステータス: 決定の現在の状態を示す（提案、承認、非推奨、置き換えなど）
  5. 結果: 決定を適用した後のアーキテクチャの状態や影響、得られた効果や問題点などを記録する

ADRは、プロジェクトのソースコードと一緒に管理することが推奨されます。これにより、コードと同期したレコードを提供できるからです。また、ADRは小さくシンプルに保つことで、読みやすく、更新しやすく、作成しやすくなります。

ADRの採用プロセス

ADRを採用することを決めた後、以下のような流れで導入しました：

  1. ADRの概要やメリットをチームに共有し、理解を得ました。
  2. フォーマットを作成し、まずは各リーダーに周知しました。
  3. ADRの作成におけるレビュールールやタイミングを決め、チーム全体に周知しました。
  4. それらを実践し、フィードバックを受け取りました。
  5. 記載内容やプロセスを定期的に振り返り、改善していきます。

また、ADRのフォーマットとして、MADR（Markdown Architecture Decision Records）を採用しました。MADRは、Markdownで書くことができるシンプルなフォーマットで、先述のセクションに加えて、以下のセクションも含みます：

  • 考慮した選択肢: 決定の対象となった選択肢を列挙する
  • 決定の基準: 選択肢を評価するための基準を定義する
  • 選択肢の比較: 各選択肢の長所と短所を基準に沿って比較する

MADRは、Confluensで共有し、テンプレートや例などを参照することができます。これにより、ADRの統一性や整合性を保つことができました。

ADRの運用ルール

ADRの作成、レビュールールやタイミングとして、以下のように決定しました：

  1. ADRの作成は、設計の責任者が行う
  2. レビューは、開発チームの有識者やスペシャリストも実施する
  3. 作成やレビューは、設計の前や議論の途中に行う （後出しNG）
  4. 内容やステータスは、変更があれば随時更新する

レビューの場を開発チーム全体とすることで、ADRの内容や理由について、チーム全体で活発な議論やフィードバックを行うことができました。また、リーダー層の承認をもってADRの承認とすることで、合意形成のプロセスを明確化しました。

ADR導入の効果

ADRを導入したことで、徐々にではありますが、以下のような効果が得られ始めました：

  1. 設計の透明性向上: 設計の意図や背景が明確に文書化され、チーム全体で共有できるようになってきました。

  2. 知識の分散: 特定の個人に依存せず、チーム全体で設計に関する知識を共有できるようになってきました。

  3. 議論の活性化: ADRのレビュープロセスを通じて、設計に関する建設的な議論が増加しました。

  4. 意思決定の質の向上: 複数の選択肢を比較検討し、決定基準を明確にすることで、より良い設計決定ができるようになりました。

  5. 新メンバーのオンボーディング改善: 新しいチームメンバーが過去の設計決定を理解しやすくなり、プロジェクトへの参加がスムーズになりました。

  6. 設計の一貫性向上: 過去の決定を参照しやすくなったことで、設計の一貫性が向上してきました。

今後の展望

ADRの導入により、設計フェーズでの課題の多くが解決されましたが、まだ改善の余地があると考えています。今後は以下のような取り組みを行っていく予定です：

  1. ADRテンプレートの最適化: プロジェクトの特性に合わせて、ADRのテンプレートをさらに最適化していきます。

  2. ADRの可視化: ADRのレビュー依頼やバージョン管理を視覚的に表現するツールの導入を検討していきます。

  3. 他チームへの展開: ADRの有効性が確認できたため、他の開発チームにも導入を推奨していく予定です。

まとめ

ADRの導入は、私たちの設計プロセスに大きな改善をもたらしました。設計の透明性が向上し、チーム全体での知識共有が促進されました。また、意思決定の質が向上し、設計の一貫性も改善されました。

ADRは単なるドキュメンテーションツールではなく、チームのコラボレーションと知識管理を強化する強力な手法です。皆さんのプロジェクトでも、ADRの導入を検討してみてはいかがでしょうか。
（とはいえ、ADRの導入は一朝一夕にはいきませんし、チーム全体の理解と協力が不可欠となります。皆さんのプロジェクトでも、ADRが有効に機能することを願っています。）

追記： ADR運用ルール

私たちの開発チームで、実際に運用しているルールになります。みなさんの参考になれば幸いです。

概要

「ADR（Architecture Decision Records）」は、ソフトウェアプロジェクトにおける重要なアーキテクチャ上の決定を記録するためのドキュメントです。ADRは、なぜ特定の技術的な決定が行われたのか、その背景や理由を文書化するもので、プロジェクトチーム内での意思決定の透明性を高めるために行います。

運用目的

  • アーキテクチャ上の意思決定を明確にすることで、チーム内での認識のズレを減らす
  • 技術採用基準が曖昧になって属人化してしまう事を防ぐ
  • 新しいメンバーが、過去のアーキテクチャ決定や技術導入の意思決定を理解しやすくする
  • 過去に決定した決定や判断を貴重な・再利用可能な資産として今後の判断に役立てる

参考資料

必須ではないが目を通しておくと良い記事

運用について

  • ADRはメンバー全員が作成できる
  • 管理はメンバー全員で行う
  • ADRは定期的にレビューされ、必要に応じて更新される
  • すべてのADRは、指定されたフォーマットに従って文書化する
  • ADRは開発に関与するチームメンバー全員がアクセス可能な場所に保存する
  • ADRに対するレビューは積極的に募集して良く、その際に他メンバーはレビューを行う必要がある
  • ADRのスコープは以下（更新OK）
    • アーキテクチャレベルの決定
    • 非機能要件
      • セキュリティ: データ保護、認証、承認、脆弱性対策などセキュリティに関わる決定。
      • 高可用性: システムが連続して稼働し、ダウンタイムを最小限に抑えるためのアプローチ。
      • 耐障害性: システムが障害に対してどのように回復するか、または耐えるかに関する戦略。
    • 新しいツールの導入
    • 影響範囲が広いライブラリやフレームワークの導入
      • 複数個の中から選定を行った場合
    • 外部公開API
      • 外部とのインターフェース（API）の設計、プロトコルの選定、データ形式、公開された契約や仕様など
    • チームの過半数以上がADRを策定すべきと判断した場合

ADR作成から完了までの流れ

  • テンプレートは下記（ADR フォーマットテンプレート）を利用する
    • 必要に応じてテンプレートの更新をしてもいい
  • ADRを作成
    • レビューできる状態になったら、ステータスをProposedにする
  • ADRのレビュー
    • ADRの作成者はレビューミーティングを開催するか、定例ミーティングでレビューをしてもらう
    • レビュワーにチームメンバーやその他関係者などを招待する
    • 目安10～15分程度(目標30分以内)でミーティングを開催する
    • 各チームメンバーは事前にADRを読み、コメントや質問をしてチーム内で議論する
  • レビューでアクションポイントの識別と解決
    • ADRを改善するアクションポイントが見つかった場合は、チームで協力してアクションポイントの解決を図る
    • e.g. 技術的な詳細の不足、リスク懸念が発見されたなど
    • 時間内に終わりきらないような場合（時間をかけて調べ直さなきゃ行けないなど）、アクションポイントを解決したのち再度別枠で「2.ADRのレビュー」を行う
  • ADRの最終承認
    • チームがADRを承認した場合、ステータスをApprovedにする
    • チームがADRを却下した場合、却下の理由を追記して、ステータスをRejectedにする

ADRの更新プロセス

承認または却下されたADRは不変のドキュメントとして扱う。既存のADRを変更する場合は、新しいADRを作成して、レビュープロセスを経て承認する必要がある。

ただし、下記の場合はドキュメントを更新してもよいとする。

  • 誤記などの体裁上の修正を行う
  • コメントを利用して追記事項を行う

新しいADRが採用された場合、ADRの作成者は古い方のADRのステータスをSupersededにする。（ただ廃止された場合はDeprecatedにする）

既存のADRに関連するものを作成する場合は、子階層に作成する。（運用のしやすさによって変更する）

技術検討時の Pros / Cons

レビュー結果一覧

フォーマット

タイトル (ページタイトルに該当)

  • ADR文書の識別のための簡潔なタイトル。
  • プレフィックスにAPP-ID,COMMONなど影響スコープを表すワードとナンバリングを組み合わせる。
    e.g. COMMON-CALC-001: GraphQL APIの導入

ラベル

  • ADRが対象とする領域をラベルとして付与する
    • 右上の三点リーダーを押下して「ラベルを追加」から追加を行う
      e.g. エラー監視、ロギング、アーキテクチャ、セキュリティ etc…

ステータス

  • 現在のADRの状態
  • どれか一つだけチェックする（ラジオボタンと同様の扱い）
    -- Draft （未完成,作業中）
    -- Proposed （提案中）
    -- Approved（承認）
    -- Rejected（却下）
    -- Deprecated（廃止）
    -- Superseded（置き換えられた）

チームやメンバー

  • 議論、レビューに参加したチームやメンバーを記述
  • メンバーの記載は必須とする
    e.g.
    • チーム: チーム1, PM
    • メンバー: AAA, BBB, CCC, DDD

コンテキスト

  • この決定が必要とされた背景、問題点、または機会。
  • チームが直面している具体的な課題や必要性を説明します。
    e.g. UI-MIGRATIONプロジェクトでは、フロントエンドとバックエンド間でのデータ交換が複雑化しています。現在のREST APIでは、オーバーフェッチングとアンダーフェッチングの問題があり、フロントエンドのパフォーマンスに影響を与えています。

意思決定内容

  • 採用されたアーキテクチャの決定や技術的な選択。
    e.g. GraphQL APIを導入し、データ取得の柔軟性を向上させる

検討された選択肢

  • 検討された他の選択肢やアプローチ。
  • それぞれの選択肢に対する簡潔な評価。
    e.g.
    • REST APIの最適化: 既存のシステムを改善するが、根本的な問題は解決しない。
    • GraphQL APIの導入: クライアントが必要なデータを正確に指定できるため、オーバーフェッチングとアンダーフェッチングを解決する。

決定の理由

  • 選択されたアプローチを採用する理由。
  • 技術的、ビジネス的、または組織的な利点を含める。
    e.g. GraphQLはクライアントが必要なデータを正確に指定できるため、データ交換の効率が大幅に向上します。これにより、APIの応答時間を短縮し、フロントエンドのパフォーマンスを向上させることが期待できます。

予期される結果

  • この決定がプロジェクト、チーム、またはシステムに与える影響。
    e.g. フロントエンドのデータ取得の柔軟性が向上し、ユーザー体験の改善が期待される
     
    以下は任意で記述。特筆事項があれば必ず記載する

参照

  • 関連リンク
    e.g. GraphQL公式ドキュメント

コンセンサス

  • 決定に至るまでのチーム内の合意形成プロセス。
  • 重要な議論や意見の相違を含める。
    e.g. 開発チームはGraphQLの利点について議論し、REST APIに比べてデータ取得の柔軟性が大幅に向上することに同意しました。ただし、学習曲線の懸念があることも認識されています。

後続のアクション

  • 決定に基づいて取るべき具体的なアクションやステップ。
    e.g. GraphQLの試験導入を行い、フロントエンドとバックエンドの統合テストを実施する

Discussion