AIエージェントの毎回「新人」になる問題の解決方法。MADRの正式な書き方と、AI開発チームでの回し方

Posted at 2026-10-07

AIに「それは前にやめた案です」と説明した回数を、数えたことはありますか。

AIのコーディングエージェントは、セッションを始めるたびに、前の会話を知らない状態で仕事を始めます。先週一緒に検討して却下した案も知りません。一般論として良い案なら、素直にもう一度勧めてきます。そして人間が、先週と同じ説明をもう一度します。

この繰り返しを止める一番安い方法が、ADR（Architecture Decision Record、設計の決定の記録） です。この記事では、ADR とは何か、AIと開発するとなぜ要るのか、どう書き、チームでどう回すかを、手順とプロンプト付きで書きます。最後に、この運用をターミナルの中で回せるようにした仕組みを紹介します。

対象は v0.24.0 から v0.26.0（2026年10月6日）までです。手順はアプリが無くても今日から使えます。

ADRとは: 決定1件を、ファイル1枚に

ADR は、設計上の決定1件を、短い Markdown ファイル1枚に書いたものです。2011年に Michael Nygard が提案した習慣で、リポジトリの決まったフォルダに番号付きで置きます。

仕様書や設計書との違いは、書く対象です。

仕様書・設計書: システムがどう動くか。システムが変われば書き直す
ADR: なぜその形にしたか、ほかに何を比べて何をやめたか。あとから書き換えない

書式はいくつかありますが、この記事では、いまよく使われる MADR（Markdown Architectural Decision Records）の版4に沿って書きます。MADR では、置き場所は docs/decisions/、ファイル名は 0004-cache-order-listings-in-process.md のように、4桁の番号と、題をハイフンでつないだ小文字の名前です。

MADR で必須の節は4つだけです。まずは必須の節だけで書いた最小の形です。

# 注文一覧のキャッシュを Redis からプロセス内の LRU に替える

## Context and Problem Statement

注文一覧のキャッシュのために Redis を1台運用している。読むのは API サーバー1台だけで、
1ページは最大50行。キャッシュのためだけに、障害の窓口になるサーバーを持ち続けるべきか。

## Considered Options

* プロセス内の LRU キャッシュ
* Redis を続ける
* キャッシュしない

## Decision Outcome

Chosen option: "プロセス内の LRU キャッシュ", because API サーバーが1台なのでキャッシュを共有する必要がなく、運用するサーバーを1台減らせるから。

これに、必要に応じて任意の節を足します。チームで回すなら、少なくとも前書き（状態と人）と Consequences は足すことを勧めます。

---
status: accepted
date: 2026-09-30
decision-makers: 佐藤, 岡本
consulted: Claude Code (AI)
informed: サポートチーム
---

# 注文一覧のキャッシュを Redis からプロセス内の LRU に替える

## Context and Problem Statement
（上と同じ）

## Decision Drivers

* API サーバーは1台で、増やす予定がない
* 1ページは最大50行で、メモリに収まる
* 運用するサーバーを減らしたい

## Considered Options
（上と同じ）

## Decision Outcome

Chosen option: "プロセス内の LRU キャッシュ", because Decision Drivers をすべて満たすのはこの案だけだから。

### Consequences

* Good, because 運用するサーバーが1台減る
* Bad, because API サーバーを再起動するとキャッシュが空になり、直後はデータベースへの読み取りが増える

### Confirmation

コードレビューで、注文一覧の読み取りが Redis のクライアントを使っていないことを確かめる。

## Pros and Cons of the Options

### プロセス内の LRU キャッシュ

* Good, because サーバーが1台減る
* Neutral, because キャッシュの大きさを自分で決める必要がある
* Bad, because 再起動でキャッシュが消える

### Redis を続ける

* Good, because 再起動してもキャッシュが残る
* Bad, because キャッシュのためだけにサーバーを1台運用し続ける

## More Information

API サーバーを2台以上にするときは、この決定を見直す。
Supersedes [ADR-0002](0002-cache-order-listings-in-redis.md).

中身は日本語で書けます。節の名前と、Chosen option や Good, because のような決まった言い回しは、MADR のまま英語で残します。形がそろっていれば、人もAIも、同じ場所で同じことを読めます。

節ごとに、答える問いが決まっている

節	必須か	答える問い	書くときの注意
題	必須	何の問題を、どう解いたか	MADR は「解いた問題と見つけた答えが分かる短い題」を求める。「キャッシュの検討」では答えが分からない
Context and Problem Statement	必須	何がこの決定を迫ったか	数字と制約で、2〜3文。問いの形で終えてもよい
Considered Options	必須	ほかに何を比べたか	一番見落とされ、一番役に立つ節。「何もしない」も案
Decision Outcome	必須	どれを、なぜ	`Chosen option: "…", because …` の形で
前書き	任意	いま有効か、誰が決め、誰に聞き、誰に知らせたか	`consulted` は意見を聞いた相手（双方向）、`informed` は知らせた相手（一方向）。名前だけ書き、メールアドレスは書かない
Decision Drivers	任意	何を基準に選んだか	Decision Outcome の理由が「Drivers をすべて満たすから」と書けるようになる
Consequences	任意	何が良くなり、何が悪くなるか	`Bad, because` も書く。良いことだけなら宣伝文
Confirmation	任意	守られていることを、どう確かめるか	レビューやテストで確かめられる形に。AIにレビューさせるときの観点にもなる
Pros and Cons of the Options	任意	案ごとの長所と短所	案ごとに `###` の見出しを立て、`Good` / `Neutral` / `Bad, because` を1行に1つ
More Information	任意	根拠、いつ見直すか、関連する決定	「API サーバーを2台以上にするときは見直す」のような見直しの条件をここに

Context が具体的だと、ADR は有効期限を判断する材料になります。上の例なら、「API サーバーが2台になった」と分かった時点で、見直すべきだと気づけます。

状態は5つ

状態（`status`）	意味
proposed	議論中
accepted	決まった。いま有効
rejected	検討したが採らなかった（消さずに残す）
deprecated	もう従わなくてよいが、代わりはまだ無い
superseded by ADR-NNNN	新しい決定に置き換えられた

承認した ADR は書き換えません。 考えが変わったら新しい ADR を書き、新しい ADR の More Information に Supersedes ADR-0002 と書き、古い ADR の状態を superseded by ADR-0004 にします。こうすると「なぜ考えが変わったか」まで残ります。誤字の修正だけは例外です。

なぜ、AIと開発すると ADR が要るのか

AIは、セッションごとに新しく入った人になる

新しく入った人が型破りな決定に出会うと、何時間も調べるか、「誤り」として直してしまいます。ADR が昔から勧められてきた理由の1つが、この新人の問題でした。

AIエージェントは、セッションを始めるたびにこの新人になります。前の会話を覚えておらず、長い会話は途中で要約されて細部が落ち、チームの別の人のAIはそもそもその会話を見ていません。新人の問題が、毎日、何度も起きるようになりました。

AIは、一般論の最善を勧める

Redis のキャッシュは、一般論としては良い案です。このプロジェクトでは却下した、という事実を知らないAIは、素直に Redis を勧めます。プロセス内のキャッシュを見て「スケールしないので Redis に替えましょう」と直そうとすることもあります。AIをこのプロジェクトの判断に従わせるには、その判断が読める場所に書いてある必要があります。

決定がチャットの中で増え、理由が置き去りになる

AIと開発すると、案を並べて比べて決めるところまでを、AIとの会話で済ませます。コードを書く時間が減ったぶん、決定の数は増えます。理由は会話の履歴に残りますが、そこは後から探しに行く場所ではありません。

逆に言えば、決定に至った会話が手元にあるので、ADR の下書きはAIに書かせられます。「書く手間に見合わない」という、ADR が定着しなかった一番の理由が小さくなりました。

回し始める7つの手順

1. 置き場所を決める

MADR の既定は docs/decisions/ です。ファイル名は 0001-keep-orders-in-postgresql.md のように、4桁の番号と、題をハイフンでつないだ小文字の名前にします。MADR が配っているテンプレート（adr-template.md）も、同じフォルダに置いておきます。

2. AIに読ませる

ADR を書いても、AIが読まなければ蒸し返しは止まりません。Claude Code は CLAUDE.md、Codex は AGENTS.md をセッションの初めに読みます。

## 設計の決定
設計を変える提案をする前に、docs/decisions/ の ADR を読むこと。
承認済み（accepted）の ADR に反する案を出すときは、どの ADR に反するのかを先に書くこと。

特に従うもの:
- ADR-0001 注文は PostgreSQL に保存する
- ADR-0004 注文一覧をプロセス内にキャッシュする（Redis は ADR-0002 でやめた）

2行目で「反するときは名指ししてから」と書くのは、AIに黙って蒸し返させず、どの決定に反するのかを先に言わせるためです。そう言われれば、見直すかどうかを人間が決められます。

3. 決めた直後に、会話から下書きさせる

ADR は決めた直後に書きます。翌日には、比べた案の半分を忘れています。AIとの相談で決まったなら、その会話の中でAIに書かせるのが一番速いです。そのときのプロンプトの例です。

いまの会話で決まった（または決まりかけている）設計の決定を、MADR の形式で ADR に書いてください。

- 会話に出てきたことだけを使うこと。会話に出てこなかった案・理由・数字・結果を足さないこと
- 会話に材料が無い節は、空のまま残すこと
- まだ決まっていなければ、比べた案だけを書き、Decision Outcome は空にすること
- 節の名前は MADR のまま英語で残し、中身は日本語で書くこと
- 題は、解いた問題と選んだ答えが分かる短い文にすること
- Decision Outcome は `Chosen option: "<案の名前>", because <理由>` で始めること
- Consequences と Pros and Cons of the Options は、1行に1つずつ `* Good, because` / `* Neutral, because` / `* Bad, because` で書き、Pros and Cons では案ごとに `### <案の名前>` の見出しを立てること。悪くなることも必ず書くこと
- 前書きの status は proposed、consulted には「Claude Code (AI)」と書くこと

一番大事なのは1行目の注意です。AIは、書いていない理由をもっともらしく補うのが得意です。補われた理由は読みやすく、そしてそのとき誰も考えていなかったことです。ADR の価値は、そのとき本当に考えたことが書いてあることにあります。

4. 過去の決定を、3〜5件だけ遡って書く

ADR は、最初の数件があるとAIが読む価値が出ます。すでに決めて、よく聞かれることから3〜5件を遡って書きます。マージ済みのプルリクエストをAIに読ませると下書きが速いです。

gh pr view 128 --json title,body,comments,files | \
  claude -p "この PR に設計の決定（依存の追加、データの形の変更、新しい型の導入、2つ以上の方法から選んだもの）が含まれていれば、MADR 4 の形式（必須の節は Context and Problem Statement・Considered Options・Decision Outcome）で ADR として書いてください。PR に書かれていない理由は足さず、分からない節は『記録なし』と書いてください。決定が含まれていなければ『ADR 不要』とだけ答えてください。"

遡って書いた ADR は、理由の一部が推測になりがちです。「記録なし」の節は、知っている人に聞いて埋めるか、そのまま残します。推測で埋めた ADR は、無い ADR より害があります。

5. 議論はプルリクエストで

チームで回すときは、ADR を proposed で書いてプルリクエストを出し、コードと同じようにレビューします。決まったら状態を accepted にしてマージします。異論が出たら、決まる前に出てくるのが利点です。

6. CI では、止めずに知らせる

依存やスキーマが変わったのに ADR が無いプルリクエストに、注意を出すこともできます。止めるのではなく、警告だけにするのがコツです。ADR が無いとマージできないようにすると、中身の無い ADR が増えます。

# .github/workflows/adr-reminder.yml
name: adr-reminder
on: pull_request
jobs:
  remind:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: 依存やスキーマが変わったのに ADR が無ければ知らせる
        run: |
          changed=$(git diff --name-only "origin/${{ github.base_ref }}...HEAD")
          if echo "$changed" | grep -qE '(^|/)(package\.json|Cargo\.toml|go\.mod|requirements\.txt)$|(^|/)migrations?/' \
             && ! echo "$changed" | grep -q '^docs/decisions/'; then
            echo "::warning::依存かスキーマが変わっています。設計の決定なら docs/decisions/ に ADR を足してください"
          fi

7. ときどき、状態を見直す

置き換えられたのに accepted のままの ADR は、人もAIも誤らせます。AIは特に、書いてある状態をそのまま信じます。四半期に一度くらい、一覧を眺めて状態を直します。

よくある失敗

背景が抽象的。 「パフォーマンスを改善する必要があった」では、見直す時期を判断できない
比べた案が無い。 事後の正当化に見える
1枚に複数の決定。 「マイクロサービス化」は1件ではない。サービスの境目・通信の方式・配置の方式は、それぞれ別の ADR
状態が古いまま。 特にAIが誤る
説明書と混ぜる。 「どう動くか」は README へ。ADR は「なぜ」だけ

よくある質問

Q. どの大きさで1件にすればいいですか。
1件に1つの決定です。「キャッシュに Redis を使う」と「Redis はマネージドのサービスを使う」は別の ADR にします。一部だけ変わったときに、その部分だけ置き換えられるからです。

Q. 承認した ADR の誤字は直してもいいですか。
決定の中身を変えない直しなら、直して構いません。理由や選んだ案が変わるなら、新しい ADR を書きます。

Q. AIに相談して決めたことは、誰が決めたことになりますか。
決めたのは人です。decision-makers には人の名前を書き、AIは consulted（意見を聞いた相手）に書きます。後から読む人は、この決定にAIが関わったことを知ったうえで読めます。

Q. 引き継いだプロジェクトに古い ADR がたくさんあります。
いまも正しいとは限らないものとして読みます。1件ずつ今のコードと照らし、合わなくなったものは deprecated にするか、新しい ADR で置き換えます。

この運用を、AIのタブの隣で回せるようにした

私は、Claude Code や Codex をタブに並べて走らせる Windows 用のターミナル（SHIKISHA-TERM）を作っています。上の手順の3・5と、AIに読ませる準備を、AIのタブのすぐ隣でできるようにしました。

会話から下書き。 「新しい ADR」のフォームで ✨ を押すと、いま見ているAIのタブの会話の記録から、MADR の下書きが入ります。手順3の注意（会話に無いことは書かない、材料が無い節は空、MADR の決まった言い回し）を指示に入れてあり、consulted にはそのタブのAIの名前が入ります
保存して、プルリクエストで提案。 ADR のファイルだけをコミットし、main の上にいれば ADR 用のブランチを切って、GitHub にプルリクエストを開きます。マージのボタンは置いていません。採るかどうかはチームが決めることだからです
承認・却下・置き換え。 ADR を開くと、状態に合った操作だけが並びます。承認済みの「編集」は灰色で、押すと「新しい ADR で置き換える」と「誤字だけをエディタで直す」の2つの道が出ます。置き換えると、両方のファイルに互いへのリンクが書かれます
AIに守らせる。 同意を取ったうえで Claude Code などに入れる手順書（スキル）に、手順2と同じこと（設計に関わる作業の前に ADR を読む、accepted に反するなら名指しして人に聞く）を書いてあります。プロジェクトごとに CLAUDE.md に書かなくても済みます
ADR に聞く。 「キャッシュには何を使っている？」と聞くと、アシスタントAIが ADR だけを読み、いま有効な決定を ADR-0004 のように名指しして答えます

プロジェクトの設定で「決定の記録を残す」に印を付けると使えます（既定はオフ）。日本語の題からは、0004-注文一覧をプロセス内にキャッシュする.md のように日本語のまま読めるファイル名を作ります。フォルダに adr-template.md があれば、チームの書式としてそちらを使います。

そのほか（v0.24.0 から）

このPCの端末が、アプリを閉じても動き続ける（0.24.0）
マスターパスワードでアプリ全体に鍵をかけられる（0.25.0）。スマホからも解錠できます
ブラウザのタブに、ページ内検索とダウンロードの一覧（0.25.0）
Markdown を3通りに見る（0.26.0）。ADR もプレビューで読め、PDF にできます

正直なところ

窓のあるアプリは Windows だけです。macOS 版はありません
会話からの下書きは、会話の記録をファイルに残す Claude Code・Codex・Gemini CLI のタブからだけ作れます
プルリクエストを開けるのは GitHub だけです
下書きは下書きです。保存する前に、必ず人が読んでください

おわりに

AIと開発するようになって、コードを書く時間は減り、決めることが増えました。決めた理由を残すことは、毎回「新人」として来るAIに、仕事を正しく引き継ぐことでもあります。

まずは docs/decisions/ を作り、よく聞かれる決定を1つ書き、CLAUDE.md か AGENTS.md に1行足すところから始めてみてください。会話から下書きするところまで任せたい方は、v0.26.0 からどうぞ。Microsoft Store から入れられます。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up