はじめに
生成AIを使うと、設計案・技術選定・比較表・たたき台の作成がとても速くなります。
一方で、AIが出した案をそのまま採用すると、「なぜその判断をしたのか」が曖昧になりがちです。
そこで役立つのが ADR（Architecture Decision Record） です。
ADRは、重要なアーキテクチャ上の意思決定について、背景・決定内容・結果を軽量に記録する手法です。Thoughtworksも、重要なアーキテクチャ判断をコンテキストや結果とともに記録し、ソース管理に置くことを推奨しています。(Thoughtworks)
想定読者：AIを開発・設計・技術選定に使い始めたエンジニア、PM、テックリード、情報システム担当者。
目次
対象読者
- AIを使って設計案や技術選定のたたき台を作っている人
- 技術選定の理由がチーム内に残らず困った経験がある人
- 「なぜこの設計にしたのか」を後から説明できるようにしたい人
- ADRを聞いたことはあるが、どう使えばよいか迷っている人
- AI活用とガバナンスのバランスを取りたい人
この記事でわかること
- ADRの基本的な考え方
- AIとADRを組み合わせるメリット
- AIに任せてよい部分、人間が判断すべき部分
- ADRのシンプルなテンプレート
- AIを使ってADRを作成・レビューする流れ
- AI活用時に起きやすい落とし穴と対策
この記事の前提
この記事では、特定のクラウドやライブラリには依存しません。
| 項目 | 内容 |
|---|---|
| 対象領域 | システム設計、技術選定、アーキテクチャ判断 |
| 使用ツール | ChatGPT、Claude、Gemini、Copilotなど任意の生成AI |
| ドキュメント形式 | Markdown推奨 |
| 管理場所 | GitHub / GitLab / Azure Repos / Confluence など |
| 想定チーム | 2名以上の開発・運用チーム |
ADRはツールよりも、意思決定を残す習慣が重要です。MicrosoftのAzure Well-Architected Frameworkでも、ADRは意思決定・正当化理由・影響を文書化するための成果物として説明されています。(Microsoft Learn)
本編
全体像
AIとADRの関係は、次のように整理できます。
ポイントは、AIは意思決定者ではなく、意思決定を支援する存在として扱うことです。
AIには、次のような作業が向いています。
- 選択肢の洗い出し
- 比較観点の整理
- メリット・デメリットの初期整理
- ADRの下書き
- 抜け漏れチェック
- 想定リスクの洗い出し
一方で、次の判断は人間が責任を持つべきです。
- 事業上の優先順位
- セキュリティ・法務・コンプライアンス判断
- コスト許容度
- チームのスキルや運用体制
- 最終的な採用・不採用の判断
ADRとは何か
ADRは Architecture Decision Record の略です。
直訳すると「アーキテクチャ上の意思決定記録」です。
ざっくり言うと、ADRは次の問いに答えるためのドキュメントです。
なぜ、その設計・技術・方針を選んだのか？
たとえば、次のような判断を記録します。
- なぜREST APIではなくGraphQLを採用したのか
- なぜRDBではなくドキュメントDBを使うのか
- なぜマイクロサービス化しないのか
- なぜRAG構成を採用するのか
- なぜ特定のLLM APIではなくプライベートLLMを使うのか
- なぜオンプレではなくクラウドを使うのか
ADRの代表的な形式では、Status、Context、Decision、Consequencesなどを記録します。Michael Nygardの元記事でも、ステータス、背景、決定、結果を記述する構成が示されています。(Michael Nygard)
なぜAI時代にADRが重要なのか
AIを使うと、設計案を出すスピードは上がります。
しかし、スピードが上がるほど、次のような問題も起きやすくなります。
- AIが出した案を十分に検証せず採用してしまう
- 判断理由がチャット履歴の中に埋もれる
- 後から見た人が「なぜこうしたのか」を理解できない
- 複数案の比較過程が残らない
- AIの回答に含まれる前提ミスに気づきにくい
特に危険なのは、AIの回答がそれっぽく見えることです。
AIは、もっともらしい比較表やアーキテクチャ案をすばやく作れます。
しかし、その案が自社の制約、既存システム、チーム体制、予算、セキュリティ要件に合っているとは限りません。
そこでADRを使います。
ADRに落とし込むことで、AIが出した案を次のように検証できます。
| 観点 | ADRで確認すること |
|---|---|
| 背景 | 何を解決したいのか |
| 制約 | 予算、期限、スキル、既存システムはどうか |
| 選択肢 | 他にどんな案があったか |
| 決定 | 最終的に何を選んだか |
| 理由 | なぜそれを選んだか |
| 結果 | 何が良くなり、何を受け入れるのか |
つまりADRは、AI活用における 判断のログ になります。
AIとADRの役割分担
AIとADRを組み合わせるときは、実務上の一例として、役割を明確に分けると運用しやすくなります。
| 作業 | AIに任せやすい | 人間が責任を持つ |
|---|---|---|
| 課題の言語化 | ○ | ○ |
| 選択肢の洗い出し | ◎ | ○ |
| 比較表の作成 | ◎ | ○ |
| 技術的な一般論の整理 | ◎ | ○ |
| 自社制約の反映 | △ | ◎ |
| セキュリティ判断 | △ | ◎ |
| 最終決定 | × | ◎ |
| ADRの下書き | ◎ | ○ |
| ADRの承認 | × | ◎ |
AIは「考える材料」を増やすのが得意です。
人間は「現実の制約を踏まえて決める」役割を担います。
この分担を曖昧にすると、AIに判断を丸投げしてしまいます。
逆に、分担を明確にすると、AIは非常に強力な設計補助ツールになります。
ADRテンプレート
まずは、シンプルなADRから始めるのがおすすめです。
# ADR-001: <決定のタイトル>
## Status
Proposed / Accepted / Deprecated / Superseded
## Context
- どのような課題があるか
- どのような制約があるか
- なぜ今この判断が必要か
## Options
### Option 1: <選択肢A>
- メリット:
- デメリット:
### Option 2: <選択肢B>
- メリット:
- デメリット:
### Option 3: <選択肢C>
- メリット:
- デメリット:
## Decision
<最終的に採用する方針を書く>
## Reason
- なぜその選択肢を採用したか
- なぜ他の選択肢を採用しなかったか
## Consequences
### Positive
- 良くなること
### Negative
- 受け入れるデメリット
### Neutral
- 変化するが良し悪しではないこと
## Review Date
<見直し予定日>
## References
- 関連Issue
- 関連Pull Request
- 参考資料
より構造化されたテンプレートを使いたい場合は、MADR（Markdown Architectural Decision Records）も候補になります。MADRは、アーキテクチャ上重要な意思決定をMarkdownで構造的に記録するためのテンプレートとして提供されています。(Architectural Decision Records)
AIを使ったADR作成フロー
AIを使う場合、いきなり「ADRを書いて」と依頼するよりも、段階を分けた方が精度が上がります。
Step 1：課題を整理する
まず、AIに判断させるのではなく、課題を整理させます。
以下の状況をもとに、技術判断で整理すべき論点を洗い出してください。
状況:
- 社内ドキュメント検索を改善したい
- 現在はキーワード検索のみ
- 回答生成にLLMを使いたい
- セキュリティ上、社外秘情報を扱う
- 開発チームは少人数
出力してほしいもの:
- 解決したい課題
- 制約条件
- 検討すべき選択肢
- 判断に必要な追加情報
ここでは、AIに「答え」を出させるのではなく、論点を増やすことを目的にします。
Step 2：選択肢を比較する
次に、複数案を比較させます。
以下の選択肢を、セキュリティ、コスト、実装難易度、運用負荷、拡張性の観点で比較してください。
選択肢:
1. 既存検索のまま改善する
2. RAG構成を導入する
3. 全文検索エンジンのみ導入する
4. ファインチューニング済みモデルを使う
注意:
- 最終判断はまだしない
- 各案のメリット・デメリットを中立的に整理する
- 不明な点は不明と書く
この段階では、AIの比較を鵜呑みにしないことが重要です。
AIが出した比較表は、レビューの材料です。
Step 3：人間が判断する
AIの出力をもとに、チームで判断します。
確認すべき観点は次のとおりです。
- 自社のセキュリティ要件に合うか
- 運用できる人員がいるか
- 障害時に対応できるか
- コストは許容範囲か
- 将来の拡張に耐えられるか
- 今やるべき判断か、後回しにできるか
ここで重要なのは、正解を選ぶことではなく、現時点の制約下で妥当な判断をすることです。
Step 4：AIにADRの下書きを作らせる
判断が固まったら、AIにADRの下書きを作らせます。
以下の情報をもとに、ADRの下書きをMarkdownで作成してください。
決定:
- 社内ドキュメント検索にRAG構成を採用する
背景:
- キーワード検索では目的の情報にたどり着きにくい
- 社内文書をもとに自然文で回答したい
- 社外秘情報を扱うため、権限管理とログ管理が必要
検討した選択肢:
- 既存検索の改善
- RAG構成
- 全文検索エンジンのみ
- ファインチューニング
採用理由:
- 既存文書を活用しやすい
- 多くのケースでは、モデル再学習を伴うファインチューニングより初期検証を始めやすい
- 参照元文書を返す設計にすれば、回答根拠を提示しやすい
懸念:
- 検索精度に依存する
- 誤回答対策が必要
- ユーザーが閲覧権限を持つ文書だけを検索対象にする設計が必要である
- 回答生成前に文書権限チェックを行う必要がある
形式:
- Status
- Context
- Options
- Decision
- Reason
- Consequences
- Review Date
Step 5：AIにレビューさせる
最後に、AIにADRをレビューさせます。
以下のADRをレビューしてください。
観点:
- 背景と決定が対応しているか
- 選択肢の比較が偏っていないか
- デメリットが十分に書かれているか
- 将来見直す条件が明確か
- 意思決定の責任が曖昧になっていないか
出力:
- 良い点
- 不足している点
- 修正案
AIによるレビューは、抜け漏れ検出に有効です。
ただし、最終承認はチーム内の責任者が行います。
具体例：RAG構成を採用するADR
以下は、AI活用を前提にしたADRのサンプルです。
# ADR-001: 社内ドキュメント検索にRAG構成を採用する
## Status
Accepted
## Context
現在、社内ドキュメントは複数のストレージに分散しており、必要な情報を探すのに時間がかかっている。
既存のキーワード検索では、利用者が正しい検索語を知らない場合に目的の情報へ到達しづらい。また、問い合わせ対応の属人化も課題になっている。
一方で、社内文書には機密情報が含まれるため、回答生成にLLMを使う場合は、権限管理、ログ管理、回答根拠の提示が必要になる。
特にRAG構成では、検索時点でユーザーの閲覧権限を反映し、許可された文書だけを回答生成に利用する設計が重要になる。
## Options
### Option 1: 既存検索を改善する
- メリット:
- 導入コストが低い
- 現行運用を大きく変えなくてよい
- デメリット:
- 自然文での質問に対応しづらい
- 回答要約や横断的な情報整理は難しい
### Option 2: RAG構成を導入する
- メリット:
- 既存文書を活用しやすい
- 参照元文書を返す設計にすれば、回答根拠を提示しやすい
- 多くのケースでは、モデル再学習を伴うファインチューニングより初期検証を始めやすい
- デメリット:
- 検索精度に回答品質が依存する
- 権限管理を誤ると情報漏えいリスクがある
- ユーザーが閲覧権限を持つ文書だけを検索対象にする設計が必要である
- 回答生成前に文書権限チェックを行う必要がある
- 誤回答への対策が必要
### Option 3: ファインチューニングを行う
- メリット:
- 特定業務に特化した回答が期待できる
- デメリット:
- 学習データの整備コストが高い
- 最新文書の反映に運用負荷がかかる
- 回答根拠の提示が難しい場合がある
## Decision
社内ドキュメント検索には、RAG構成を採用する。
ただし、初期リリースでは全社公開ではなく、限定された部門・文書範囲でPoCを行う。
回答には参照元文書を表示し、ユーザーが根拠を確認できるようにする。
## Reason
RAG構成は、既存文書を活用しながら自然文での質問応答を実現しやすい。
また、参照元文書を返す設計にすれば、利用者が回答の妥当性を確認しやすい。
ただし、実際の品質は検索精度、文書の鮮度、引用表示の実装、権限管理に依存する。
ファインチューニングは将来的な選択肢として残すが、初期段階では学習データ整備、評価、継続的な更新にかかる運用負荷が大きい。
既存検索の改善のみでは、問い合わせ対応の効率化という目的に対して効果が限定的である。
## Consequences
### Positive
- 利用者が自然文で社内文書を検索できる
- 回答と参照元をセットで確認できる
- 問い合わせ対応の一次回答を効率化できる
### Negative
- 検索インデックスの品質管理が必要になる
- 権限管理と文書アクセス制御の設計が必要になる
- ユーザーが閲覧権限を持つ文書だけを検索・回答生成に利用する制御が必要になる
- 誤回答や古い情報を提示するリスクがある
### Neutral
- 文書管理ルールの見直しが必要になる
- 回答品質を継続的に評価する運用が必要になる
## Review Date
2026-09-30
## References
- 社内問い合わせ件数レポート
- 情報セキュリティ要件
- RAG PoC計画書
このように書いておくと、後から見た人が「なぜRAGを採用したのか」「何をリスクとして受け入れたのか」を理解できます。
AIをADR運用に組み込むポイント
AIとADRをうまく組み合わせるには、次の運用が有効です。
| タイミング | AIの使い方 |
|---|---|
| 設計前 | 論点の洗い出し |
| 技術選定時 | 選択肢の比較 |
| レビュー前 | ADRの下書き作成 |
| レビュー時 | 抜け漏れチェック |
| 実装後 | 実態との差分確認 |
| 振り返り時 | 変更が必要なADRの洗い出し |
特におすすめなのは、Pull RequestとADRを紐づける運用です。
docs/adr/
001-use-rag-for-internal-search.md
002-use-managed-vector-database.md
003-keep-human-review-for-ai-answers.md
Gitで管理しておけば、コード変更と設計判断の履歴を近い場所に残せます。adr-toolsのように、ADRをコマンドラインで管理するためのツールも存在します。(GitHub)
よくある落とし穴と対策
落とし穴1：AIの出力をそのままADRに貼る
AIの文章は整って見えます。
しかし、整っていることと正しいことは別です。
対策
- AIの出力は下書きとして扱う
- 自社の制約を必ず追記する
- 判断者・レビュー者を明確にする
- 不明点は「不明」と書く
落とし穴2：メリットばかり書く
ADRは稟議資料や宣伝資料ではありません。
採用した技術の良い点だけを書くと、後から判断を見直せなくなります。
対策
- デメリットを必ず書く
- 採用しなかった選択肢も書く
- 「何を諦めたか」を明記する
落とし穴3：大きすぎるADRを書く
1つのADRに複数の判断を詰め込むと、後で読みにくくなります。
悪い例：
AI検索基盤、クラウド、DB、認証、監視方式をまとめて決める
良い例：
ADR-001: 社内検索にRAG構成を採用する
ADR-002: ベクトルDBにマネージドサービスを利用する
ADR-003: 回答生成前に文書権限チェックを行う
ADR-004: AI回答に参照元リンクを表示する
対策
- 1 ADR = 1つの意思決定にする
- 迷ったら分割する
- 後から置き換えやすい粒度にする
落とし穴4：一度書いたADRを更新し続ける
ADRは、意思決定の履歴です。
過去の判断を直接書き換え続けると、当時の判断理由が消えてしまいます。
対策
- 判断が変わったら新しいADRを作る
- 古いADRはDeprecatedやSupersededにする
- 新旧ADRを相互リンクする
例：
## Status
Superseded by ADR-007
落とし穴5：AI利用の責任範囲が曖昧
「AIがそう言ったから」という理由では、設計判断の説明になりません。
対策
- ADR内にAI利用の有無を書く
- AIが出した案を誰がレビューしたか残す
- 最終判断者を明確にする
- 重要判断では人間のレビューを必須にする
記載例：
## AI Usage
本ADRの初期案作成に生成AIを使用した。
最終判断はアーキテクトおよび開発チームでレビューし、承認した。
まとめと次のステップ
AI時代の設計では、答えを速く出すことだけでなく、なぜその答えを選んだのかを残すことが重要です。
この記事の要点は次のとおりです。
- ADRは、アーキテクチャ上の意思決定を残す軽量なドキュメント
- AIは選択肢の洗い出しや下書き作成に有効
- 最終判断は人間が責任を持つ
- ADRには、背景・選択肢・決定・理由・結果を書く
- AIの出力をそのまま採用せず、制約やリスクを明記する
- 判断が変わったら、過去ADRを書き換えるのではなく新しいADRを作る
まずは、次の1つだけでも始めると効果があります。
次に大きな技術選定をするとき、ADRを1枚だけ書いてみる
AIで設計案を出し、ADRで判断を残す。
この組み合わせは、開発スピードと説明責任を両立するための現実的なアプローチです。
参考リンク
- Thoughtworks: Lightweight Architecture Decision Records (Thoughtworks)
- Microsoft: Maintain an architecture decision record (Microsoft Learn)
- MADR: Markdown Architectural Decision Records (Architectural Decision Records)
- adr-tools: Command-line tools for working with Architecture Decision Records (GitHub)
免責事項: 本記事は筆者が確認した時点の情報に基づく参考情報であり、正確性・完全性・最新性を保証するものではありません。利用により生じたいかなる損害についても、筆者は責任を負いません。