起業なのか請負開発か趣味のプロジェクト（ペットプロジェクト）かによって状況は異なりますが「私のチームの開発者は私１人だけです」という個人開発においても、ADRは有効なツールとなりえます。
ADRとは何か？
ADR（アーキテクチャデシジョンレコード）は、ソフトウェアアーキテクチャにおける重要な設計判断とその根拠、影響、関係する検討事項などを記録した文書です。
一見、現代的な響きですが、その実態はシステム設計ドキュメントの一部です。
"ADR"で検索すると真っ先にヒットするアーキテクチャの入門書『Design It! ―プログラマーのためのアーキテクティング入門』では、ADRは「アーキテクチャ手法に対する開発者寄りのアプローチ」と説明されており、アーキテクトと開発者自身がアーキテクチャに関する意思決定を記録し、共有するための手法として位置づけられています。
アーキテクチャデシジョンレコード（Architecture Decision Records）
テキストベースの軽量なテンプレートを使用して、アーキテクチャ上の設計判断を記録する。軽量なアーキテクチャデシジョンレコード（Architecture Decision Records：ADR）は、実績のあるアーキテクチャ手法に対する開発者寄りのアプローチだ。設計判断を記録していくことで、それらを共有し分析することが容易になる。意思決定の履歴を残すことで、現在のアーキテクチャについてのコンテキストを、その過程と結びつけて提供できる。
16章 設計をタンジブルにするアクティビティ
ソースコードの側には意図をコメントを残せますし、コミット情報にはポエムを綴ることができますが、設計は抽象的なものなので専用の書く場所を作らないといけません。
記述する内容は、書籍『ソフトウェアアーキテクチャの基礎 ―エンジニアリングに基づく体系的アプローチ』によると、タイトル、ステータス、コンテキスト、決定、影響の項目で構成されます。
ADRの基本構造は、タイトル、ステータス、コンテキスト、決定、影響という5つの主要セクションから構成される。私たちは通常、基本構造の一部として、さらにコンプライアンスと備考という2つのセクションを追加する。この基本構造（図19-1）は、テンプレートの一貫性と簡潔さが保たれていれば、必要に応じて他のセクションを含む形に拡張が可能だ。たとえば、必要に応じて代替案セクションを追加して、可能なすべての代替ソリューションの分析を提供できる。
19章 アーキテクチャ決定
# タイトル * アーキテクチャ決定の簡単な説明 ## ステータス * 提案済み、承認済み、破棄 ## コンテキスト * この決定を行った状況。技術的な制約、ビジネス要件、既存システムとの関係性など ## 決定 * 決定事項とその根拠 ## 影響 * この決定によるシステム・品質・関係者への影響。デメリットやトレードオフについても記述する。 ## コンプライアンス * この決定が順守されていることを確認する方法(アーキテクチャ適応度関数) ## 備考 * この決定のメタデータ（著者など）
重要なのは「コンテキスト --> 決定 --> 影響」のフローです。コンテキストにおける状況を説明し、決定とその根拠を明示し、影響による予測を記録することで、設計判断の全体像を把握しやすくなります。
一例として、私の最近の経験ではモノリシックなウェブアプリケーションのUIレイヤーを切り出してSPAにするか否かをADRで提案しました。
# SPA化に関するアーキテクチャ決定 ## ステータス * 提案済み ## コンテキスト * 現状のウェブアプリケーションはPHPでレンダリングされ、サーバーサイドでテンプレートエンジンを使ってHTMLを生成している。 * 現状のアプリケーションは、モノリシックな構成であり、UIレイヤーとビジネスロジックが混在している。 * ユーザーがアプリケーションを利用する際に、ページ遷移が多く、UXが低い。 * 今期にUIの全面的なリニューアルを行う予定である。 * ユーザー規模の拡大を計画している * 開発人員の変化はない ## 決定 * SPA化を行い、ユーザーのUXを向上させることとする。 * SPA化により、ユーザーの操作に対して、リアクティブに画面を更新することが可能となる。 ## 影響 * SPA化により、JavaScriptのエコシステムを活用することが必要となる。 * SPA化により、フロントエンドの知識を持つエンジニアが必要となる。 * SPA化により、フロントエンドとバックエンドの通信が必要となる。 * SPA化により、フロントエンドのビルド環境が必要となる。 ## コンプライアンス * SPA化により、UXが向上することを確認するため、ユーザービリティテストを行う。 * SPA化により、開発効率が向上することを確認するため、開発効率を測定する。
ビジネスでの場ではこれに相当するドキュメントを納品物として定めるとか、自社ではチケットシステムやドキュメント共有ツールに議論のログをまとめてあるとか、それぞれの慣習が存在すると思いますが、個人の開発でそういった活動を行っている例は稀です。
しかし、個人開発においても、ADRを作成・活用することで、多くの利点が期待できます。
個人開発におけるADRの利点
客観的視点による設計判断の向上
個人開発では、客観的な視点が不足し、偏った設計判断をしてしまうリスクがあります。ADRに設計判断を文章化することで、客観的に自身の考えを見つめ直す機会が生まれ、より良い設計を選択できるようになります。
文章化を過度なプロセスと捉え、敬遠する必要はありません。いうなれば技術ブログを公開して第三者の意見を取り入れるのも同様の効果があります。
近年では、LLMなどの技術を活用することで、AI相手にレビューを依頼したり、文章化そのものにかかるコストを削減できるため、ADRとの相性が良いでしょう。
私の投稿した技術記事もこういった動機で書かれたものも少なくありません。
プロジェクトの未来は予測できない
個人開発であっても、プロジェクトが長期化するにつれて、将来の自分自身が過去の設計判断を振り返る必要が出てくる場面は多々あります。
また、開発当初は想定していなかったとしても、プロジェクトが思いがけず注目を集め、不特定多数の開発者が関わる可能性もゼロではありません。
ADRに設計判断を記録しておくことで、将来の自分自身や、潜在的な共同開発者に対して、設計の意図や根拠を明確に伝えることができます。
私の場合は、過去に「ユニットテストを日本語メソッド化する！」という設計を推し進めたら、後々に非日本語話者のエンジニアが参加することになり、その設計が不適切だと気づきました。ADRを書いていれば、そのような問題を未然に防ぐことができたかもしれません（本当か？）。
変化への対応をスムーズにする
個人開発では、プロジェクトの要件や技術的な状況を柔軟に変更することができます。しかし、その一方で、変更によって設計の一貫性が損なわれたり、過去の設計判断が考慮されなくなってしまうリスクも孕んでいます。ADRを記録し、定期的に見直すことで、変更による影響を最小限に抑え、一貫性を保ちながらプロジェクトを進めることができます。
また、文章化によって思考が整理され、「このアーキテクチャ変更は本当に必要なのか？」と冷静に判断できることもあります。
私が「NuxtアプリのVue2をバージョン3にアップデートするべきか」という検討をした際に、ADRを書いたことで、アップデートの必要性を再確認し、中断の判断をすることができました。
個人を軸にプロジェクト横断できる
ADRは、特定の時点における設計判断だけでなく、その時点における外部環境(利用可能な技術、ライブラリ・フレームワークのトレンド、開発手法など)も合わせて記録することで、より価値のある情報になります。例えば、「2024年当時はXというフレームワークを採用したが、2025年に登場したYというフレームワークの方が、当時の状況を考慮しても優れていたため乗り換えた」といった記録を残すことで、自身のアーキテクチャ選定の傾向と成長を分析することができます。
個人開発では、開発者自身がすべてのプロジェクトを統括するアーキテクトの役割も担うため、ADRの活用による効果はさらに大きくなります。
私の場合は今まで「iOSでRxSwiftを使ってMVVMアーキテクチャを構築する」というADRを逆パターンの「新規プロジェクトでRxSwiftやFluxを避ける」に反映しました。
また「サーバーサイド言語をリプレイせずPHPを使い続ける」や「ECSではなくAmazon EKSでインフラ構築する」といった意思決定のタイミングで記録したADRは、その後の複数のプロジェクトにも影響を与えています。
ADRの運用方法
軽量な運用
『Design It!』ではADRは軽量であることが重要であると述べられています。 個人開発においても、チーム開発のような厳格なルールや複雑なテンプレートは不要です。重要なのは、自分にとって理解しやすく、管理しやすい方法で運用することです。
私は、タスク管理ツールにNotionのページを埋め込み、そこに自由に書き込んでいます
ツールとフォーマット
テキストエディタやMarkdownで十分です。世間では、さまざまなADRツールが紹介されていますが目的を理解していれば必須ではありません。
一般的な記述フォーマットは、先にあげた、タイトル、ステータス、コンテキスト、決定、影響の項目で構成されます。
しかし項目は厳格に決まっておらず、各自カスタマイズしているようです。
新しいトピックとしては、ThoughtworksのAndrew Harmel-Lawの近著『Facilitating Software Architecture』では、よりスケールする意思決定を実現するための"Architecture Advice Process"とその収集・記述方法が提案されています
Architecture Advice Processでは、誰でも（アーキテクトであれ開発者であれ）、アーキテクチャ上の決定を下し、最終的にそれを伝えることができます。ただし、オプション作成の段階で、以下の2つのグループからアドバイスを求める必要があります。
1 .その決定によって 大きな影響を受けるすべての人
2. その決定が下される 分野の専門知識を持つ人々4. The Architecture Advice Process(引用者訳)
公開
ADRを公開することで、外部からのフィードバックを得られるという利点があります。 個人開発の場合は技術ブログを書くのがいいでしょう。
ただし、技術評価に関する記事は、読者の興味を引くための誇張表現(クリックベイト)に陥りやすい傾向があります
強い言葉は避け、公平性を保つために事実と根拠と意見は明確に分けましょう。
公開に抵抗がある場合は、リポジトリのREADMEに記載しておくのも良いでしょう
継続的な記録と振り返り
ADRは継続的に記録し、過去の記録も残しておくことが重要であるとされています。
『C++ソフトウェア設計 ―高品質設計の原則とデザインパターン』では、アーキテクチャドキュメントを、普段は資産として保管し、必要な時にのみアクセスできる銀行の貸金庫に例えています。これは、運用面における理想的なバランスと言えるでしょう
この点については、アーキテクチャドキュメントは銀行の貸金庫のようなものと言えます。情報を確実に保管でき、必要に応じこれまでの履歴をすべて確認できる貴重なものですが、毎日貸金庫を開けるわけではありません。
2章 抽象化の技
まとめ
個人開発においても、ADRを活用することで、設計判断の客観的な視点を持ち、将来の変化に対応するための柔軟性を持つことができます。
簡易的でもいいのでADRを運用し、継続的に記録・振り返ることで、自身やプロジェクトにおけるアーキテクチャの進化を促進しましょう。
