ADRの書き方｜技術選定の理由を残すテンプレートと運用ルール

2026年9月18日 2026年9月18日株式会社 SunSunTech

株式会社 SunSunTech

システム開発で技術や設計方針を決めた後、「なぜこの案を選んだのか説明できない」「担当者が変わると同じ議論を繰り返す」と困ることがあります。そんな開発者、テックリード、プロジェクトリーダーに役立つのがADR（Architecture Decision Record／アーキテクチャ決定記録）です。

この記事では、ADRを作る目的、記録すべき判断、比較軸の決め方、すぐ使えるテンプレート、レビューと更新のルールまでを実践的に解説します。読み終えれば、結論だけでなく背景と理由が伝わり、将来の変更にも耐えられる設計判断の残し方が分かります。

ADRとは？設計判断の背景を残す短い記録
- ADRを作るべき場面と作らなくてよい場面
書き始める前に比較軸と制約をそろえる
ADRテンプレートと項目別の書き方
ADRを形骸化させないレビューと運用ルール
ADRに関するよくある質問
まとめ
- - 投稿者プロフィール
    - 最新の投稿

ADRとは？設計判断の背景を残す短い記録

ADRは、アーキテクチャ上の重要な判断を1件ずつ記録する文書です。一般的には「背景」「検討した選択肢」「決定」「結果や影響」を簡潔にまとめます。詳細設計書の代わりではなく、設計書だけでは抜けやすい「なぜ」を残すことが主目的です。

たとえばデータベース、認証方式、メッセージング基盤、クラウドサービス、API方式を選ぶ場面では、どの案にも利点と制約があります。採用技術の名前だけを残すと、数か月後には制約や前提が見えなくなります。ADRに判断時点の事情を残しておけば、変更要求が出た際に「前提が変わったから再検討する」と合理的に判断できます。

ADRの価値は、決定を永久に固定することではありません。チームが過去の判断を再現でき、変更の必要性を同じ材料で議論できる状態を作ることにあります。

ADRを作るべき場面と作らなくてよい場面

すべての実装判断をADRにすると、記録の負担が増えて重要な決定が埋もれます。次のいずれかに当てはまる場合を作成対象にすると運用しやすくなります。

後から変更すると、データ移行や大規模改修が必要になる
複数チーム、セキュリティ、運用、費用に影響する
有力な選択肢が複数あり、採否の理由を説明する必要がある
標準から外れる構成や、暫定対応を採用する
将来、前提条件が変われば見直す可能性が高い

一方、命名規則に沿った変数名、容易に戻せる局所的なリファクタリング、既存ルールで一意に決まる実装などは、通常のコードレビューやチケットで十分です。判断に迷ったら「この決定を半年後に別の担当者が変更するとき、理由を知らないことで大きな手戻りが起きるか」を基準にします。

よくある失敗は、会議の議事録をそのままADRにすることです。議事録は発言の経緯を残しますが、決定と根拠が散らばりがちです。ADRでは1つの判断に焦点を絞り、読者が短時間で結論とトレードオフを把握できる形に整理します。

書き始める前に比較軸と制約をそろえる

説得力のあるADRは、結論より先に評価条件をそろえています。まず「何を解決する判断か」を1文で定義し、必須条件と希望条件を分けましょう。必須条件は満たさなければ採用できない条件、希望条件は優劣を比べる条件です。

比較軸には、性能、可用性、セキュリティ、開発速度、運用負荷、費用、既存環境との整合性、チームの習熟度、移行難易度などがあります。テーマに関係する軸だけを選び、可能な項目は数値や検証結果で示します。「使いやすい」「将来性がある」のような曖昧な表現だけでは、後から評価を再現できません。

候補は採用案だけでなく、現状維持を含めて2〜4案程度を並べます。各案について、利点、欠点、重大なリスク、検証で分かったことを同じ粒度で記載します。先に採用案を決めて都合のよい情報だけを書くと、ADRが意思決定の記録ではなく結論の正当化になってしまいます。

ADRテンプレートと項目別の書き方

形式を統一すると、作成者が変わっても読みやすくなります。次のテンプレートをリポジトリやドキュメント基盤に用意しておくと、記録を始めやすくなります。

# ADR-番号: 判断を表す短いタイトル
ステータス: 提案中 / 承認 / 却下 / 廃止 / 置換
日付: YYYY-MM-DD
関係者: 決定者・相談先

## 背景
解決したい問題、制約、前提、期限

## 選択肢
候補ごとの利点・欠点・リスク・検証結果

## 決定
採用案と、決め手になった比較軸

## 影響
得られる効果、受け入れる不利益、必要な作業

## 見直し条件
再検討を始める指標、期限、前提の変化

タイトルは「DBについて」ではなく「注文履歴の保存先にPostgreSQLを採用する」のように、判断が分かる文にします。背景には製品説明ではなく、今回の問題と制約を書きます。決定欄では、採用案の利点だけでなく、何を諦めたかも明記してください。

影響欄には、移行、監視、教育、契約、セキュリティ審査などの後続作業を含めます。見直し条件には「月間リクエスト数が一定値を超えたとき」「サポート期限の半年前」「障害復旧目標を満たせないとき」など、再評価のきっかけを書きます。これにより、判断を放置せず、必要なときに更新できます。

ADRを形骸化させないレビューと運用ルール

ADRは作ることより、判断の流れに組み込むことが重要です。提案者が下書きを作り、影響を受ける開発、運用、セキュリティなどの担当者がレビューし、決定権を持つ人が承認する流れを決めます。コードと密接な判断はリポジトリで管理し、変更提案とADRを同じレビュー対象にすると記録漏れを減らせます。

承認済みADRの本文を後から書き換えると、当時の判断が分からなくなります。前提が変わった場合は、元のADRを「置換」にし、新しいADRから参照します。軽微な誤字修正を除き、履歴を消さないことが原則です。

運用時は、連番、保存場所、ステータス、命名規則、承認者、レビュー期限をチームで統一します。月1回などの一律棚卸しより、リリース計画、技術的負債の確認、障害振り返りといった既存イベントで関連ADRを参照する方が継続しやすいでしょう。読まれない場合は文書を増やす前に、1件が長すぎないか、検索できるか、関連チケットや設計書から辿れるかを確認します。

ADRに関するよくある質問

Q1. ADRはどのくらいの長さが適切ですか？

決定と根拠を再現できる範囲で短くまとめます。分量を固定する必要はありませんが、長大な要件や検証データは別資料に置き、ADRからリンクすると読みやすくなります。1件に複数の判断が混ざったら分割を検討してください。

Q2. 小規模なチームでもADRは必要ですか？

人数より、変更コストと判断の寿命で決めます。1人で開発していても、半年後の自分が理由を忘れる可能性はあります。重要な技術選定だけに絞れば、小規模チームでも少ない負担で効果を得られます。

Q3. 採用しなかった選択肢も書くべきですか？

書くべきです。代替案と却下理由がないと、同じ案が何度も提案されます。ただし候補を網羅する必要はありません。実際に比較した有力案と、採用できなかった決定的な理由を残しましょう。

まとめ

ADRは、重要な設計判断について、背景、選択肢、決定、影響、見直し条件を残すための短い記録です。対象を変更コストや影響範囲の大きい判断に絞り、比較軸を先にそろえることで、結論の正当化ではなく再現可能な意思決定になります。

まずは現在検討中の技術選定を1件選び、紹介したテンプレートで下書きを作ってください。レビューでは「採用理由」だけでなく「受け入れる欠点」と「見直す条件」が書かれているかを確認しましょう。その1件をチームの標準例にすれば、設計議論の引き継ぎと将来の再判断が格段に進めやすくなります。

投稿者プロフィール

株式会社 SunSunTech: はじめまして。
株式会社SunSunTech代表取締役の鈴木と申します。

SunSunTechは、エンジニアが納得できるキャリアと報酬を得られるSES企業を目指して設立しました。

私は元々、エンジニアとして複数のSES現場で経験を積んできました。
その中で、「スキルに見合った評価が得られない」「給与の仕組みが不透明」といった業界特有の課題に何度も直面してきました。

こうした状況を変えるために、SunSunTechでは、透明性のある評価制度の導入、エンジニアファーストな案件選定など、"エンジニアが報われる仕組み"を徹底しています。

SES企業様とのパートナー連携においても、スピード・誠実・精度を大切にし、長期的に信頼される関係構築を目指しております。

エンジニアの未来を、本気で変えていく。
その想いに共感してくださる方、ぜひ一度お気軽にお声がけください。