Integrated Data Service 部の中野 (takamoto) です。2021~2022年頃は主に データプラットフォーム統合プロジェクトの紹介 - KADOKAWA Connected Engineering Blog で紹介されていたデータプラットフォーム開発の認証認可の開発に関わっていました。また、ここ2年弱は別チームに移り、データプラットフォーム上のデータパイプラインの開発・運用をメインで担当しています。
今回は、上記のデータプラットフォーム統合プロジェクトの開発チームに導入され、その後移った先のチームでも活用が進んでいる ADR の活用事例を紹介します。既に ADR 自体の紹介記事自体は数多く存在するため、この記事では ADR 自体についての説明は軽く流し、代わりに以下のような観点での事例紹介に重きを置くスタイルを取ります。
- どのようなモチベーションで ADR を導入したか？ 導入した結果、どのような効果が得られたか？
- 活用を続ける中で、 実践内容をどのような理由でどのように変化させていったか？
- ADR を導入した結果、設計ドキュメント全体にどのような影響を与えたか？
TL;DR
- 最初は検討用資料の延長として ADR を導入。
- 検討用資料の延長として採用するだけで得られるメリットと、 ADR らしく記述することで初めて得られるメリットが存在。
- ADR らしく記述することで、 ADR の不得意領域が見えてくる。
- ADR の不得意領域をカバーするフォーマットとして Design Docs を導入。
前提: ADR とは？
ADR (Architecture Decision Records) は、アーキテクチャ上の決定について主に以下の点を簡潔に記録しておくための手法の1つです。
- 検討時の背景: 意思決定を行う際の背景はなにか？ 例えばどのような問題が存在していた？
- 決定内容: どのようなトレードオフの元でそれを選択したのか、あるいは選ばなかったのか？
- 決定の状態: 決定は現在も有効か？ それとも後から廃止されたか？
ADR は2018年5月頃に Technology Rader で Adopt となったり、ここ5~6年で Design It! やソフトウェアアーキテクチャの基礎といった書籍でも取り上げられるようになってきており、国内での採用事例の紹介記事も2021年以降特に増えてきている印象です。
参考資料：
- アーキテクチャ決定レコードの概要 | Cloud アーキテクチャ センター | Google Cloud
- adr.github.io
- Using architectural decision records to streamline technical decision-making for a software development project - AWS Prescriptive Guidance
事例紹介
この節では、 ADR の導入から現在までを3つの期間に区切り、それぞれの期間ごとに実践内容とその結果について紹介します。
第1期: 検討用資料+αとして導入
背景
ADR 導入以前、データプラットフォーム統合プロジェクト内での何らかの決定を伴う検討は、検討対象の複雑さやサイズの大小に関わらず以下のような（定型化されていない）フローで行われていました。
- 以下のような内容が記述された、検討用資料を作成する。
- 検討のために実施された調査の結果
- 考えられる選択肢と、選択肢それぞれの Pros/Cons
- 資料を元に、口頭や GitHub Issue 上でディスカッションを行い、決定する。
ですが、この方法には以下のような問題がありました。
- あくまでディスカッション用の資料である為、口頭での議論内容や決定内容、決定理由が資料に追記されるかは資料作成者次第で、資料を見ても最終的に何が決定されたのか分からないことが多い。
- 作成された資料は、社内 Wiki (Confluence) 上にある開発チームの雑多な資料置き場に置かれていたため、現在も有効な決定に関わった資料を把握するのが時間経過に伴って困難になる。
実践内容
上記の問題を解消するために 2021年9月頃に以下の形で ADR が導入されました。
- ADR の作成フロー: これまでと同様に資料を作成し、資料を元にディスカッションを行った後、 ADR の手法に従って決定のステータスや決定内容を資料に記載する。
- ADR の管理方法: よくある Git リポジトリ管理ではなく、社内 Wiki (Confluence) 上で管理する。また、 ADR を分類ごとにディレクトリを分けて管理する形は取らず、フラットに管理する。理由は以下のとおり。
- 複数のコードベースに影響を与える決定がなされる可能性が高く、Git リポジトリ管理ではその際の ADR 置き場に困ると考えた。また、所属部署では内部向けドキュメントは基本 Confluence に集約していくハウスルールが存在した為、それに従うこととした。
- 最初から適切に ADR を分類するのは難しく、破綻する可能性が高いと考えた。また、 Confluence ではページを移動させても URL は変化しないため、後からディレクトリ分けをすることは十分可能と考えた。
- ADR のフォーマット: よくある ADR と同様に、
ContextやStatus、Decisionの項目を持つ他、以下のルールを設ける。- ADR ではタイトルは
ADR001_XXXのように先頭に連番を記載するフォーマットが一般的だが、元々の検討用資料では{日付}_{概要}という形式を採用していたので（導入負荷を極力下げるために）それを踏襲する。 - 元々の検討用資料によくあった形を踏襲して、テンプレートとして
Optionの項目を追加する。 - 決定理由を意識的に記載するために、テンプレートとして
Reasonの項目を追加する。
- ADR ではタイトルは
結果
以下に記載しているようにフォーマットの導入だけでも一定の効果はありましたが、検討用資料+αとして導入された為、 ADR で重要な「後からも読みやすくあるべし」といった観点が抜け落ちてしまいがちでもありました。
- うまく機能したと感じた点
- 導入のモチベーションとなった問題の一部解消: テンプレートによって書くべき内容を明確化したことで、結論やその理由が資料から把握できるようになった。また、専用の資料置き場が用意されたことで、決定の背景が記述された資料へのアクセス性が改善された。
- 定型化による恩恵: ADR という用語がチーム内での共通言語となったことにより、「これは ADR が必要だよね」といった会話が発生し、検討する際のフローが以前より明瞭になった。また、検討資料のフォーマットがテンプレート化されたことにより、資料の読みやすさが改善した。
- うまく機能しなかったと感じた点
- ADR の乱用: 検討時に便利なフレームワークとして ADR が利用された結果、決定背景を記述するという観点ではコード上のコメントで十分なケースや、（設計上の判断ではなく）運用保守で直近どういった対応をすべきかの検討でも ADR が記述されがちであった。これは設計に関する資料が徐々に埋もれていく問題の発生が容易に想像されるので、望ましくない状態であった。
- 1 ADR 1 決定の不徹底: 元々の検討用資料はあくまでディスカッション用の資料であった為、1ドキュメント毎に単一の決定を行う意識はなく、この状態を ADR でも引き摺っていた。これは、 ADR のステータスが決めづらくなる、決定内容が曖昧になる、記述が煩雑になるといった悪影響を及ぼした。
- ADR にノイズが多い: 以下のようなケースが発生し、後から資料を参照するといった観点ではノイズとなる記述が残ってしまっていた。
- 元々の検討用資料では Option ごとの詳細な調査結果も1つの資料に収められていることが多く、それがそのまま踏襲されるケースがあった。
- ADR 採用後に行う必要のある作業の TODO リストが
影響に記述されるケースがあった。
- タイトルから決定内容が分かりづらい:
〜についてのようなタイトルが付けられがちで、タイトルから決定内容が読み取りづらいケースが発生した。 - 一覧性の悪さ: 素朴に社内 Wiki 上で管理していたため、複数の ADR のステータスを把握するためには、それぞれの ADR のページを態々開く必要があった。
第2期: 検討用資料+αからの脱却
背景
2022年4月頃に筆者が現在所属しているチームに移った為、上記の実践と完全には陸続きではないのですが、移った先のチームでも元のチーム同様に「決定の文書化が必ずしもされない問題」や、「意思決定がチームではなく特定個人に閉じてしまう問題」などもあった為、こちらでも ADR を導入しました。
実践内容
第1期でうまく機能しなかったと感じた点を改善すべく、以下の形で導入しました。
- ADR 作成フロー: 以下の点について、第1期からルールを厳格化する。
- ADR の適用範囲を設計上の決定に絞る。
- 1 ADR 1 決定を徹底する。
- ADR 上の記述から背景や決定の経緯がわかるように徹底する（ADR 内に貼られた Slack 上のディスカッションへのリンク等を辿らなければ把握できない状態にはしない）。
- 「背景を読めば自動的に決定が導き出せる状態」になる程度に、背景を丁寧に書くことを意識する。
- ADR 管理方法: 第1期と同様に、社内 Wiki (Confluence) 上に、ディレクトリ分けをせずにフラットに管理する。またそれに加えて、 Confluence の ページ プロパティ マクロ と ページプロパティレポートマクロ を活用することで、各 ADR のステータス等の情報も記載された ADR 一覧ページを用意する。
- ADR のフォーマット: 基本的には第1期のものを流用するが、一部手を加える。
- タイトルには連番を振るように変更する。また、タイトルは決定内容の概要を記載するようにする（例: 「〜で〜を行う」「〜を採用する」）。
- Option ごとの詳細な調査結果は ADR 内には含めず、 ADR の子ページなどに切り出し、 ADR からは参考資料として参照する形を徹底する（参考資料を読まなくても決定の経緯が理解できる形で ADR を記述する）。
- ADR 採用後に行う必要のある作業の TODO は、タスクチケットなどへの外出しを徹底する。
結果
以下に記載しているように、第1期にうまく機能しなかったと感じた点については概ね改善され、本来の ADR の効果が得られていると感じました。一方で、 ADR ではカバーしづらい領域も見えてきました。
- うまく機能したと感じた点
- 検討全体の精度が向上した: 第1期より記述が明瞭になった結果、口頭でのディスカッションで内容を補完する必要が減り、背景に対する理解度の向上やそれに伴う検討全体の精度の向上を感じた。また、 1 ADR 1 決定の徹底は決定内容を明確にするだけでなく、自然と背景が整理されるメリットもあるように感じた。
- 資料の再利用がしやすくなった: 決定内容が明確になったことで、実装上のコメントなどから資料を引用しやすくなった。また、一覧性が向上したことで決定の経緯を把握する必要が出た際に、対応する現在も有効な ADR が探しやすくなった。
- うまく機能しなかったと感じた点
- ADR だけで合意形成を行うのは面倒: ADR だけで合意形成を行うことも出来るが、記述の明瞭さを求められるために記述する負荷やそれに伴う開発スピードの低下を感じる場合があった（ADR としてどのようにまとめればよいかイメージ出来ない状態でスタートするものは特に）。
- 単一の決定に切り出しづらいケースがある: 経験値が低い領域等のアーキテクチャ設計では「基本的なアイデアを元に実装イメージを作成⇒実装イメージをアイデアにフィードバック」の流れを反復しながら徐々に解像度を上げていくことになるが、その初期段階での決定は曖昧であったり複数の決定が相互に依存し合っている事が多く、 決定1つ1つを別々の ADR に切り出すのは困難だった。
第3期（現在）: ADR が不得意な用途向けのフォーマットとして Design Docs を導入
背景
第2期の結果から、 ADR は「曖昧な状態から決定まで持っていくために、まずその方向性について合意形成する」用途や、その際のアイデアを後から参照する用途にはあまり向いていないと感じました。アーキテクチャの規模が小さい場合は、ラフに Slack 上や口頭などで事前にざっくり合意形成を行った上で ADR を作成する形でも対応可能ですが、規模が大きい場合は概して問題の複雑度も高く、同様の方法での対応は難しい場合があります。
実践内容
上記のようなケースに対応するために、以下の形で Design Docs を新たに導入しました。
- 資料のライフサイクル: 以下のように遷移する。
- 開発開始時点: チームメンバー間でアーキテクチャの方向性の認識を合わせるために作成される。
- 開発中: 開発中に判明した内容は、適宜資料にフィードバックされる。また、開発中に認識がブレそうになった際は、この資料に立ち戻る。
- 開発終了後: アーカイブされる。たとえ今後設計が変わってもこの資料は更新されない。
- 資料に記述する内容: 設計上の基本的なアイデア、重要な要素、注意すべき要素、抽象度の高いアーキテクチャ図など。
- 資料に記述しない内容: ADR や実装上のコメントとして記載可能なものなど。
- （詳細設計等の）実装寄りの記述の賞味期限は短いので、積極的に記述するのは避ける。
参考資料：
結果
導入してから日が浅いのでまだまだ評価中ですが、合意形成の用途としてはある程度機能していると感じています。また「後から参照する」という観点では ADR の方が優れていると感じるため、「ADR で書けるものについては極力 ADR に寄せて、 ADR で書きづらい領域のみ Design Docs として書く」という方針自体は悪くないように感じています。
まとめ
以上が簡単になりますが、ADR の導入事例とそれに関連した Design Docs の導入事例の紹介となります。
第3期では ADR の穴を埋めるために Design Docs を導入しましたが、「現在のアーキテクチャの全体像に関する資料」のような ADR や Design Docs ではカバーしづらい領域は依然として存在しています。また、アーキテクチャ以外の領域に関する検討ドキュメントについても、現時点では特別定型化されていない状態です。ですが、これは ADR や Design Docs を導入したことで「定型化が不足している領域が認識できるようになった」ということの裏返しかと思うので良い変化だと捉えています。
ADR は導入負荷のとても軽いフォーマットです。また、利用すべきタイミングがわかりやすいフォーマットでもあると思うので、本記事の事例のように素朴にドキュメントを記述している状態から改善していく際の、最初の第一歩としても有用だと感じています。
本記事が ADR を導入する際の参考になれば幸いです。
