Tsuzura

技術判断をADRに残す

ADR（Architecture Decision Record）の書き方を、対象とする判断、背景、選択肢、理由、影響、状態、判断変更の履歴まで順に説明します。

公開日
更新日

技術を選んでも、判断した人や当時の条件が分からなくなると、後から同じ議論を繰り返します。理由を確認できないまま既存の構成を変えると、要件や品質条件を崩す可能性もあります。

ADR（Architecture Decision Record）は、システムに長く影響する一件の技術判断について、背景、選択肢、決定、理由、既知の影響を残す記録です。未確認事項が残る間は提案中とし、人が確認してから承認済みまたは不採用に進めます。判断が変わった場合は、過去の記録を消さず、後続のADRとの関係を残します。

この記事は、AIを補助に使いながらWebサービスや業務システムを初めて設計する人を対象にしています。先に、記録する判断に関する要件、品質条件、または技術選定の結果を用意してください。読み終えると、空欄からADRを一件作り、判断の状態と履歴を一覧に残せます。

要件が未決なら要件と受入条件の決め方に戻ります。品質条件が必要なら非機能要件の決め方を確認してください。候補の比較と採否は技術選定の進め方で扱います。この記事では、詳細設計、会議の進め方、Git操作、全社の承認制度、完成済みのADR例は扱いません。

ADRとは

ADRは、重要な技術判断を後から確認するための短い記録です。Michael Nygardの原典は、構造、性能や可用性などの品質特性、依存関係、外部との取り決め（インターフェース）、構築方法に影響する一件の判断を対象とし、題名、背景、決定、状態、結果を基本項目にしています。

AWSのADRプロセスも、重要な判断、その背景、決定、結果を一件ずつ記録し、ADRの集合を判断一覧（Decision Log）として管理します。本記事では、ADRの題名と現在の状態から必要な記録を探せる一覧にします。

ADRには複数の書式が公開されています。本記事では、原典と複数の公式ガイドを基に、初めて運用するための最小項目を整理します。この整理はTsuzuraの軽量な運用案です。

技術選定票・設計書・タスク記録との違い

ADRは、候補の調査、詳細設計、作業管理を一つにまとめる文書ではありません。役割を分け、必要な資料を相互に参照します。

記録 主に残すこと ADRとの関係
要件・品質条件 必要な結果と合格条件 判断の背景と基準になる
技術選定票 候補、条件、証拠、採否 ADRが参照する判断材料になる
ADR 重要な決定、理由、影響、状態 現在有効な判断と履歴を残す
詳細設計書 構造、データ、処理、接続の詳細 ADRから必要な箇所を参照する
Issue・タスク 実行する作業、担当、進捗 Accepted後の実装につなぐ
テスト・レビュー記録 判断どおりに実装されたかの証拠 ADRの確認方法につなぐ

MicrosoftのADRガイドは、ADRを詳細な設計ガイドにせず、補足資料にリンクしても判断自体は単独で理解できるようにすると説明しています。AWSのベストプラクティスは、ADRがあるだけでは、既存コードが判断に従うとは限らないとしています。

コードの責務と依存を決める場合はコードアーキテクチャの選び方を参照してください。変更をどこで分けるかはソフトウェア設計の基本原則で扱います。

ADRに残す判断を選ぶ

すべての実装判断をADRにすると、重要な判断を見つけにくくなります。影響範囲が複数の部分や関係者にまたがるか、元に戻すために複数箇所の変更や関係者の再確認が必要な判断を候補にします。後から理由を確認する必要があるかも含めて判断します。

影響が長く残るか確認する

次のいずれかに当てはまる判断を、この記事では重要な判断としてADRの候補にします。

  • システムの構造や責務分担（どの部分が何を担当するか）を変える
  • セキュリティ、可用性、性能、保守性など、複数の部分や関係者に影響する品質条件を決める
  • 複数の部分を結ぶ依存関係（ある部分が別の部分を前提にする関係）を決める
  • 外部からの接続方法やデータ形式など、公開する取り決めを決める
  • 複数の部分の実装や運用の前提になるライブラリ、フレームワーク、実行基盤（システムを動かす環境）、構築方法を決める
  • 元に戻すために、複数箇所の変更、データ移行、または関係者の再確認が必要になる
  • 複数の関係者が、後から判断理由を確認する必要がある

AWSのFAQは、構造、性能や可用性などの品質条件、依存関係、外部との取り決め（インターフェース）、ライブラリやフレームワークなどの構築方法を対象に挙げています。MicrosoftのADRガイドは、構造、システムの品質を左右する特性、元に戻しにくい判断から対象を絞ります。

一つの部分だけを変更し、既存の確認手順だけで元に戻せる実装詳細、既存の規約に従うだけの変更、作業手順だけを残す場合は、Issueやタスクで足ります。この線引きは一律の標準ではありません。迷う場合は、影響を受ける部分と関係者を書き出し、判断者に確認するまでADRの候補として扱います。

一件の判断に分ける

一件のADRには、独立した判断を一つだけ書きます。判断を一文で示せない、承認する人が異なる、見直す条件が異なる、置き換える時期が異なる場合は分けます。

Nygardの原典は、一件のADRが一件の重要な判断を扱うと説明しています。MicrosoftのADRガイドも、短期・中期・長期で判断が異なる場合は、段階ごとに記録を分けるよう示しています。

対象に含める範囲と含めない範囲を先に書きます。関連するADRがある場合は番号とリンクを付けます。複数の判断が依存する場合も、一件にまとめず関係を記録します。

書く前に判断材料をそろえる

ADRは、確認済みの判断材料から作ります。情報が足りない状態を、AIや書き手の推測で埋めません。

決定前と決定後を分ける

作成を始める時点では、状態をProposed（提案中）にします。判断材料を、確認済み・前提・未確認の三つに分けます。

状態 意味 ADRでの扱い
確認済み 要件、資料、検証結果、関係者の確認で裏付けられる 背景、基準、理由に使える
前提 現時点では置く必要があるが、事実として確定していない 前提と明記し、見直す条件を付ける
未確認 判断を変え得る情報が足りない 担当と期限を決め、解決までProposedを維持する

未確認事項が結論に影響しないと判断する場合は、誰が何を受け入れたかを記録します。判断者が不在、必須条件が未確認、受け入れる影響が不明な場合はAcceptedに進めません。

根拠を複製せず参照する

ADRには、要件、品質条件、技術選定票、検証結果、契約、設計資料の参照先を付けます。詳細な表や手順を全文コピーする必要はありません。ただし、リンクを開かなくても、何を決め、なぜその案を選び、どの影響を受け入れたかは分かるようにします。

NASAの意思決定分析ガイドは、判断の状況、評価条件、候補、評価方法、前提、限界、不確実性、比較結果、最終判断と理由を記録対象にしています。NASAが想定する報告の詳しさを小規模サービスにそのまま要求するのではなく、ADRが参照すべき判断材料を確認するために使います。

参照先には、資料名、対象版、確認日を含めます。チャットや会議だけに理由が残っている場合は、確認できた内容をADRに移し、元の記録にリンクします。

一件のADRを書く

本記事では、Nygardの基本項目に、選択肢、判断基準、確認方法、管理担当（Owner）、見直し条件を加えます。項目を増やすことより、判断と理由を確認できることが重要です。

識別情報と状態

最初に次の情報を書きます。

  • 重複しないADR番号
  • 決定内容が分かる短い題名
  • 状態
  • 作成日または決定日
  • 管理担当
  • 判断者
  • 対象範囲
  • 参照資料
  • 関連ADR

管理担当は、記録を更新し、レビューを進める人です。判断者は、影響と責任を確認して採否を決める人です。同じ人が兼ねても、役割は分けて記録します。

背景と選択肢

背景には、なぜ今決める必要があるか、必要な結果、制約、確認済みの事実、前提、未確認事項を書きます。判断を正当化するための感想ではなく、当時の条件を確認できる内容にします。

MADR 4.0.0の最小テンプレートは、背景と課題、検討した選択肢、決定結果と理由を分けています。選択肢には、実際に検討した案だけを書きます。必要な場合は、現状を維持する案や、何もしない案も含めます。

選択肢の詳しい比較は技術選定票に残し、ADRでは候補名、判断基準、採用・不採用の理由を追えるようにします。検討していない候補を後から追加しません。

決定と理由

決定には、何を採用し、どの範囲に適用するかを明確に書きます。「適切に対応する」「必要に応じて使う」だけでは、実装やレビューで判断を確認できません。

理由を書くときは、判断基準と証拠を対応づけます。採用案の利点だけでなく、他の案を選ばなかった理由、受け入れる制約、残る不確実性も分けます。

AWSのFAQは、背景に検討した解決策を含め、決定を明確にし、結果に既知のトレードオフを記録するよう示しています。これはAWSの推奨書式であり、唯一の書式ではありません。

影響と確認方法

結果には、判断後に生じる変化を記録します。

  • 良い影響
  • 悪い影響
  • 中立な影響
  • 必要になる実装・移行・運用作業
  • 残る不確実性
  • 見直す条件

Nygardの原典は、良い結果だけでなく、悪い結果と中立な結果も含めるよう説明しています。将来の全影響を予測できるわけではありません。現時点で確認済みの影響と、後で確認する項目を分けます。

MADR 4.0.0の完全テンプレートには、判断基準、選択肢の長所・短所、結果に加え、Confirmation（確認方法）があります。本記事では、実装が判断に従っていることを何で確かめるかを記録します。詳しいテスト設計はテストの種類と選び方で扱います。

レビューして状態を決める

ADRは、書いた人だけでAcceptedにしません。判断の影響を引き受ける人が、背景、理由、影響、未確認事項を確認します。

管理担当と判断者を残す

本記事では、次の四状態から始めます。これは本記事で扱う最小運用であり、外部標準で一律に定められた状態ではありません。

状態 意味 次の行動
Proposed レビュー中 未確認事項を解決し、判断者が確認する
Accepted 現在有効な判断 実装と確認に渡す
Rejected 検討したが採用しない 理由を残し、現在の判断として使わない
Superseded 後続ADRに置き換えられた 後続ADRを参照する

AWSのADRプロセスは、管理担当がProposedをレビューに出し、未解決ならProposedを維持し、承認時はAccepted、不採用時はRejectedとする流れを示しています。承認時には日時、版、関係者一覧を加えるようにも示しています。Tsuzuraのテンプレートでは、判断日と判断者も残します。

チームで別の状態を使う場合は、状態名と意味を判断一覧に定義します。同じ状態名を、担当者ごとに違う意味で使いません。

未確認ならProposedのままにする

次のいずれかに当てはまる場合は、Acceptedに進めません。

  • 判断する範囲が一件に絞れていない
  • 要件または品質条件を参照できない
  • 実際に検討した選択肢が分からない
  • 理由を証拠に対応づけられない
  • 悪い影響または残る不確実性を確認していない
  • 判断者が決まっていない
  • 結論を変える未確認事項が残っている
  • 実装後の確認方法がない
  • 非公開情報を含む参照資料の扱いを確認していない

不足している項目を削って体裁だけ整えるのではなく、未確認事項、担当、期限、未確認事項が解消するまで着手しない作業を記録します。Rejectedの場合も、採用しなかった理由を残します。

判断が変わったら履歴をつなぐ

Accepted後に判断の意味が変わる場合は、新しいADRを作ります。当時の背景と理由を残すためです。

旧ADRを黙って書き換えない

Nygardの原典、AWSのベストプラクティス、MicrosoftのADRガイドは、判断が変わったときに旧記録を残し、後続記録で置き換える方法を示しています。

新しいADRには置き換える旧ADRを、旧ADRには後継となる新ADRを記録します。

  • 新ADR: 置き換えるADR（Supersedes） ADR-XXXX
  • 旧ADR: このADRを置き換えたADR（Superseded by） ADR-YYYY

本記事では、誤字や参照切れは変更履歴を残して修正できます。判断後に確認できた結果は、変更履歴を残して追記できます。対象範囲、決定、決定理由を変える場合は新しいADRにします。この区分は資料間の運用差を踏まえた本記事の軽量ルールです。

RejectedとSupersededの本文は、参照先の修正を除き、当時の記録として保ちます。新しい判断に合わせて過去の理由を書き換えません。

後続ADRと判断一覧を更新する

ADRは関係者が参照できる中央の場所に保存します。Gitは変更履歴を管理しやすく、Wikiは開発環境を使わない関係者も参照しやすいという違いがあります。保存場所の名称より、判断者と実装者が同じ記録を見つけられることを優先します。

AWSのベストプラクティスは、ADRを中央の場所に保存し、GitまたはWikiを選択肢として挙げています。MicrosoftのADRガイドも、判断の一覧をシステムの文書と一緒に参照できる状態を求めています。

判断一覧には、Tsuzuraの軽量運用として次の項目を一行ずつ残します。

ADR 題名 状態 管理担当 判断日 関連ADR

番号を再利用せず、旧ADRも一覧から削除しません。詳細なGit操作はGitで変更を確認・保存・戻すを参照してください。

AIで下書きする

本記事では、AIの利用を、確認済みの判断材料の整理と不足項目の抽出に限定します。判断理由の推測やAcceptedの決定は任せません。

AIに任せる範囲

AIには、確認済みの材料だけで行える次の作業を任せます。

  • 確認済みの文章をADRの項目に整理する
  • 背景、選択肢、理由、影響の不足を質問として出す
  • 前提と未確認事項を分ける
  • 根拠資料と主張の対応を一覧にする
  • 状態、管理担当、関連ADR、見直し条件の空欄を見つける
  • 決定内容と実装タスクの不一致候補を出す

一回の依頼では、対象のADR番号と整理する項目を指定します。状態の変更は任せず、出力後は、人が差分と参照資料を確認します。

AIには、要件、品質条件、技術選定票、参照してよい資料、対象範囲を渡します。確認できないことは「不明」と出すように指定します。AIが作った選択肢、理由、影響を、実際に検討した事実として残しません。

人が確認・決定する範囲

NISTの生成AIリスク管理プロファイルは、生成AIがもっともらしい誤りを示す作話（Confabulation）のリスクを説明しています。また、出力の出典と引用を確認する対応項目を挙げています。AIが示した要件、仕様、費用、契約、引用は原資料で確認します。

人が行うのは、次の判断です。

  • 誰が判断責任を持つかを確定する
  • 要件、品質条件、制約を確認する
  • 選択肢と根拠を原資料で照合する
  • 採用案と受け入れる不利益を決める
  • 未確認事項を受け入れるか、解決まで止めるかを決める
  • AcceptedまたはRejectedに変更する
  • 実装がADRに従うかをテストとレビューで確認する

NISTの同資料は、個人情報や機密データの漏えい、無断利用、開示などを、データプライバシー上のリスクに含めています。AIにADRの背景を送る前に、個人情報、秘密情報、顧客情報、非公開の契約条件が含まれないかを確認します。必要な場合は、利用する製品、契約プラン、管理設定、保存・削除・学習利用の条件を確認します。

秘密値そのものをADRやAI入力に転記しません。個人情報や顧客情報が含まれる場合は送信を止め、プライバシーまたは法務の責任者が利用可否を確認するまでAIに送りません。条件を確認しても、非保存、非学習、適法性が自動的に保証されるわけではありません。

ADRテンプレートと完了確認

次のテンプレートは、Nygard、MADR、AWS、Microsoftの資料を小規模なサービス向けに整理した本記事独自の書式です。外部機関の公式テンプレートではありません。

空欄テンプレート

# ADR-NNNN: 決定内容が分かる短い題名

- 状態: Proposed
- 作成日:
- 判断日:
- 管理担当:
- 判断者:
- 対象範囲:
- 対象外:
- 参照資料:
- 関連ADR:
- 置き換えるADR:
- このADRを置き換えたADR:

## 背景

- なぜ今決める必要があるか:
- 必要な結果:
- 制約:
- 確認済みの事実:
- 前提:
- 未確認事項:

## 判断基準

- 必須条件:
- 比較条件:

## 検討した選択肢

- 選択肢:
  - 確認した内容:
  - 採用または不採用の理由:

## 決定

- 採用する内容:
- 適用する範囲:
- 決定理由:
- 根拠の参照先:

## 結果

- 良い影響:
- 悪い影響:
- 中立な影響:
- 必要になる作業:
- 残る不確実性:
- 見直す条件:

## 確認方法

- 実装で確認すること:
- テスト・レビュー・設定の証拠:
- 確認する人:
- 確認できない場合の扱い:

## 変更履歴

- YYYY-MM-DD:

判断一覧の一行

| ADR | 題名 | 状態 | 管理担当 | 判断日 | 関連ADR |
|---|---|---|---|---|---|
| ADR-NNNN | | Proposed | | | |

完了条件

次を確認できれば、ADRを次工程に渡せます。

  • 対象が一件の重要な判断に絞られている
  • 背景に確認済み、前提、未確認を分けている
  • 実際に検討した選択肢と判断基準がある
  • 決定と理由を根拠に対応づけている
  • 良い影響だけでなく、悪い影響と残る不確実性がある
  • 管理担当、判断者、状態、判断日が分かる
  • 未確認事項が結論を変える場合はProposedのままにしている
  • 実装後の確認方法がある
  • 判断変更時の新旧ADRを相互に追える
  • 判断一覧から現在の状態を見つけられる
  • AIが加えた内容と引用を人が原資料で確認している
  • 非公開情報をADRとAI入力に含めてよいか確認している

Accepted後は、決定をAIに渡す実装タスクの分け方に渡します。実装が判断に従うかはテストとコードレビューで確認します。ADRが完成しても、実装の適合、セキュリティ、性能、法令適合まで確認済みになったとは扱いません。

出典