はじめに
こんにちは、フォースタートアップス株式会社エンジニアの野尻(@jsotakebmx)です。2025年1月に入社し、主にタレントエージェンシー支援システム(以下「支援システム」と呼ぶ)のシステム開発を担当しています。 入社から間もない(いっても約3ヶ月経ちますが)私は、支援システムのドメイン知識やアーキテクチャを把握するために日々あくせくしています。
この記事では、ADR(Architecture Decision Record)というアーキテクチャに関する意思決定の記録を始めた経緯などについて語ります。
目次
ADRとは
冒頭でも軽く説明しましたが、ADRは「Architecture Decision Record」の略語で「特定のアーキテクチャの選択を行う理由をテキストで説明・記録」していくフレームワークです。
「なぜこの選択をしたのか?」という背景を含めてテキストに残すことで、未来のチームメンバーが「あれ?この技術選定、なんなんだっけ?」と疑問を抱かないようにすることができます。
出典は以下の記事をご覧ください。
取り組むにあたって参考にした記事も添付しておきます。
きっかけ
私の所属チームでは、各週火曜日にレトロスペクティブを実施しており象・死んだ魚・嘔吐やポジティブふりかえりマッピングなどのさまざまな手法を使って振り返りを実施しています。
最近開催された「ポジティブふりかえりマッピング」にて、PdMから「ナレッジをちゃんと残したいよね」という意見が出ました。確かに、なぜこの技術やアーキテクチャが選ばれたのか、時間が経つにつれて曖昧になってしまうことって多いですよね。私自身も「昔のことだしなぁ……」と後から頭を悩ませることが多々あります。
そんな中、ファシリテーターから「ADR(Architecture Decision Record)っていう方法があるらしい」という話が飛び出しました。 ちょうど2025年4月から支援システムで大きなリアーキテクチャを予定していたため、ADRを導入する絶好の機会!ということでチーム全員が合意しました。
⬇️当時の様子 👀
※ 弊社レトロスクティブについての取り組みについてもっと知りたい方は、スプリントレトロスペクティブ本来の目的とは?初めてファシリをやって体感した「難しさ」と「学び」をご覧ください 🙏
CTOへの質問会で深まった理解
「きっかけ」にも記載しましたが、支援システムでは4月から大幅なリアーキテクチャを実施します。ざっくり説明すると約一年丸々使って「AWS→Salesforce、Rails+Nuxt.js→Next.js(tRPC)、デザインシステムの刷新」を完遂させます。
ただ、一部の技術選定をCTOがメインで行ってくれていたため、チームメンバーのほとんどがその技術選定の背景や理由をよく知らない状態でした。
モヤモヤした状態で開発を始めることはしたくなかったので、じゃあせっかくだし全部聞いちゃおうよ!ということでCTOに対して質問会の実施を打診。快諾してくださったので、すぐに「どんな質問をするか?」をチームで考えて質問集を作りました。
さらに、質問会当日はインタビュー内容を漏らさないように録音やNottaのような自動文字起こしツールを活用してみました。
ちなみに録音を後から聞き返したら、私自身はきはき喋ってたつもりが、意外とごにょごにょしていてちょっと悲しいけどいい気づきを得ました😅(このせいで文字起こしも変になってました 🤖)
CTOインタビューでは、既存システムの課題や新アーキテクチャ選定の基準だけでなく、ビジネス的な判断や支援システムの今後の展望についてまで話を聞くことができ、私自身はもちろんのことチーム全体の疑問を解消することができました。
いざ作成
その後、インタビュー結果をもとにADRを作成。テンプレートは、株式会社一休のテックブログを参考にさせていただきました。
# タイトル タイトルには、一目で論点がわかるタイトルを記載する。 "ADR_XXX:"から始める # ステータス draft, proposed, accepted, rejected, deprecated, superseded # コンテキスト このADRの決断や原動力となっている理由・背景・対応案などについて記載する。 # 決定 コンテキストを踏まえた決定を簡潔に記載する # 影響 この決定の結果生じる影響を記載します。 得られるメリット。コンテキストを取り入れなかった場合のデメリットなどでも可。 また、決定の結果、今後チームで意識しなければならないことなど。
参考:採用したフォーマット
管理方法
ADRの管理場所として、GitHub Issues、GitHub Discussions、Notionの3つが選択肢として上がったのですが、ADRは一人で実施するものではなく、チームのレビューや議論を経て完成形を目指していくという前提のもと、以下の観点でDiscussionsの方が適していると判断しました。
会話ログの整理が優秀
会話のソート機能が個人的には一番嬉しいポイントです。 「Oldest ,Newest ,Top」でソートすることができるため、ログが多くなっても共感を多く得ているコメントを探しやすいです。
Discussionsという名前の機能なだけあって、確かに議論に適しているなと感じます。
カテゴリ機能
カテゴリを活用することで、話題ごとに一覧で見ることができるのも嬉しいポイントです。
Issuesでもラベルを張ることで擬似的にカテゴリ分類をすることはできますが、ラベル機能はDiscussionsにもありますので、一覧性の高いDiscussionsに軍配が上がりました。
Issueが肥大化する
ADRの性質上、完成した後もcloseすることは基本ありません。従ってADRを書けば書くほどIssueの数が増え続けていくことになります。
所属チームではIssueは実装・バグ・調査タスクの管理を主な用途としているため、Issueの数字がどんだけ頑張っても0にならないのはなんとなく心理的に苦しいなぁと思ったのも大きな理由の一つに挙げられます。
誰がいつ書くのか
誰が?(WHO)
所属チームではADRの作成は特定の誰かに依存しないように「誰でも」というルールにしています。強いていうなら、アーキテクチャの提案や採用をした本人が書くのが好ましいかなぁといった具合です。
いつ書くの?(WHEN)
新規アーキテクチャ、ライブラリ導入、運用方法を提案したいときなど、いつでもOKとしました。また、「既存アーキテクチャだけど散らばった資料を元にまとめました」とかもいいのかなと思います。気軽に書いていければと思います。
ADRを始めて感じたこと
実際に書いてみると、チーム内の理解がぐっと深まるだけでなく、「そんな背景があったのね!」という発見もありました。何より、未来のメンバーが困らないようにナレッジを蓄積していくのはやっぱり大切だなぁ、としみじみ感じました。
ADRを文化として定着させるためにも、これからも気軽に書いて気軽に議論できる雰囲気を維持していきたいところです。
AIエージェントとの相性
少し趣旨は変わります。ADRとAIエージェント(を用いた駆動開発など)は相性がいいのではないかと考えています。 これについては、実務においてAIエージェントでゴリゴリ開発しているわけではないので予測の域を出ないですが、そう考える理由としてコンテキストの蓄積があります。
AIエージェントに対して実現したいことや仕様を伝えると、よしなにライブラリを選定し実装をゴリゴリ進めてくれますが、「なんでそのライブラリなん?」「確かにそのライブラリええけど既存のUIライブラリ使ってくれや...」って思うことはありませんか?私は結構あります。
この時に、エージェントに対してそのライブラリを選定した背景や根拠を羅列してもらい、ADRとしてナレッジを積んでおくことで「エージェントのためのコンテキスト」としても使えますし、「このライブラリなんで使ってるんだっけ?→AIがいいって言いました!→☺️」ってことが無くなるはずです。(願望)
実際どのくらい相性が良くて効果があるかはADRの運用を継続した先に見えてくると思うので、またの機会に執筆できたらなぁと思います。
最後に
ADRを始めたばかりですが、まずは継続して運用し「ADRやっといてよかった」だったり未来の開発メンバーから「ADRあって助かりました」が出てきたら最高だなぁと思います。
また、こういった文書作成は意識しないと面倒くさくなってやらなくなるオチもあるあるだと思うので、「いつでも・誰でも」と言いつつ最初のうちは誰か(私)がボールを持って推進するのがいいのかもしれません。
1年後私たちがADRを継続できているのか、またどんな風に活用しているのか、その結末をまたブログにできたらと思います!