この記事は、ニフティグループ Advent Calendar 2023 1日目の記事です。

前段の話

私が所属するプロジェクトでは、Design Docsでソフトウェアの設計や、目的、背景などを記述しており、継続的に更新しています。

Design Docsには、細かな設計方針や、その意図は明確に記述されていますが、読みやすさの観点から結論や重要なポイントのみを載せるようにしています。なので、粒度の細かい情報が失われてしまうということが起こってしまいます。

これでは新規参入者になぜ他の選択肢を選ばなかったか、なぜこの選択肢を選んだのかについて伝授されません。

未来の運用者は数ある選択肢からの導入理由や、決定の過程や議論した内容がわからないまま機能の追加や改修を行わなければなりません。

これが積み重なっていくと日々の運用のコストが膨らんでいき、運用したくないシステムになってしまい、技術的負債となってしまいます。

そこで、私のプロジェクトでは決定の過程や議論の内容、導入理由をArchitecture Decision Record (ADR)に残していくことに決めました。

ADRとは何か

Architecture Decision Record（ADR）は、ソフトウェアやシステムの設計における意思決定を文書化するための手法の一つです。ADRは、プロジェクトのアーキテクチャに関する重要な意思決定やその背景、理由、代替手段などを記録するために使用されます。これにより、将来の開発者やメンバーがプロジェクトの進化や変更に理解を持ちやすくなります。

ADRには概ね以下のような情報が含まれています:

1. コンテキスト（Context）: 意思決定を行った背景や文脈に関する情報。プロジェクトの現状、問題点、要件などが含まれます。
2. 意思決定（Decision）: 実際に行われた意思決定に関する情報。採用されたアーキテクチャの選択、採用しなかった代替手段などが含まれます。
3. 結果（Consequences）: 意思決定の結果として期待される影響や将来の課題に関する情報。採用したアーキテクチャがどのようにプロジェクトに影響を与えるか、またその他の代替手段がどのような結果をもたらす可能性があるかなどが含まれます。
4. ステータス（Status）: ADRがどのような状態にあるかを示す情報。進行中、完了、廃止などが含まれます。

ADRは、ソフトウェアアーキテクチャにおける変更や進化が行われる際に、なぜ特定のアーキテクチャが採用されたかを理解しやすくするために使用されます。これは特に、プロジェクトが長期間にわたって拡大し、新しいメンバーが参加する場合に役立ちます。

ADRはAWSやGoogle Cloudでも紹介されています。

Using architectural decision records to streamline technical decision-making for a software development project

アーキテクチャ決定レコードの概要

ADRを使ってみる

いつ書くか

先述したようにADRはアーキテクチャの設計における意思決定を文書化するための手法です。
しかし、私が担当するプロジェクトではアーキテクチャ以外においても、設計上の判断に複数の選択肢が考えられ、後の運用者から見て推定が困難であるものに対してADRを書くようにしています。

こうすることで、担当プロジェクトのさまざまな意思決定や選択理由を一括管理することができ、新規参入者が容易に参照し、理解することができるようになります。

例:

• 言語・フレームワークや開発ツールなどの選定
• 使用するインフラの構成
• アプリケーション全体の設計やディレクトリ管理方針
• アプリケーションロジックにおける計算方法の選択

一方、自明であるものに対しては記述しません。 (自明であるかどうかに対してチーム内で意見が分かれる場合は書くべきである)

例:

• ECSに対してALBを導入する決定

また、一つの意思決定につき一つのADRを作成します。
なので、再利用をせずに、新たな変更があったときは新しいADRを作成する必要があります。

実際に使っているテンプレート

設計判断を蓄積し、検索・参照可能とすることが求められるため、軽量なフォーマットが適しています。また、テンプレートにはばらつきがあり確定したフォーマットがありません。

実際に使用しているテンプレートは以下のようになっています。
一般的なテンプレートからほぼ変えていないですが、Decisionを上に持ってきています。
これは、決定した内容がファーストビューに表示され、ぱっと見でわかるようにしているためです。

また、過去経験の蓄積という性質を重視したいことから、Consideration（比較検討や議論）とReferences（参考情報）を項目として追加しています。

運用について

一度作成されたADRを変更しない運用としています。

新規作成時

1. 設計判断が必要となったらADRをDraftとして作成し、チームメンバーに承認を求める
2. 議論・修正ののち、承認された場合
   • ステータスをAcceptedに移す
   • Design Docに関連の深い機能がある場合は、Design Docからリンク
3. 議論の結果、判断提案自体を非承認とする場合
   • ステータスをRejectedに移す

更新時

1. 新しくADRを作成し、Referencesに更新元ADRへのリンクを付ける
2. 承認された場合
   1. 新ADR
      1. ステータスをAcceptedに移す
      2. Design Docに関連の深い機能がある場合は、Design Docからリンク
   2. 旧ADR
      1. ステータスをSupersededに移す
      2. 置換先として新ADRをリンクさせる
      3. Design Docからリンクされていた場合はリンクを削除する
3. 非承認の場合は新規作成時同様、Rejectedとする

実際に運用してみてのいろいろ

さて、実際に運用してみてしばらく経っていますが、メリットと課題を並べてみます。
まず、実際にADRを運用してみて感じたメリットは以下のようになっています。

• 意思決定が文書化されているので、プロジェクトのアーキテクチャに関する重要な情報が透明になり、新規参入者がプロジェクトに参画しやすくなる
• 変更の経緯や背景を知ることで、特定のアーキテクチャの選択がなされた理由を理解しやすくなる
• ADRの項目に議論した内容を記録する項目を入れています。よって、意思決定の際には必ずコミュニケーションを挟むようになり、チーム内のコミュニケーションが活性化される
• 意思決定の際に検討した代替手段が文書化されるため、将来の変更や改善のためにこれらの選択肢を再評価することが簡単

運用する上で課題と感じている部分は以下のようになっています。

• とにかく書くのが面倒
• 意思決定した際に文書化しないといけないので開発スピードは落ちる （良いように言うと、慎重に決めてから開発できる）
• 現状だと意思決定が発生する場合は大小問わず全てADRを執筆するようになっているので、細かいライブラリのインストールなども全て執筆するようになっている
  • 「本当は便利なライブラリだけどADR書くの面倒だから入れなくていいかぁ」ってなる
  • 全部書いてるとそのうち内容が疎かになりそう

やはり長い文章を書くのは少し億劫ですよね。。。

ADRのメリットを最大限に引き出すためには、文書作成の手続きを極力効率化し、プロジェクトの規模や状況に合わせて柔軟に適用することが重要だと感じました。

これによって、慎重かつ迅速な意思決定と、プロジェクト全体の透明性を両立させることが可能になると思います。
もっとシンプルにかつ現状のクオリティを損なわない方法を検討中です！

まとめ

ADRを作成することで、設計の背景や流れを記録することにより技術的負債なく未来へプロジェクトを託すことができます。

また、ADRプロジェクトの長期的な成功に貢献する有用なツールであり、慎重に導入し、適切に活用することで、ソフトウェア開発プロセスをより効果的かつ効率的に進める手助けとなります。

みなさんもADRを導入してみてはいかがでしょうか！

明日は、fu9shima さんが何か書かれるそうです。 お楽しみに！