1ページで決定を残す（ADR）：人のためにも、AIのためにも

コードを書くチームで働く人なら誰でも、新人の方でも、AIエージェントに作業を任せている方でも読めます。ソフトウェア設計の知識は不要です。用語にはどれも身近なたとえを添えています。計算の部分は印をつけてあるので、不要なら読み飛ばせます。

数字は公開情報から取っており、末尾に一覧があります。「例」と書いたものはこの記事のために作った例で、実在の人物や会社には触れていません。AIエージェントが文書を内部でどう読み、どう使うのかは、まだ誰にも完全には分かっていません。以下のたとえは覚えやすくするための補助です。AIに関する助言は実践の整理であり、対照実験の結果ではありません。

---

まず要点#

• プロジェクトで一番難しいのは、コードそのものよりコードの裏にある理由であることが多いです。理由は一部の人の頭の中にあり、その人たちと一緒にいなくなります。
• ADR（architecture decision record、決定記録）は、決定を1つ、背景、決定、結果、状態とともに残す短い1ページです。2011年にMichael Nygardが提案し、長さは1〜2ページを勧めています。
• 理由を知らない新人には、2つの道しかありません。理解せずに受け入れるか、結果を知らずに覆すかです。どちらも良くありません。Nygardはまさにこの2つを挙げています。
• AIエージェントも似た状況になりえます。「遠回り」なコードを見て整理してしまい、その遠回りが意図的だったことを知りません。エージェント向けの指示ファイルからリンクされたADRは、修正の前に確認できる場所になります。
• よいADRは1ページで足ります。未来の読み手に向けて、却下した案と、受け入れた代償を書きます。貼って使えるテンプレートも載せました。
• ADRはすべての変更に必要な儀式ではありません。小さくて簡単に戻せる決定には不要です。また、状態を更新する人と、読む人がいてはじめて役に立ちます。

---

むずかしい言葉をやさしく#

---

1. まずイメージ：レシピのメモ#

レシピ帳のあるレストランを思い浮かべてください。スープのページには「塩は入れない。最後にナンプラーで味を整える」とあります。入ったばかりの調理補助の人は、薄いと感じて塩を足します。その日、塩を控えているお客さまがスープを注文します。誰にも悪意はありません。レシピ帳に足りなかったのは1行、「なぜ塩を入れないか」だけです。

では、その1行があるとします。「塩は入れない。この料理は食事制限のあるお客さまにも出すため。塩はお客さまが卓上で足す」。補助の人は読んで納得できますし、お店の方針が変われば、直す場所もあります。

ADRは、そのメモのコード版です。そしてAIエージェントがリポジトリに入ってきたとき、「塩を足す」前に読めるメモになります。

ポイント： 残すべきものは分厚い本ではなく、覚えておく価値のある決定ごとの理由です。誰かが読める短さにします。

---

2. ADRとは何か：出典から#

2.1 Michael Nygardの原典（2011年）#

Michael Nygardは、2011年11月15日にCognitectのブログに載せた「Documenting Architecture Decisions」で、アーキテクチャの決定にはしばしば理由の記録がないと書いています。新しくプロジェクトに入った人には道が2つしかありません。理解せずに決定を受け入れるか、結果を知らずに覆すかです。どちらもプロジェクトを傷つけうるし、説明のない決定が多すぎるとチーム全体が何も変えるのを怖がるようになる、と述べています。

各記録は次の5つの部分から成る、と提案しています。

• タイトル：短い名詞句。
• 背景：決定に働く力（技術、政治、社会、プロジェクト固有）を、判断を入れずに事実として書く。
• 決定：完全な文、能動態、「私たちは〜します」で始める。
• 状態：関係者が合意するまでは「提案中」、その後「承認済み」。のちに「非推奨」や「置き換え済み」になることもあり、置き換え先へのリンクをつける。
• 結果：決定後の状況。良い影響、悪い影響、どちらでもない影響を含める。

長さは1〜2ページ。文体は、未来の開発者と会話するつもりで、完全な文で書きます。箇条書きはレイアウトのために使い、文を断片に置き換えないこと。保存場所はプロジェクトのリポジトリで、たとえばdoc/arch/adr-NNN.md。番号は連番で、再利用しません。覆された決定は削除しません。古い記録を残し、置き換え済みと印をつけます。

Nygardは使った経験も書いています。複数のプロジェクトで約3か月使ったあと、それらを行き来した6〜10人の開発者が、記録の背景の部分に価値があると話した、とのことです。これは著者自身の報告で、小さな集団であり、対照実験ではありません。

2.2 MADR：よく使われるMarkdownのテンプレート#

MADR（Markdown Architectural Decision Records）は、Markdownで書く軽いテンプレートです。公式ページによると、構成は次のとおりです。タイトル、任意の先頭情報（状態、日付、決定者、相談した人、知らせた人）、背景と課題、任意の判断要因、検討した選択肢、決定の結果（良い結果と悪い結果を含む）、任意の遵守確認、各選択肢の長所と短所、補足情報（見直す条件も書ける）。保存の慣習は、docs/decisionsというフォルダにNNNN-title-with-dashes.mdという名前で連番にすることです。ページが説明している最新版は2024年9月17日公開の4.0.0で、MITまたはCC0のデュアルライセンスです。

2.3 Y-statement：1文のADR#

Y-statementは、Olaf Zimmermannと関係する著者たちによって広まった短い形で、次のパターンの1文です。「（状況）において、（懸念）に直面し、私たちは（選択肢）を選び、（他の選択肢）は選ばず、（品質目標）を達成するために、（代償）を受け入れた」。私が読んだ出典では、つなぎの言葉が少しずつ違うので（「and against」や「and neglected」）、厳密な規格ではなくパターンとして扱ってください。Y-statementは単純な決定に向いています。複雑な決定には、MADRやNygard版のような、より詳しい形式が勧められています。

ポイント： ADRは複雑な道具ではありません。核は4つの問いです。どんな状況にいるか、何を選ぶか、何を捨てるか、何を失うことを受け入れるか。

---

3. なぜチームは決定を失い、AIでなぜそれが目立つのか#

3.1 Stack Overflow 2026調査のデータ#

Stack Overflow Developer Survey 2026の結果ページには、文脈に関する困りごとの項目があります。私が読んだ要約では、回答者の約60.9%が「重要な文脈が人の頭の中にある」、56.5%が「情報が古い」、53.4%が「情報が多すぎるツールに散らばっている」、63.2%が「情報が不完全」と答えています。要約を通して読んだだけで、各表との照合はしていません。元の質問は技術的な決定より広いかもしれず、回答者は調査に答えた人たちです。ですからこれは、チームの知識は散らばりがちという一般的なシグナルであり、ADRについての証拠ではありません。

3.2 AIエージェントの場合：コードは見えるが、理由は見えない#

エージェントを、とても速いけれど今日入ったばかりの同僚だと思い浮かべてください。コード全体を数秒で読めますが、先週の会議は覚えていません。遠回りなコードを見ると、単純にするのが自然な反応です。その遠回りが理由のある決定の結果なら、止められるのは、探す場所に書かれた理由だけです。

はっきり言っておくと、ADRを文脈に入れるとエージェントが決定を覆す回数がどれだけ減るかを測った研究は、私は見つけられませんでした。これは実践上の考え方で、エージェントが読む場所に必要なことを置くという、記事AIの取扱説明書：AGENTS.mdの考え方につながります。

3.3 自分で確かめられる計算（例、読み飛ばし可）#

これは作った数字の例で、実測ではありません。6人のチームが月に2つ決定を記録し、各ADRは300語、技術文書を読む速さは1分150語（仮定）とします。1年で24件のADRがたまります。

adr, words, wpm = 24, 300, 150
read_all = adr * words / wpm          # 7200語、つまり48分
index = adr * 12 / wpm                # 24個のタイトル、1行12語、つまり288語、約2分

asked, explain = 5, 15                # 新人が5つの決定を聞き直し、先輩が1回15分で説明
without = asked * explain             # 先輩の時間75分
with_adr = asked * words / wpm        # ADR5件 x 2分 = 新人の時間10分
print(read_all, round(index, 2), without, with_adr)
# 48.0 1.92 75 10.0

newcomers = 4
print(newcomers * without, newcomers * with_adr)
# 300 40.0  （1年あたりの分）

結果の読み方：24件のADRをすべて読むと約48分、タイトルの一覧だけなら約2分なので、全部を読み込む必要はありません。新人が5つの決定を聞き直し、先輩が1回15分で説明すると、1人あたり先輩の時間で75分、新人4人なら年300分です。ADRがあれば、新人は5件を1人あたり約10分で読めるので、年40分です。

念のため：300語、1分150語、5つの質問、15分は私の仮定です。ADRにも書く時間と更新する時間がかかりますが、ここには含めていません。自分のチームの数字に置き換えてください。

---

4. 1ページのテンプレート#

提出用紙を思い浮かべてください。欄は少なく、どの欄も必須で、10分で埋められる小ささです。以下のテンプレートはNygard版をもとに、MADRの考え方から2つの欄（見直す条件と確認方法）を足したものです。決定に出口と確認手段を持たせるためです。

# ADR 0007: リマインドはキュー経由で送る

状態: 承認済み（提案中 / 承認済み / ADR 00NNに置き換え済み）
日付: 2026-03-12
決定者: 名前または役割

## 背景
状況と制約を、判断を入れず事実として書く。誰が何を待っているか。

## 決定
私たちは〜します（1〜2文の完全な文、能動態）

## 却下した案
- 案A：選ばなかった理由。
- 案B：選ばなかった理由。

## 結果
- 得るもの：良いこと。
- 失うもの：受け入れた代償。
- どちらでもない：変わるだけで、良くも悪くもないこと。

## 見直す条件
決定を見直すきっかけになる具体的な条件。

## 確認方法
決定が守られていることを示す、自動チェックや観察できる兆候。

1ページに収める3つのルール：

1. ADR1つに決定1つ。 タイトルに「と」が必要なら、2つの決定かもしれません。
2. 背景と決定は完全な文で。 箇条書きは、案や結果のような短い一覧だけにします。
3. 長い詳細は別の場所に。 比較表、グラフ、実験結果は、貼らずにリンクします。

---

5. 記入例：書き上げたADR#

これはこの記事のために作った例で、実在の会社や製品には触れていません。状況：小さなアプリが、サービス業の店の予約を助け、リマインドのメールを送ります。例の数字はすべて架空です。

# ADR 0007: リマインドはリクエスト処理中ではなくキュー経由で送る

状態: 承認済み
日付: 2026-03-12

## 背景
お客さまが予約すると、アプリはリクエストの処理中に確認メールを送っている。
メール送信サービスは、ときどき応答に数秒かかり、一度は1時間停止した。
その間は予約ページが固まり、予約ボタンを2回押したお客さまもいた。

## 決定
私たちはメール送信をジョブキューに入れます。予約のリクエストは、予約を
データベースに書き込んですぐに応答するだけにします。別のワーカーがメールを
送り、最大3回まで再試行します。

## 却下した案
- リクエスト内で直接送る：一番単純だが、サービスが遅いとページが固まる。
- 1分ごとの定期ジョブで表を走査する：キューは不要だが、メールが最大1分遅れ、
  大きな表を走査する。

## 結果
- 得るもの：予約ページが速く応答し、メールの失敗が予約を壊さなくなる。
- 失うもの：監視する部品が1つ増え、メールが数秒遅れることがある。
- どちらでもない：デバッグ時に読むログの種類が1つ増える。

## 見直す条件
6か月間、1日のメール送信数が50通を下回る場合、または
メール事業者が組み込みのキューを提供した場合。

## 確認方法
予約のリクエストがメール送信サービスを直接呼ばないことを確かめるテスト。

同じ決定のY-statement版：「予約受付という状況で、遅くて失敗しやすいメール送信サービスに直面し、私たちは送信をキューに入れることを選び、直接送信や定期的な表の走査は選ばず、予約ページを常に速く保つために、監視する部品が1つ増えることを受け入れた。」

完全版は日本語で約550字、1ページに収まる長さです。注目してほしいのは、「却下した案」の欄が、人もAIも一番単純な案に戻ってしまうのを防ぐという点です。一番単純な案は、誰もが最初に思いつくものだからです。

---

6. AIエージェントが読めて使えるようにADRを書く#

次の当番の人にメモを残すところを思い浮かべてください。メモは、その人の目に入る場所に貼ってはじめて役に立ちます。

1. ADRはリポジトリに置く。 たとえばdocs/adrフォルダに、コードと変更履歴と一緒に置きます。
2. 索引ファイルを用意する。 各ADRのタイトル、状態、パスを1行ずつ並べます。エージェントは索引を読んで関係する記録を開くので、全部を読み込まずに済みます。
3. エージェントの指示ファイルからリンクする。 AGENTS.mdやツールの指示ファイルに、下のブロックのような数行を足します。
4. 状態は1行目に、決まった言葉で書く。 提案中、承認済み、置き換え済みなど。人にも機械にも絞り込めます。
5. 最初の2つの欄は人が書く。 背景と決定は人が埋めます。AIは却下した案の提案や下書きはできますが、もっともらしい理由が本当の理由とは限りません。理由は人が確認します。記事AIの結果に証拠を求める5つの方法の考え方と同じです。

## 既存の決定
- docs/adrで扱われているやり方を変える前に、索引docs/adr/README.mdを読み、
  関係するADRを開くこと。
- 変更が承認済みのADRに反する場合は、自分で直さず、手を止めて質問すること。
- 完了を報告するときは、どのADRを読んだかを書くこと。

3行で、人もエージェントも全部読める短さです。最後の行は、証拠の記事の4つ目の方法、つまり「読んだこと」と「仮定したこと」を分ける考え方を借りています。

---

7. ADRのライフサイクル#

一番大事な点：古い記録を削除しないこと。 読む人は、かつて何を決めたかと、なぜ変えたかの両方を見る必要があります。

---

8. ADRを書かないほうがよいとき#

これは私の経験則で、NygardやMADRの規格ではありません。台所のごみ箱を思い浮かべてください。何にでも専用のノートがいるわけではありません。

• 書かない： 1時間ほどの作業で元に戻せる決定（変数名の変更、ファイル名の選択）。
• 書かない： 理由がツールの標準ドキュメントにあり、誰でも調べられる場合。
• 書かない： 手続きを満たすためだけに書く場合。誰も読まないADRは、手間がかかるだけで役に立ちません。
• 書く： 新人が「なぜこうなっているのか」と聞きそうなとき、決定を覆すのに半日以上かかるとき、誰もが最初に思いつく案をちょうど却下したとき。

---

9. ADRにも弱いところがある#

レシピ帳を思い浮かべてください。分厚くて誰も開かないもの、何年も前から間違ったままのものがあります。

9.1 例：ADRがある朝とない朝#

これは例（想定）で、実在の人物や製品には触れていません。5章の例を使っています。

ADRがない場合：

• 09:00。 開発者がエージェントに頼みます。「予約まわりのコードを整理して、余分な部分を減らして」。
• 09:20。 エージェントはメールのキューを余分な層と見なし、直接呼び出しに変えます。既存のテストはすべて通ります。
• 11:00。 開発者は差分を読み、妥当だと思ってマージします。
• 15:30。 メールサービスが遅くなります。予約ページが固まり、お客さまが2回予約します。

ADRがあり、AGENTS.mdがそれを指している場合：

• 09:00。 同じ依頼です。
• 09:10。 エージェントはADRの索引を読み、ADR 0007を開いて言います。「このキューは承認済みの決定です。変更しません。置き換えるための新しいADRを作りますか」。
• 09:20。 開発者が答えます。「そのままで。ほかの部分だけ整理して」。
• 09:50。 エージェントは変更を提出し、「ADR 0007を読み、キューには触れていません」と書きます。

どちらの場合もすべきことは、エージェントが余分に見えるものを消そうとする時点で止まり、それに理由があるかを聞くことです。これは例なので何も証明しません。Stack Overflow調査のシグナル（3章）とNygardの報告が示すのは、文脈の欠如が実際にあること、そして短い記録が助けになりうることだけです。

---

10. 使った数字と文書#

正しく読むために： 上の出典は、短い理由を残すことを支持しています。ADRが誤りを減らす、あるいはAIエージェントが決定を覆すのを防ぐことを直接測った対照実験は、見つかっていません。この記事のAIに関する部分は、実践の整理です。

---

11. 明日から使える習慣#

11.1 ADRを確定する前の8つの質問#

1. これは1つの決定か、2つがくっついていないか。
2. 1年後の読み手が、誰にも聞かずに背景を理解できるか。
3. 決定は「私たちは〜します」で始まる完全な文か。
4. 却下した案と、その理由が書いてあるか。
5. 結果に、得るものだけでなく失うものとどちらでもないことも入っているか。
6. 見直す具体的な条件と、確認方法があるか。
7. 状態と日付は1行目にあり、索引は更新したか。
8. AGENTS.mdやREADMEがこのADRを指しているか。

11.2 すぐできる3つのこと#

1. docs/adrフォルダと、空の索引を作る。
2. 新人がよく聞く最近の決定を1つ選び、約15分で最初のADRを書く。
3. 6章の3行を、AIエージェントの指示ファイルに足す。

---

12. バランスよく見る：ADRにできること、できないこと#

できること： 理由を残す、新人が自分で答えを探せるようにする、エージェントに修正前の確認場所を与える、各決定の代償をチームに言葉にさせる。

できないこと：

• ADRは決定が正しいことを保証しません。そのときに何を考えたかを残すだけです。
• 更新されないADRは、ADRがないより害になることがあります。有効でないことを有効だと言うからです。
• エージェントがADRを読む義務はなく、どの程度従うかを測ったテストも私は見ていません。エージェントに、どのADRを読んだかを報告させて確かめてください。
• ADRは書く手間も維持する手間もかかります。ごく小さなチームや短期のプロジェクトでは、READMEの一文で足りるかもしれません。
• AIが代わりに書いた理由は、流暢でも正しいとは限りません。人が確認する必要があります。

言い過ぎないために： ADRはチーム内の会話の代わりにはなりません。軽く見ないために： 失われた決定のコストは、たいてい最後に来ます。誰かが、それにかつて理由があったことを知らずに覆すときです。

---

13. まとめ#

コードは何をしたかを示し、ADRはなぜそうしたかを示します。決定の時点で書いた短い1ページに、捨てた案と受け入れた代償を書き、人とAIが読む場所からの道をつけておけば、「理由があったと誰も知らなかった」だけで覆される決定の多くを防げます。まず、新人がよく聞く決定から始めてください。

---

参考資料#

数字は2026年10月時点の公開情報です。一部は要約を通して読んでいるので、引用する前に元の出典を開いて確かめてください。

• Michael Nygard、Documenting Architecture Decisions（Cognitect、2011年11月15日）
• Architectural Decision Records、adr.github.ioとMADR（バージョン4.0.0）
• Olaf Zimmermann、Y-Statements（1文のADRのパターン）
• Stack Overflow、2026 Developer Survey（要約を通して読んだもので、各表は未照合）