ADR(Architecture Decision Record)入門 ── 小規模開発で「なぜこの設計にしたか」を残す最小の方法
· 小村 豪 · 設計, 設計レビュー, ドキュメント, ADR, 技術相談, 保守, 受託開発, Windows開発
「なんでここ、ファイル連携なんですか。普通にDB見ればよくないですか」──引き継いだシステムのコードを開いた開発者は、ほぼ必ずこの種の疑問にぶつかります。そして多くの場合、答えを知る人はもうプロジェクトにいません。
理由はあったはずです。相手システムのDBに直接接続する許可が下りなかったのかもしれないし、当時の納期では安全な方式がそれしかなかったのかもしれません。しかしその理由が残っていないと、後任は「触ってよいのか分からないコード」を前に手が止まるか、逆に理由ごと壊してしまいます。
当ブログでは、受託開発の進め方を「Windowsアプリ 外注・受託開発を依頼する前に整理したいこと」で、契約の枠組みを「IPA『モデル取引・契約書』に学ぶ準委任と請負の使い分け」で解説してきました。この記事はその先にある「作った後、数年間もたせる」ための話です。設計判断の理由を最小の手間で残す仕組み、ADR(Architecture Decision Record)を、小規模な受託開発・社内開発を想定して解説します。
1. まず結論
- 網羅的な設計書より先に、「決定の記録」を残すべきです。保守で本当に困るのは「何をしているか」ではなく「なぜそうしたか」が分からないことだからです。
- ADRは1つの決定を「タイトル/ステータス/コンテキスト/決定/結果」の定型で1ファイルに書く軽量な形式です。Michael Nygardが2011年に提唱し、1件1〜2ページ以内が原則です。1
- 置き場所はコードと同じリポジトリ(例:
docs/adr/0001-title.md)。Wikiや共有フォルダーではなく、コードと一緒にバージョン管理し、コードレビューと一緒に見ます。12 - 決定は上書きしません。方針を変えるときは新しいADRを追加し、古いADRのステータスをSuperseded(置き換え済み)にして相互参照します。ADRは追記専用のログです。2
- 何でも書くのではなく、「後から変えにくい」「複数の妥当な選択肢があった」「制約が決め手になった」決定だけを書きます。命名規則やフォーマッタ設定は対象外です。2
- 筆者の実感では、1件あたり15〜30分で書ける分量に抑えるのが継続の条件です。重厚なテンプレートは最初の3件で止まります。
- 受託開発では、ADRは発注側と共有できる成果物になります。検収時の説明資料、担当者交代・ベンダー交代時の引き継ぎ資料としてそのまま機能します。
2. 「なぜこうなっているのか分からない」問題
2.1 コードはWhatを語るが、Whyを語らない
コードを読めば「何をしているか」は(時間をかければ)分かります。分からないのは次のような「なぜ」です。
- なぜDBはSQL ServerではなくSQLiteなのか
- なぜ他システム連携がWeb APIではなくCSVファイルの受け渡しなのか
- なぜこの帳票だけExcelを起動して印刷しているのか
- なぜ.NET Frameworkのままで、現行の.NETに上げていないのか
こうした決定には、当時の予算・納期・顧客側の制約・既存資産との兼ね合いといったコードの外にある理由が必ずあります。コメントに書くには大きすぎ、設計書に書くには「決定の経緯」は馴染まない。結果として、理由はどこにも残りません。
2.2 決定の置き場所は、数年で消えるものばかり
では実際、設計判断の理由は今どこにあるでしょうか。よくある置き場所を比べてみます。
| 置き場所 | 数年後に残っているか | コードとの距離 | 後任が見つけられるか |
|---|---|---|---|
| 口頭・打ち合わせでの合意 | 残らない | ─ | 不可能 |
| チャット(Teams/Slack) | 流れて実質消える | 遠い | ほぼ不可能 |
| メール | 個人の受信箱に埋没 | 遠い | 退職で消える |
| 議事録(共有フォルダー) | 残るが玉石混交 | 遠い | 「どの回の議事録か」が分からない |
| Wiki・設計書 | 更新が止まり乖離する | 遠い | 見つかるが信用できない |
| ADR(リポジトリ内) | コードと共に残る | 同じリポジトリ | docs/adr/ を開けばよい |
Microsoftのアーキテクトガイダンスも、記録されなかった決定は忘れられ、同じ議論の蒸し返しや、当初の意図に反する変更を招くと明確に指摘しています。2
2.3 受託開発では、契約の切れ目が記憶の切れ目になる
自社開発なら「あの人に聞けば分かる」がしばらく通用しますが、受託開発では担当者の異動・退職に加えてベンダー交代があります。開発したベンダーと保守するベンダーが別になった瞬間、口頭とチャットにあった「なぜ」は完全に失われます。
契約の観点から見ても、開発と保守が別契約・別工程になるのは普通のことです(この構造は「IPA『モデル取引・契約書』の解説記事」で扱いました)。また「準委任契約の正しい働き方」で整理したとおり、準委任では受託側が自律的に業務を進めるからこそ、何をどう判断したかを発注側に示せる記録が信頼の裏付けになります。ADRはこの両方に効きます。
3. ADRとは何か
3.1 Nygardの提案 ── 5つの要素と2ページの上限
ADRはMichael Nygardが2011年のブログ記事「Documenting Architecture Decisions」で提唱した形式です。1 要点は次のとおりです。
- 1つの決定につき1ファイル。連番を振り、番号は使い回さない
- ファイルはMarkdownなどの軽量な形式で、プロジェクトのリポジトリ内に置く
- 構成はタイトル/ステータス/コンテキスト/決定/結果(Consequences)の5要素
- ステータスは提案中(proposed)→承認済み(accepted)と進み、覆すときは廃止(deprecated)や置き換え済み(superseded)にする。古い記録は消さない
- 全体で1〜2ページ以内。将来の開発者が会話するように読める、完結した文章で書く
「アーキテクチャ」と付きますが、大規模システム専用の手法ではありません。むしろ専任のアーキテクトも文書化担当もいない小規模開発でこそ、この「最小限の定型」が効きます。なお、ADRのテンプレートやツールはコミュニティサイト(adr.github.io)に体系的に整理されており、「アーキテクチャ上重要な決定を、根拠とトレードオフごと記録する」という考え方の入り口として参照できます。3
3.2 Markdownテンプレート
筆者が小規模案件で使っている、Nygard形式そのままの最小テンプレートです。
# ADR-NNNN: (決定内容を短い一文で)
## ステータス
提案中 | 承認済み | 廃止 | 置き換え済み(→ ADR-MMMM)
## コンテキスト
なぜこの決定が必要になったか。技術的・業務的な前提、
制約(予算・納期・既存資産・顧客環境)、検討した選択肢を、
当時の状況を知らない読み手にも分かるように書く。
## 決定
「〜する」と能動態で言い切る。1〜3文。
## 結果
この決定で良くなること・悪くなること(トレードオフ)を両方書く。
将来この決定を見直すきっかけになる条件があれば書く。
ポイントは「結果」に悪い点も書くことです。トレードオフのない決定は記録する価値がほとんどありません。Microsoftのガイダンスも、決定の帰結を意図的にも偶発的にも隠さないこと、根拠のない記録は時間とともに価値を失うことを強調しています。2
4. 何をADRに書くか・書かないか
ADRが続かない最大の原因は「何でも書こうとすること」です。Microsoftのガイダンスでは、記録するのはシステムの構造や重要な品質特性に影響するもの、後戻りが難しいものに限るとされています。2 これを日常の判断に落とすと、次の表になります。
| 決定の種類 | 例 | ADRに書くか | 理由 |
|---|---|---|---|
| 後から変えにくい技術選定 | DBをSQLiteにする、通信をファイル連携にする | 書く | 変更コストが大きく、理由を知らずに触ると危険 |
| 複数の妥当な選択肢から選んだ | 帳票をCOM連携ではなくライブラリ生成にする | 書く | 「なぜ他方を捨てたか」が後任の再検討を短縮する |
| 制約が決め手になった | 顧客環境がオフラインなので自動更新を諦めた | 書く | 制約が消えたとき(環境刷新時)に見直せる |
| 外部との取り決め | CSVの文字コード・レイアウトを相手先仕様に合わせた | 書く | 自社だけでは変えられない境界だと明示できる |
| 規約・スタイルの統一 | 命名規則、フォーマッタ、usingの並び順 | 書かない | .editorconfig 等の設定ファイル+自動化で足りる |
| いつでも変えられる実装詳細 | 内部クラスの分割、privateメソッドの構成 | 書かない | コードとコードレビューで足りる |
| 定例的な運用作業 | ライブラリのパッチバージョン更新 | 書かない | 変更履歴(コミットログ)で足りる |
迷ったときの基準は一つで、「1年後にこのコードを見た人(自分を含む)が『なぜ？』と聞きたくなるか」です。聞きたくなるなら書く、コードや設定を見れば自明なら書かない。
もう一つの落とし穴は、書く粒度を「ドキュメントの種類」で考えてしまうことです。次のように役割分担を決めておくと迷いません。
| 残したい情報 | 適した場所 | ADRとの関係 |
|---|---|---|
| なぜこの方式を選んだか | ADR | 本体 |
| 現在の構成図・データの流れ | 設計書(薄く) | ADRから参照する |
| 個々の変更の内容 | コミットメッセージ / PR | ADR番号を書いて紐づける |
| 操作手順 | 操作マニュアル | 別物(読み手が違う)。書き方は「Wordマニュアル作成の基本」参照 |
| 障害対応の記録 | 障害票・issue | 対応の結果、方式を変えたらADRを起こす |
5. 小規模受託での運用
5.1 ディレクトリとファイル名
リポジトリ直下に docs/adr/ を切り、連番+短いスラッグで置きます。
docs/
adr/
0001-record-architecture-decisions.md
0002-use-sqlite-for-local-storage.md
0003-excel-report-via-com-automation.md
0007-excel-report-via-openxml-library.md
最初の1件目は「ADRを使うことにした」というADR自身にするのが定番です。これで後任は docs/adr/ を見れば運用ルールごと理解できます。
5.2 いつ書き、誰がレビューするか
- 書くタイミングは「決めた直後」です。設計検討の締めとして、打ち合わせの結論をその日のうちにADRにします。後述しますが、まとめて後から書くのは失敗します。
- コードレビューにADRを含めます。方式に関わる変更のプルリクエストにADRの追加・更新が含まれているかを見る、それだけです。ADR専用の承認会議は不要で、レビューの一部にするのが小規模チームの現実解です。ADRをバージョン管理下に置くことはMicrosoftのガイダンスでも推奨されています。2
- 決定を覆すときは、新しいADRを書き、古いADRのステータスを
Supersededに変えて相互参照します。本文は書き換えません。承認済みの記録を編集せず、置き換えの連鎖で履歴を保つ──これがADRを「追記専用のログ」として扱うということです。2
5.3 発注側と共有する成果物としてのADR
受託開発では、ADRを納品物の一部として発注側と共有することを勧めます。効果は3つあります。
- 検収・説明の材料になる。「なぜこの構成なのか」を口頭で説明する代わりに、ADRを見せれば済みます。制約(予算・納期・環境)が決め手だった決定は、発注側自身が当事者なので、記録があると後々の認識齟齬を防げます。
- ベンダー交代への保険になる。発注側の立場では、次のベンダーに渡せる「判断の履歴」があるかどうかで、引き継ぎのコストとリスクが大きく変わります。発注前の整理については「Windowsアプリの受託開発ガイド」で書いたとおりですが、納品後に残る文書として何をもらうかを契約時に決めておく際、ADRは費用対効果が最も高い部類です。
- 準委任の報告と相性がよい。準委任契約では業務遂行の報告が求められますが、設計フェーズの報告にADRをそのまま使えます。
5.4 かかる時間の現実感
筆者の経験では、テンプレートに沿って1件書くのに15〜30分です。決定の頻度は小規模案件なら月に数件程度なので、月1〜2時間の投資で「なぜ」が全部残ります。数年後の調査・再検討・引き継ぎで消える時間と比べれば、割に合わない現場はまずありません。
6. ありがちな失敗
| 失敗パターン | 症状 | 対策 |
|---|---|---|
| 書きすぎる | 些末な決定までADR化し、3週間で力尽きる | 4章の判断表で対象を絞る。月数件が正常 |
| テンプレートが重厚 | 承認欄・影響分析・リスク評価つきの様式で誰も書かない | Nygardの5要素だけに戻す。1〜2ページ上限1 |
| Wikiに書く | コードと別の場所で更新が止まり、乖離して信用を失う | リポジトリ内に置き、PRと一緒にレビューする |
| 後からまとめて書く | 「落ち着いたら書く」→記憶が消えていて書けない | 決めた直後に書く。書けないなら決定の場で画面共有しながら書く |
| 過去のADRを書き換える | 履歴が消え、「いつ方針が変わったか」が分からなくなる | Supersededで置き換え、本文は不変に保つ2 |
| 結果(悪い点)を書かない | ただの決定通知になり、再検討の役に立たない | トレードオフと「見直しの条件」を必ず書く |
特に「後からまとめて書く」は、既存システムに途中からADRを導入するときに陥りがちです。過去の決定をすべて復元しようとせず、分かっている主要な決定だけを遡って数件書き、あとは今日以降の決定から積むのが現実的です。既存(ブラウンフィールド)のシステムでも、把握できている過去の決定があれば遡って記録する価値はあります。2
7. ADRの実例
小規模なWindows業務アプリでよくある題材で、実際のADR全文の形を2本示します(内容は一般化した例です)。
1本目は、技術選定の定番であるデータベースの決定です。
# ADR-0002: 業務データの保存先はSQLiteにする
## ステータス
承認済み (2026-07-17)
## コンテキスト
本システムは1拠点の在庫管理デスクトップアプリである。利用者は2〜3名いるが、
運用上は事務室の主担当PC 1台にインストールし、交代で使う(同時利用は1名)。
顧客社内にDBサーバーを運用できる担当者はおらず、サーバー機の導入予算もない。
データ量は10年運用しても数百MB程度の見込み。
選択肢として SQL Server Express / SQLite / Accessファイル(.accdb) を検討した。
SQL Server Expressはサーバーの構築とWindows Update後の稼働確認を
継続的に行える体制が顧客側にないため見送り。Accessは同時更新時の
破損リスクと将来の移行性を考慮して見送り。
## 決定
データ保存にはSQLiteを採用する。DBファイルは共有フォルダーに置かず、
主担当PCのローカルに置く。バックアップは日次でVACUUM INTOによる
スナップショットを作成してNASへ保存する(稼働中の生ファイルコピーは
WALファイルの取りこぼしや書き込み競合で壊れたバックアップになるため不可)。
## 結果
- 良い点: DBサーバーの構築・保守が不要。バックアップもSQL 1文で完結する
- 良い点: アプリ配布にランタイムを同梱でき、インストールが単純になる
- 悪い点: 書き込みはDB単位のロックになるため、多拠点・大人数には拡張できない
- 悪い点: 将来サーバーDBへ移す場合はデータ移行と接続層の改修が必要
- 複数PCからの同時利用が必要になった時点で、この決定は見直す(その場合はサーバーDBまたはAPI経由の構成になる)
2本目は、一度した決定を覆す例です。Supersededの使い方も含めて見てください。
# ADR-0007: 帳票のExcel出力はCOM連携ではなくライブラリ生成にする
## ステータス
承認済み (2026-07-17) ── ADR-0003(COMオートメーション採用)を置き換える
## コンテキスト
納品書と月次集計をExcelファイルで出力する要件がある。
当初はADR-0003のとおりExcelのCOMオートメーションで実装したが、
無人実行する夜間バッチでExcelプロセスが残留して処理が止まる事象が
繰り返し発生し、実行用PCにOfficeライセンスが必要な点も
端末更新のたびに問題になった。
選択肢として COM連携の継続(プロセス監視を追加) /
Open XML形式を直接生成するライブラリへの切り替え /
帳票のPDF化(仕様変更) を検討した。PDF化は取引先が
Excelでの追記を前提としているため不可。
## 決定
帳票は.xlsxをライブラリで直接生成する方式に切り替える。
Excel本体には依存しない。書式はテンプレート.xlsxとして
リポジトリに含め、セル差し込みで生成する。
## 結果
- 良い点: 実行環境にExcelが不要になり、無人実行が安定する
- 良い点: プロセス残留の問題が構造的になくなる
- 悪い点: Excelの全機能は使えないため、既存帳票の一部書式は簡略化が必要
- 悪い点: 既存帳票のテンプレート化に改修工数がかかる
- ADR-0003はSupersededとし、本ADRへの参照を付けた
この2本を読むだけで、「このシステムはなぜサーバーDBがないのか」「なぜ帳票コードにExcel起動の痕跡があるのか」という、引き継ぎで必ず出る疑問に答えられることが分かると思います。合計でも1,500字程度、書くのに1時間かかりません。
8. まとめ
- 保守・引き継ぎで失われて困るのはWhatではなくWhyです。記録されなかった決定は忘れられ、議論の蒸し返しと意図に反する変更を招きます。2
- ADRは1決定=1ファイル、5要素、1〜2ページ以内の軽量な記録形式です。Nygardの原型のまま、小規模開発にそのまま使えます。1
- 書くのは「変えにくい」「選択肢があった」「制約が決め手」の決定だけ。規約やフォーマットは自動化に任せ、ADRの対象にしません。2
- 置き場所は
docs/adr/、レビューはプルリクエストと一緒に。決定は上書きせずSupersededで置き換え、履歴を不変に保ちます。12 - 受託開発では、ADRは検収の説明資料・ベンダー交代時の引き継ぎ資料として発注側にも価値のある納品物になります。
- 1件15〜30分。まず次の設計判断から1本書くこと、既存システムなら分かっている主要な決定を数件だけ遡って書くことから始めてください。
関連記事
- 受託開発・運用保守の契約はどう結ぶべきか - IPA「モデル取引・契約書」に学ぶ準委任と請負の使い分け
- 偽装請負にならないための準委任契約の正しい働き方
- Windowsアプリ 外注・受託開発を依頼する前に整理したいこと
- Wordマニュアル作成の基本 - ダメな例と改善策
関連する相談領域
合同会社小村ソフトでは、設計レビューの中でのADR導入支援、既存システムの設計判断の棚卸しと文書化、引き継ぎ・ベンダー交代を見据えた保守体制づくりを扱っています。
参考リンク
-
Michael Nygard, Documenting Architecture Decisions. ADRの原典(2011年)。タイトル/コンテキスト/決定/ステータス/結果の5要素、提案中→承認済み→廃止/置き換え済みというステータス、1〜2ページの分量、連番ファイルとしてリポジトリに置くこと、古い決定を消さずSuperseded等で残すことについて。 ↩ ↩2 ↩3 ↩4 ↩5 ↩6
-
Microsoft Learn, Maintain an architecture decision record (ADR). Azure Well-Architected Frameworkのガイダンス。ADRを追記専用のログとし承認済みの記録を編集しないこと、変更時は新しい記録で置き換えて相互リンクすること、対象をシステム構造・重要な品質特性に影響し後戻りが難しい決定に限ること、コンテキストと根拠・トレードオフ・ステータス(Proposed/Accepted/Superseded)を含めること、記録されない決定は忘れられ議論の蒸し返しや意図に反する変更を招くこと、既存ワークロードでも遡って記録する価値があることについて。 ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8 ↩9 ↩10 ↩11 ↩12 ↩13
-
adr.github.io, Architectural Decision Records. ADRのコミュニティサイト。アーキテクチャ上の決定(AD)とアーキテクチャ上重要な要求(ASR)の定義、ADRが単一の決定とその根拠・トレードオフ・帰結を記録するものであること、各種テンプレートとツールの整理について。 ↩
関連する記事
同じタグを共有する最新の記事です。さらに近い話題で知識を深められます。
障害対応は復旧で終わらない ── 小さな開発チームのためのポストモーテム(再発防止)の型
障害を「直して謝って終わり」にすると同じ障害を繰り返します。SREのblameless postmortemの考え方を小規模チームのWindowsアプリ保守向けに翻訳し、1時間で書けるテンプレート、直接原因と寄与要因の分け方、再発防止策の強度判断表、実施のトリアージまでを実...
「何秒で動けば満足か」を決め忘れないために ── IPA「非機能要求グレード」で非機能要件を整理する
システム開発で「速度が遅い」「障害対応が想定外」と揉める原因の多くは、非機能要件の決め忘れです。IPAが公開する「非機能要求グレード」の6大項目、グレード表とモデルシステムの使い方、中小企業の業務アプリでの現実的な活用方法を、発注側にも分かりやすく解説します。
ソースコードも仕様書もないシステムを引き継いだら ── 止めずに運用・保守するための実務手順
開発会社の廃業や担当者の退職で、ソースコードも仕様書もない業務システムだけが残った ── そんな状態から運用・保守を始めるための実務手順を整理します。動いている環境の保全とバックアップ、実行ファイル・DB・連携先の棚卸し、挙動からの仕様復元、逆コンパイルの技術的な可能性と法...
WindowsアプリのWeb化、しない方がいいケース ── 判断表と「分割」という現実解
「社内のWindowsアプリをWebにしたい」という要望は増えていますが、装置連携・ローカルファイル処理・オフライン運用・高速入力UIを抱えたアプリでは、Web化がコスト増と機能劣化を招くことがあります。Web化に向くケース・向かないケースの判断表と、全部Web化ではなく一...
Windowsアプリ 外注・受託開発を依頼する前に整理したいこと
Windowsアプリの外注・受託開発を依頼する前に、既存ソフト改修、装置連携、COM/ActiveX、配布・更新、保守の整理ポイントを解説します。
関連トピック
このテーマと近いトピックページです。記事を起点に、関連するサービスや他の記事へ進めます。
Windows技術トピック
Windows 開発、不具合調査、既存資産活用の技術トピックをまとめた入口です。
このテーマがつながるサービス
この記事は次のサービスページにつながります。近い入口からご覧ください。
Windowsアプリ開発
業務アプリ、装置連携、通信ツールなどの Windows ソフト開発を支援します。
技術相談・設計レビュー
改修方針、設計レビュー、既存資産の扱いを整理するための技術相談です。
よくある質問
この記事のテーマについて、相談時によくある質問をまとめています。
- ADR(Architecture Decision Record)とは何ですか？
- ソフトウェアの構造に関わる1つの決定を、「タイトル/ステータス/コンテキスト/決定/結果」という短い定型で1ファイルに記録するドキュメントです。Michael Nygardが2011年に提唱した軽量な形式で、1件あたり1〜2ページ以内に収め、コードと同じリポジトリにMarkdownとしてコミットするのが基本です。網羅的な設計書と違い、「なぜその選択をしたか」と「捨てた選択肢」を残すことに特化しています。
- ADRには何を書いて、何を書かなくてよいのですか？
- 書くべきなのは、後から変えにくい決定(データベースや通信方式の選定、外部連携の形式など)、複数の妥当な選択肢から選んだ決定、予算・納期・既存資産といった制約が決め手になった決定です。逆に、命名規則やフォーマッタ設定のようにツールや規約で機械的に統一できるもの、変更が容易でコードを読めば足りるものは書く必要がありません。判断に迷ったら「1年後の自分が『なぜ？』と聞きたくなるか」を基準にします。
- 決定を変更したくなったら、過去のADRを書き換えてよいですか？
- 書き換えず、新しいADRを追加して置き換えます。古いADRはステータスをSuperseded(置き換え済み)に変えて新しいADRへの参照を付け、本文はそのまま残します。Microsoftのガイダンスでも、ADRは追記専用のログとして扱い、承認済みの記録を後から編集しないことが推奨されています。こうすることで「いつ・なぜ方針が変わったか」という履歴自体が引き継ぎ資料になります。
- 設計書があればADRは不要ではないですか？
- 役割が違います。設計書は「現在どういう構造か(What)」を示しますが、「なぜその構造を選び、何を捨てたか(Why)」は普通残りません。また網羅的な設計書は更新が止まりやすく、数年後にはコードと乖離しがちです。ADRは決定のたびに数百字を追記するだけなので更新が止まりにくく、設計書が古びても「判断の理由」だけは生き残ります。小規模開発では、詳細設計書を薄くしてADRを併用する構成が現実的です。
著者プロフィール
記事の著者プロフィールページです。
小村 豪
合同会社小村ソフト 代表
Windows ソフト開発、技術相談、不具合調査を中心に、既存資産が残る案件や原因が見えにくい障害調査に強みがあります。
公開リンク