AIにADRのドラフトを書かせる｜設計判断の「なぜ」を残す型
新しく入った後輩から、ふいに聞かれました。「このサービス、なんでキューを挟む構成にしたんですか？ 直接呼んだほうが簡単そうに見えて」。
半年前、自分も会議に出ていた判断です。たしか、いろいろ比べて決めた。でも、何と何を比べて、何が決め手だったのかが出てこない。チャットをさかのぼっても、結論の一言しか残っていない。
ここで自分を責めなくて大丈夫です。決めた理由は、決めた瞬間がいちばん当たり前に見えるので、わざわざ書こうとは思わないものです。そして、忙しい現場で一番後回しになるのが、この「なぜ」を書く作業でもあります。
この記事では、その後回しになりがちな記録を、AIに下書きしてもらって残す方法を整理します。形式は ADR（Architecture Decision Record＝設計判断の記録） という、1つの判断を1枚の短い文書に残すやり方です。
結論：順番は3つです。①集める——会議メモ、チャット、比較表など、判断のときに実際に出ていた材料をAIに渡す。②下書き——AIにはADRの型に流し込ませ、材料に書かれていない理由は作らせず、空欄と質問で返させる。③残す——人が理由を確かめて埋め、チームで確認してからリポジトリに置く。古くなった判断は消さず、新しいADRで置き換えた印をつける。
覚え方は 集める → 下書き → 残す。AIに任せるのは「形にする」ところまで。「なぜ」を決めるのは、判断した人です。
今日ぜんぶやる必要はありません。直近で決めたことを1つだけ選んで、そのときのチャットをAIに渡して下書きしてもらう。それだけで、半年後の自分と後輩が助かる1枚ができます。
何が起きているのか——判断は残るのに、理由が消えていく
打ち手の前に、なぜ設計判断の理由は残りにくいのかを整理します。
1つ目は、結論だけがコードに残ること。キューを使った、このライブラリを選んだ、テーブルを分けた。「何をしたか」はコードを読めば分かります。でも、「ほかに何を検討して、なぜそれを選ばなかったか」は、コードのどこにも書かれていません。
2つ目は、理由が散らばっていること。比較は会議で話し、補足はチャットで流れ、数字は誰かの手元の表にある。材料は全部どこかにあるのに、1か所にまとまっていないので、あとから拾い集めるのが大変です。
3つ目は、書くのが重く感じること。設計書を丸ごと更新しようとすると、半日仕事になります。だから「落ち着いたら書こう」となり、落ち着く日は来ません（仕様書・設計書のドラフトをAIで作る｜叩き台の作り方と注意点）。
ここで役に立つのがADRです。よく使われる型は、タイトル・ステータス（提案中／採用／廃止／置き換え済みなど）・背景（どんな状況と制約があったか）・決定（何を選んだか）・結果（その選択で何が良くなり、何を引き受けたか）の5つ程度。1つの判断につき1枚、短くていいのが特徴です。検討した他の案を書く欄を足す型もあります。
そして、AIはこの「散らばった材料を型に流し込む」作業がとても得意です。ただし、得意すぎるがゆえの落とし穴もあります。次の具体例で見てみます。
具体例——つい、こうなりがちという形
どれも「早く記録を残したい」という前向きな気持ちから生まれます。心当たりのある行があれば、そこだけ見れば十分です。
- 「キューを使う構成にしたADRを書いて」とだけ頼む：AIは、それらしい背景と理由をすらすら書いてくれます。でもそれは、一般的にキューが選ばれる理由であって、あなたのチームが選んだ理由とは限りません。読み返すと納得できる分、間違いに気づきにくいのが困るところです。
- 検討していない代替案が並んでいる：「他の選択肢」の欄に、会議で一度も話題に出なかった案と、その却下理由が書かれている。後から読んだ人は、それも比べたのだと受け取ります（AIのハルシネーションの見抜き方｜開発現場で気づく型）。
- 「結果」に良いことしか書かれていない：キューを入れたことで、処理が非同期になって追いにくくなる、運用の監視が1つ増える。そういう「引き受けたもの」が抜けていると、あとで困ったときに「知らなかった」になります。
- 数字がどこから来たのか分からない：「処理時間が約40%短縮される見込み」。材料のどこにもない数字が、判断の根拠として書かれていることがあります。
- チャットをそのまま貼って相談する：社外秘の顧客名や、接続先の情報が混じったまま渡してしまう（社内データをAIに渡す前の線引き｜情報漏えいを防ぐ型）。
- 古いADRを書き換えてしまう：方針が変わったので、以前のADRの中身を新しい内容に上書きする。すると、「以前はなぜ別のやり方だったのか」が消えます。
影響——理由が残らないと、同じ議論をもう一度することになる
急いで全部を記録しないと大変、という話ではありません。ただ、後から効いてくる種類の問題なので、書いておきます。
- 同じ議論を何度もくり返す：新しいメンバーが「直接呼べばいいのでは」と言うたびに、ゼロから比べ直す。前回の結論にたどり着くまで、同じ時間がかかります。
- 理由を知らずに、前提を壊してしまう：キューを挟んだのは、外部APIの流量制限に合わせるためだった。それを知らずに「簡単にしよう」と外すと、本番でまとめて弾かれる、ということが起きえます。
- 間違った理由が「公式の記録」になる：AIが書いたもっともらしい理由がそのまま残ると、次の判断がその誤った前提の上に積み上がります。記録がないより、少し厄介です。
- 判断した人に質問が集まり続ける：理由が頭の中にしかないと、その人がいないと先に進めない状態になります。
少し安心できる話をすると、この領域は小さく始められます。立派な設計書は要りません。1つの判断につき1枚、材料を集めてAIに下書きしてもらい、人が理由を確かめる。それだけで、半年後の「なんでだっけ」はかなり減ります。
明日からやること（集める・下書き・残す）
上から順に、小さく始められます。今日は①だけでも構いません。
1. 集める——判断のときに「実際に出ていた材料」を渡す
AIに頼む前に、そのとき本当に話されたことを手元に集めます。ここが、AIに理由を作らせないためのいちばん大事な準備です。
- 会議メモ、チャットのやりとり、比較表、見積もりなど、判断の場に出ていたものを集める。完璧に揃っていなくて大丈夫です。断片でも、AIが整理してくれます。
- 決めたことを、自分の言葉で1行書き添える。「外部APIの呼び出しはキューを挟んで非同期にする」のように。結論がはっきりしていると、下書きがぶれません。
- 覚えている範囲で、比べた案と、選ばなかった理由をメモする。うろ覚えなら「うろ覚え」と書いておけば十分です。
- 秘密の情報は伏せてから渡す。顧客名、社内の接続先、個人名は、「顧客A」「社内API」のように置き換えてから渡します。社内でAIに渡してよい範囲のルールがあれば、それに従います。
- 判断した日付と、関わった人（役割でよい）を書く。あとで「誰に聞けばいいか」が分かるようにするためです。
2. 下書き——型に流し込ませ、足りない理由は空欄で返させる
材料が集まったら、AIにADRの型で下書きしてもらいます。ポイントは、「材料にないことは書かないで」と最初に伝えることです。
- 型を指定する。タイトル・ステータス・背景・決定・結果（良くなること／引き受けること）・検討した他の案。チームで決まった型があれば、それを渡します。
- 材料にない理由・数字・代替案は、書かずに「要確認」として空欄にさせる。AIは空欄を埋めたがるので、「推測で埋めないで」と言葉にして頼むのがコツです。
- 最後に「確かめたい質問」を出させる。「この案を選ばなかった理由は材料にありません。何でしたか？」のように、AIに聞き手になってもらうと、自分の頭の中にあった理由が出てきやすくなります（AIを設計の壁打ち相手にする｜問いの立て方の型）。
- 「結果」には、引き受けたものも書かせる。運用の手間が増える、処理が追いにくくなる、など。良いことだけの記録は、あとで役に立ちにくいからです。
- 1枚は短く。長くなりそうなら、それは判断が2つ以上混ざっているサインです。1つの判断につき1枚に分けてもらいます。
3. 残す——人が理由を確かめ、チームで見てから置く
下書きができたら、ここからは人の仕事です。
- 空欄と質問に、自分の言葉で答える。思い出せないところは「当時の理由は不明。現時点ではこう考えている」と正直に書いて構いません。分からないことを分からないと書いた記録は、作り話より何倍も役に立ちます。
- 書かれた理由を、材料と1つずつ照らし合わせる。材料に出てこない理由や数字が混じっていないか。読んで納得できる文ほど、一度立ち止まって見ます（AIのアーキテクチャ案を鵜呑みにしない｜比較の型）。
- 関わった人に見てもらう。プルリクエストでADRを出して、判断に関わった人のレビューを通してから採用にすると、記録と実際の判断がずれにくくなります（AIにコミットメッセージとPR説明を書かせる｜レビューが楽になる型）。
- コードの近くに置く。リポジトリの中に
docs/adr/のような置き場を作り、番号と短い名前をつけて並べておくと、あとから探しやすくなります。 - 古いADRは消さず、置き換えの印をつける。方針が変わったら新しいADRを書き、古いほうのステータスを「置き換え済み」にして、新しいADRへのリンクを添えます。「以前はなぜそうだったか」も、大事な記録です。
AIに頼むときのプロンプト（コピーして使えます）
何も言わないと、AIはもっともらしい理由で空欄を埋めてしまいます。材料にないことは書かないこと、分からないところは質問で返すことを、最初に伝えるのがコツです。
設計判断を記録するADR（Architecture Decision Record）の下書きをお願いします。
①下の材料だけをもとに、次の型で書いてください：タイトル／ステータス（提案中）／背景（状況と制約）／決定／結果（良くなること・引き受けること）／検討した他の案と選ばなかった理由。
②材料に書かれていない理由・数字・代替案は、推測で埋めずに「要確認」としてください。一般論で補うこともしないでください。
③「結果」には、この決定で増える手間や制約も必ず書いてください。材料から読み取れなければ「要確認」で構いません。
④最後に、空欄を埋めるために私に聞きたい質問を、重要な順に5つまで挙げてください。
⑤各記述が材料のどこに基づくかを、短く添えてください。
決めたこと（1行）：（ ） 判断した日付・関わった人の役割：（ ） 材料（会議メモ・チャット・比較表など。秘密の値は伏せる）：（ ）
質問に答えたあとは、こう続けます。
質問への答えを下に書きます。これを反映して、ADRを仕上げてください。私の答えにも材料にもないことは、引き続き「要確認」のままにしてください。
⑤の「材料のどこに基づくか」が効きます。根拠を示せない文が、そのまま目で見て分かるようになります。
出てきた下書きは、次の3点だけ自分の目で確かめます。（1）材料にない理由・数字・代替案が混じっていないか、（2）「結果」に引き受けたものが書かれているか、（3）「要確認」を、推測のまま埋めていないか。
ADRをAIと作るチェックリスト（コピーして使えます）
全部に○が要るわけではありません。気になった行だけで十分です。
① 集める
- 会議メモ・チャット・比較表など、判断のときの材料を集めたか
- 決めたことを自分の言葉で1行書いたか
- 比べた案と、選ばなかった理由を覚えている範囲でメモしたか
- 顧客名・接続先・個人名などは伏せてから渡したか
- 判断した日付と、関わった人の役割を書いたか
② 下書き
- ADRの型（背景・決定・結果など）を指定したか
- 材料にない理由・数字・代替案は「要確認」にするよう頼んだか
- 最後に、確かめたい質問を出してもらったか
- 「結果」に、引き受ける手間や制約も書いてもらったか
- 1枚に判断が1つだけになっているか
③ 残す
- 空欄と質問に、自分の言葉で答えたか（分からないことは分からないと書いたか）
- 書かれた理由と数字を、材料と照らし合わせたか
- 判断に関わった人にレビューしてもらったか
- リポジトリの決まった場所に、番号つきで置いたか
- 方針が変わったとき、古いADRを消さずに「置き換え済み」にしたか
この記事のまとめ
設計判断の理由が残らないのは、怠けているからではなく、決めた瞬間は理由が当たり前に見えて、書く作業がいちばん後回しになりやすいからです。
やることは3つ。①集める——判断のときに実際に出ていた材料を集めて渡す。②下書き——AIにADRの型へ流し込ませ、材料にない理由は空欄と質問で返させる。③残す——人が理由を確かめて埋め、レビューを通してリポジトリに置き、古い判断は消さずに置き換える。
AIに頼むときは、「材料にないことは推測で埋めないで」と一言添える。それだけで、もっともらしい作り話が記録に紛れ込むのを防げます。
後輩に「なんでですか」と聞かれて答えられなかったとき、少し恥ずかしい気持ちになったかもしれません。でもそれは、あなたが判断を軽く扱ったからではなく、理由を書き残す仕組みがなかっただけです。
ADRは、立派な文書である必要はありません。材料を集めて、AIに形にしてもらい、自分の言葉で理由を確かめる。その1枚が、次に同じ問いにぶつかった誰かの時間を、まるごと助けます。
今日は、直近で決めたことを1つ選んで、そのときのチャットをAIに渡してみる。返ってきた「要確認」の空欄に答えていくうちに、あのとき自分たちがちゃんと考えていたことが、きっと思い出せるはずです。
よければ、こちらも
- 案を比べるときはAIのアーキテクチャ案を鵜呑みにしない｜比較の型
- 判断の前の壁打ちはAIを設計の壁打ち相手にする｜問いの立て方の型
- ライブラリを選ぶときはAIの技術選定・ライブラリ比較の落とし穴｜任せる前の確認
- 設計書全体の叩き台は仕様書・設計書のドラフトをAIで作る｜叩き台の作り方と注意点
- 理由が残っていない古いコードにはレガシーコードの仕様をAIに読み解かせる｜仕様復元の進め方
- コードの中の「なぜ」はAIにdocstring・コメントを書かせる｜後で嘘にならない書き方
- もっともらしい誤りへの備えはAIのハルシネーションの見抜き方｜開発現場で気づく型