--- title: "1ページで決定を残す（ADR）：人のためにも、AIのためにも" url: https://www.stacklogs.io.vn/ja/keiken/adr-1peji-de-kimeta-koto-wo-nokosu/ language: ja author: "Nhu Duy Thin (Thinnd)" published: 2026-10-30 updated: 2026-10-30 section: "経験と教訓" tags: ["ADR", "意思決定の記録", "ドキュメント", "AIエージェント", "チーム開発", "テンプレート"] summary: "ADR（architecture decision record）は、技術的な決定を1つ、理由とともに残す短い1ページです。背景、決定、結果、状態を書きます。Michael Nygardが2011年に1〜2ページの形式として提案しました。記録をリポジトリに置き、AIエージェント向けの指示ファイルからリンクしておくと、新人もエージェントも、理由を知らないまま過去の決定を覆さずに済みます。" license: "Cite with the author name and the canonical URL above." --- # 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はすべての変更に必要な儀式ではありません。小さくて簡単に戻せる決定には不要です。また、状態を更新する人と、読む人がいてはじめて役に立ちます。 --- ## むずかしい言葉をやさしく | 用語 | やさしい説明 | |---|---| | **ADR**（決定記録） | チームがなぜこの方法を選んだかを書いた1ページ。レシピの「塩は入れない、塩を控えているお客さまがいるため」というメモのようなものです。 | | **Context**（背景） | 決定したときの状況。何が必要で、何に縛られ、誰が待っているか。 | | **Decision**（決定） | チームがこれからすること。「私たちは〜します」で始まる完全な文で書きます。 | | **Consequences**（結果） | 決定のあとに起きること。得るもの、失うもの、どちらでもない変化を含みます。 | | **Status**（状態） | 記録がどの段階にあるか。提案中、承認済み、置き換え済みなど。 | | **Superseded**（置き換え済み） | 新しい決定ができて、古い決定は有効でなくなったこと。古い記録は残し、印をつけ、新しい記録を指します。 | | **Y-statement** | ADRを1文にした形。「Xという状況で、Yに直面し、私たちはAを選びBは選ばなかった」というパターンです。 | | **リポジトリ** | チーム全員がコードを置く場所。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](https://www.stacklogs.io.vn/ja/gijutsu/agents-md-no-kakikata/)の考え方につながります。 ### 3.3 自分で確かめられる計算（例、読み飛ばし可） これは作った数字の例で、実測ではありません。6人のチームが月に2つ決定を記録し、各ADRは300語、技術文書を読む速さは1分150語（仮定）とします。1年で24件のADRがたまります。 ```python 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つの欄（見直す条件と確認方法）を足したものです。決定に出口と確認手段を持たせるためです。 ```markdown # ADR 0007: リマインドはキュー経由で送る 状態: 承認済み（提案中 / 承認済み / ADR 00NNに置き換え済み） 日付: 2026-03-12 決定者: 名前または役割 ## 背景 状況と制約を、判断を入れず事実として書く。誰が何を待っているか。 ## 決定 私たちは〜します（1〜2文の完全な文、能動態） ## 却下した案 - 案A：選ばなかった理由。 - 案B：選ばなかった理由。 ## 結果 - 得るもの：良いこと。 - 失うもの：受け入れた代償。 - どちらでもない：変わるだけで、良くも悪くもないこと。 ## 見直す条件 決定を見直すきっかけになる具体的な条件。 ## 確認方法 決定が守られていることを示す、自動チェックや観察できる兆候。 ``` 1ページに収める3つのルール： 1. **ADR1つに決定1つ。** タイトルに「と」が必要なら、2つの決定かもしれません。 2. **背景と決定は完全な文で。** 箇条書きは、案や結果のような短い一覧だけにします。 3. **長い詳細は別の場所に。** 比較表、グラフ、実験結果は、貼らずにリンクします。 --- ## 5. 記入例：書き上げたADR これはこの記事のために作った例で、実在の会社や製品には触れていません。状況：小さなアプリが、サービス業の店の予約を助け、リマインドのメールを送ります。例の数字はすべて架空です。 ```markdown # 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つの方法](https://www.stacklogs.io.vn/ja/gijutsu/ai-no-kekka-ni-shoko-wo-motomeru-5tsu-no-hoho/)の考え方と同じです。 ```text ## 既存の決定 - docs/adrで扱われているやり方を変える前に、索引docs/adr/README.mdを読み、 関係するADRを開くこと。 - 変更が承認済みのADRに反する場合は、自分で直さず、手を止めて質問すること。 - 完了を報告するときは、どのADRを読んだかを書くこと。 ``` 3行で、人もエージェントも全部読める短さです。最後の行は、証拠の記事の4つ目の方法、つまり「読んだこと」と「仮定したこと」を分ける考え方を借りています。 --- ## 7. ADRのライフサイクル | 状態 | 意味 | すること | |---|---|---| | 提案中 | 議論中で、まだ誰も従う必要はない | 期限と決定者を書く | | 承認済み | 有効 | 正しく保ち、索引からリンクする | | 非推奨 | もう適用されず、置き換えもない | 短い理由を足す | | 置き換え済み | 新しいADRが置き換えた | 古い記録は残して印をつけ、新しい記録を指す。新しい記録からも古い記録を指す | 一番大事な点：**古い記録を削除しないこと。** 読む人は、かつて何を決めたかと、なぜ変えたかの両方を見る必要があります。 --- ## 8. ADRを書かないほうがよいとき これは私の経験則で、NygardやMADRの規格ではありません。台所のごみ箱を思い浮かべてください。何にでも専用のノートがいるわけではありません。 - **書かない：** 1時間ほどの作業で元に戻せる決定（変数名の変更、ファイル名の選択）。 - **書かない：** 理由がツールの標準ドキュメントにあり、誰でも調べられる場合。 - **書かない：** 手続きを満たすためだけに書く場合。誰も読まないADRは、手間がかかるだけで役に立ちません。 - **書く：** 新人が「なぜこうなっているのか」と聞きそうなとき、決定を覆すのに半日以上かかるとき、誰もが最初に思いつく案をちょうど却下したとき。 --- ## 9. ADRにも弱いところがある レシピ帳を思い浮かべてください。分厚くて誰も開かないもの、何年も前から間違ったままのものがあります。 | 状況 | 仕組み | 見抜き方 | |---|---|---| | 理由を忘れたあとに書く | 理由がもっともらしく作り直される | 決定の時点で書く。または「当初の理由は不明」と書く | | 長すぎる | 誰も読まない。特にエージェントが冒頭しか取らないとき | 1ページに収め、詳細はリンクにする | | 状態を更新しない | コードが変わったのに古いADRが「承認済み」のまま | PRのテンプレートに「どのADRに影響するか」の質問を足す | | 誰も読まない | ADRがどこかにあるだけで、そこへの道がない | AGENTS.md、README、PRテンプレートからリンクする | | 本当の決定がチャットにある | メッセージで決まったことが記録されない | 決まったらすぐADRを書き、リンクを会話に貼る | | AIがもっともらしいが間違った理由を下書きする | 流暢な文が、分かっていないことを隠す | 背景は人が書き、「これを見ていた人は誰か」と聞く | | 小さなADRが増えすぎる | 索引が長くなり探しにくい | 8章のルールに当てはまる決定だけ記録する | ### 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. 使った数字と文書 | 出典 | 内容 | 読み方 | 注意 | |---|---|---|---| | Michael Nygard、2011年11月15日 | 理由が失われると、新人は盲目的に受け入れるか軽率に覆す。5つの部分、1〜2ページ、古い記録は削除しない | この記事のテンプレートの土台 | 意見の記事で、小さな集団での約3か月の著者自身の報告を含む | | MADR 4.0.0（2024年9月17日） | Markdownのテンプレート、`docs/decisions`フォルダ、`NNNN-title.md`、検討した選択肢と確認の欄 | テンプレートに足した2つの欄の根拠 | 実践のテンプレートで、効果の研究ではない | | Y-statement（Zimmermannほか） | 1文：状況、懸念、選んだ案と選ばなかった案、目標、代償 | 単純な決定向けの短い形 | 出典によってつなぎの言葉が少し違う | | Stack Overflow Developer Survey 2026 | 約60.9%が文脈は頭の中、56.5%が情報が古い、53.4%がツールに散らばっていると回答 | チームの知識は散らばりがち | 要約を通して読んだ。元の質問はもっと広いかもしれず、ADRを測ったものではない | **正しく読むために：** 上の出典は、短い理由を残すことを支持しています。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](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)（Cognitect、2011年11月15日） - Architectural Decision Records、[adr.github.io](https://adr.github.io/)と[MADR](https://adr.github.io/madr/)（バージョン4.0.0） - Olaf Zimmermann、[Y-Statements](https://medium.com/@docsoc/y-statements-10eb07b5a177)（1文のADRのパターン） - Stack Overflow、[2026 Developer Survey](https://survey.stackoverflow.co/2026/)（要約を通して読んだもので、各表は未照合）