ADRをAIで下書きするプロンプト｜選択肢・判断理由・影響まで残す実務テンプレート
このプロンプトは、システム構成や技術選定のメモから、ADR（Architecture Decision Record：アーキテクチャ意思決定記録）の下書きを作るためのものです。
設計判断を文書に残したい開発者、テックリード、プロジェクトマネージャーに向いています。狙う出力は、Markdown形式のADRです。
重要なのは、AIに技術選定そのものを任せることではありません。人が示した事実と判断材料を、AIに「背景・候補・決定・影響」へ整理させます。
この記事で分かることは次のとおりです。
- コピペして使えるADR作成プロンプト
- 入力時に変える項目と、固定したいルール
- AIが根拠や決定を補ってしまう失敗の防ぎ方
- レビューしやすいADRへ整える追加指示
ADR作成プロンプトの用途と完成イメージ
ADRは、採用技術の説明書ではなく「なぜその判断をしたか」を将来のメンバーへ残す記録です。
ADRの公開情報をまとめるArchitectural Decision Recordsでは、ADRを、単一のアーキテクチャ上の決定とその理由を記録するものと説明しています。複数のADRを蓄積すると、プロジェクトの意思決定履歴になります。
たとえば「データベースにPostgreSQLを使う」とだけ書いても、後から参加した人には判断材料が見えません。ADRでは、少なくとも次の流れを残します。
- どの要件や問題に対応する必要があったか
- どの選択肢を比較したか
- 何を採用し、何を採用しなかったか
- 採用によって得るものと、引き受ける制約は何か
AWS Prescriptive GuidanceのADRプロセスも、最低限の要素としてコンテキスト、決定、結果を挙げています。また、構造、非機能要件、依存関係、APIなどのインターフェース、ライブラリや開発手法の選択は、ADRの対象になり得ます。
AIに任せる範囲
AIが得意なのは、散在した検討メモを共通の型へ整理する作業です。
- 会議メモから背景と制約を抽出する
- 候補ごとの長所、短所、リスクを並べ直す
- 決定事項と未決事項を分離する
- 用語や見出しを統一する
- 根拠が足りない箇所を質問として返す
一方、採用技術の最終決定、セキュリティ要件の承認、費用や運用負荷の評価は、人が担当します。
ここがポイント: AIには「不足情報を推測して完成させる」のではなく、「不足を明示した下書きを作る」役割を与えます。
コピペ用ADR作成プロンプト
次のテンプレートでは、判断材料が不足している場合にADRを完成扱いにせず、確認事項を先に出させます。会議メモや設計メモを {入力資料} に貼り付けて使ってください。
あなたは、ソフトウェア設計の意思決定を文書化する編集者です。
以下の入力資料を基に、1件のArchitecture Decision Record（ADR）をMarkdownで作成してください。
# 目的
設計判断について、背景、比較した選択肢、決定理由、結果を、後から参加するメンバーにも追跡できる形で残す。
# 入力情報
- 対象システム: {対象システム}
- 決定したい問い: {決定したい問い}
- 現在の状態・問題: {現在の状態・問題}
- 機能要件: {機能要件}
- 非機能要件: {性能・可用性・セキュリティ・運用など}
- 制約: {予算・納期・既存技術・契約・人員など}
- 比較した選択肢: {選択肢と分かっている評価}
- 決定内容: {決定済みなら記入／未決定なら「未決定」}
- 判断基準: {優先順位を含む評価基準}
- 関係者: {決定者・レビュー担当者}
- 関連資料: {チケット・仕様書・既存ADRなど}
- 入力資料:
{会議メモや設計メモを貼り付ける}
# 作成ルール
1. 入力にない事実、数値、合意、評価、決定理由を推測しない。
2. 情報不足が決定内容や比較結果に影響する場合は、ADR本文を作る前に「確認が必要な項目」を箇条書きで示す。
3. 決定が未確定の場合、ステータスを「Proposed」とし、AIが案を勝手に採用しない。
4. 選択肢ごとに、利点、欠点、リスク、制約との適合を整理する。
5. 採用しなかった選択肢にも、見送った理由を書く。根拠がなければ「要確認」とする。
6. 結果には、好ましい影響だけでなく、運用負荷、移行、セキュリティ、費用、将来の変更余地も含める。
7. 決定事項は曖昧な推奨表現ではなく、実行内容が分かる文にする。
8. 1つのADRには1つの主要な決定だけを記録する。複数の決定が混在する場合は分割案を示す。
9. 簡潔な日本語で書き、入力資料の重複は統合する。
# 出力形式
## {ADR番号}: {決定を表す短いタイトル}
- ステータス: [Proposed / Accepted / Rejected / Superseded]
- 日付: {YYYY-MM-DD}
- 決定者: {氏名または役割}
- レビュー担当: {氏名または役割}
### コンテキスト
{問題、要件、制約、決定が必要な理由}
### 判断基準
- {基準1}
- {基準2}
### 検討した選択肢
#### 選択肢A: {名称}
- 利点:
- 欠点:
- リスク:
- 制約との適合:
#### 選択肢B: {名称}
- 利点:
- 欠点:
- リスク:
- 制約との適合:
### 決定
{採用する選択肢と、チームが実行する内容}
### 決定理由
{判断基準に照らして採用した理由と、他案を見送った理由}
### 結果
#### 好ましい影響
- {影響}
#### 受け入れる不利益・リスク
- {影響}
#### 必要な対応
- {移行、検証、監視、教育、費用確認など}
### 確認方法
{この決定が実装・運用で守られていると確認する方法}
### 関連資料
- {URLまたは文書名}
### 未解決事項
- {未決事項。なければ「なし」}
# 最終確認
ADRの後に、次の3点を出力してください。
- 入力から確認できなかった記述
- 人がレビューすべき判断
- 別ADRへ分割した方がよい論点
入力時に変える部分
出力品質を最も左右するのは、製品名や技術名より「判断基準と制約」です。 候補だけを渡すと、AIは一般的な長所と短所を並べるだけになりやすいためです。
最低限埋めたい項目
まず、次の5項目を具体化します。
{決定したい問い}：何を決めるADRなのか{現在の状態・問題}：なぜ今、決定が必要なのか{制約}：変更できない条件は何か{比較した選択肢}：実際に検討した候補は何か{判断基準}：何を優先して比較するのか
たとえば「メッセージキューを決める」では範囲が広すぎます。「注文確定後の非同期処理に使うメッセージ基盤を、既存のAWS運用体制と月額予算の範囲で決める」と書けば、対象と制約が見えます。
判断基準には、優先順位も添えます。
判断基準:
1. 障害時に注文データを失わないこと
2. 既存の監視・権限管理へ統合できること
3. 3名の運用担当者で保守できること
4. 月額費用が予算上限を超えないこと
固定した方がよい条件
案件ごとに変えず、チームの共通ルールとして残したい指示もあります。
- 入力にない事実を補わない
- 未決定ならステータスを
Proposedにする - 採用しなかった案の理由も残す
- 不利益や追加作業を省略しない
- 1件のADRで1つの主要判断を扱う
- 人によるレビュー項目を最後に出す
ADRにはNygard形式やMADRなど複数の型があります。ADR Templatesでは、Nygard形式の基本要素としてタイトル、ステータス、コンテキスト、決定、結果を紹介し、MADRでは比較候補の長所・短所も重視しています。既存のADRがあるチームでは、新しい形式を持ち込まず、見出し名とステータス値を既存文書に合わせてください。
失敗しやすい指示と改善例
最も危険な失敗は、AIが不足情報を自然な文章で埋め、未確認の理由をチームの合意に見せてしまうことです。
NG例：題名だけで完成させる
Redisを採用するADRを書いてください。
メリットとデメリットも含めてください。
この指示では、何にRedisを使うのか、比較対象は何か、誰が決めたのかが分かりません。それでもAIが文章を完成させれば、一般論がプロジェクト固有の判断理由に混ざります。
改善例：事実と不足情報を分ける
セッション保存先を決めるADRの下書きを作成してください。
確認済みの事実:
- Webアプリは3台のサーバーで稼働する
- 現在は各サーバーのローカルメモリにセッションを保存している
- ロードバランサーの固定セッションを廃止したい
- 候補はRedisとデータベース
- 判断基準は、可用性、運用負荷、応答時間、費用
- 採用案はまだ決まっていない
制約:
- 入力にない性能値や費用を作らない
- ステータスはProposedにする
- 候補ごとの未確認事項を明示する
- 最後に、決定前に計測・確認すべき項目を出す
改善点は明確です。
- 対象を「セッション保存先」に限定した
- 確認済みの事実を分離した
- 未決定であることを明記した
- 比較基準を指定した
- AIに不足情報を質問へ変換させた
NG例：メリットだけを求める
採用理由を説得力のある文章にしてください。
「説得力」を優先すると、不利益が弱く書かれるおそれがあります。ADRは採用案の宣伝資料ではありません。
次のように、判断を検証できる形へ変えます。
採用案を正当化するのではなく、判断基準との対応を示してください。
採用案の欠点、受け入れるリスク、運用上必要になる追加作業も、利点と同じ粒度で記載してください。
根拠が入力にない評価には「要確認」と付けてください。
出力を安定させる3つのコツ
形式、根拠の境界、レビュー手順を同時に指定すると、ADRをチームで確認しやすくなります。
1. 出力形式を既存ADRに合わせる
チームに既存テンプレートがある場合は、その空のテンプレートか、機密情報を除いた過去のADRを入力に加えます。
以下の見出し順、ステータス値、箇条書き記号を変更しないでください。
不足する項目は削除せず「要確認」と記載してください。
これにより、AIが独自の見出しを増やして意思決定ログの形式を乱すのを防げます。
2. 事実・評価・未確認を分ける
比較表が整っていても、評価の根拠が曖昧なら決定には使えません。下書き後に、記述の出どころを分類させます。
ADR内の主要な記述を次の3種類に分類してください。
- 入力資料で確認できる事実
- チームの判断・評価
- 根拠がなく確認を要する記述
「確認を要する記述」には、確認方法と担当に適した役割も提案してください。
AIの一般知識を使った補足が必要な場合も、そのまま決定理由にはしません。公式仕様、計測結果、見積もりなどで確認する対象として扱います。
3. 決定後の確認方法まで書く
ADRは作成して終わりではありません。決定がコードや運用へ反映されたかを確かめる方法を加えます。
- 依存ライブラリをCIで検査する
- 構成ファイルをコードレビューで確認する
- 負荷試験の合格条件をチケットへ記録する
- 監視項目とアラート設定を運用手順へ追加する
- 関連するPull RequestからADRへリンクする
AWSのベストプラクティスでは、ADRをチームが参照できる中央の場所へ保存し、履歴を維持することが推奨されています。受理済みの判断を変更するときは、元の記録を消して書き換えるのではなく、新しいADRを作り、旧ADRを Superseded として残す運用が示されています（AWS Prescriptive Guidance）。
活用例：会議メモからADRレビュー案を作る
実務では、設計会議の直後に使うと、合意事項と未決事項を分けやすくなります。
入力資料として、次の情報を渡します。
- 会議で確認した問題と要件
- 発言者ではなく、合意された内容
- 比較した候補と評価根拠
- 決まったこと、決まらなかったこと
- 次回までの調査項目と担当
ただし、会議メモに個人情報、認証情報、非公開の顧客情報が含まれる場合は、利用するAIサービスのデータ取扱方針と組織の規程を確認し、必要な情報だけを入力してください。
下書きができたら、次の追加プロンプトでレビューできます。
作成したADRをレビューしてください。
次の観点ごとに、問題箇所、問題である理由、修正案を出してください。
- 1件のADRに複数の主要判断が混在していないか
- コンテキストだけを読んで、決定が必要な理由を理解できるか
- 判断基準と決定理由が対応しているか
- 採用しなかった選択肢の理由が記録されているか
- 不利益、移行作業、運用負荷が抜けていないか
- 入力にない事実や合意を断定していないか
- 決定を実装後に確認する方法があるか
ADR本文はまだ書き換えず、重大度を「必須」「推奨」「軽微」に分けて指摘してください。
先に指摘だけを出させるのがポイントです。AIが文面を自動修正すると、レビュー前の合意内容まで変わる可能性があります。
ADR公開前のチェックリスト
最後は、人が次の項目を確認します。
- [ ] ADRの対象となる決定が1つに絞られている
- [ ] 決定が必要になった背景と制約が具体的である
- [ ] 実際に検討した選択肢だけが記録されている
- [ ] 判断基準に優先順位がある
- [ ] 採用案の不利益と追加作業が書かれている
- [ ] 未確認の数値や合意をAIが補っていない
- [ ] ステータス、決定者、日付が正しい
- [ ] 関連チケットや仕様書へたどれる
- [ ] 実装・運用で決定を確認する方法がある
- [ ] 機密情報や認証情報が含まれていない
AIで短縮すべきなのは、文章を整える時間です。比較、承認、責任まで自動化してはいけません。 次にADRを作るときは、まず「決定したい問い」「制約」「判断基準」の3点を埋め、情報が足りなければ Accepted にせず Proposed のままレビューへ回してください。