はじめに
AI開発に任せていて、こんなことありませんか
- AIに「いい感じに直して」と頼んだら、過去の判断を無視した実装 が返ってきた
- AIに毎回「Firebase / Stripe / AI API のキーが設定されていないので動きません」と指摘される。実際はキーをサーバーに入って手で設定したり、GitHub Secrets / GitLab CI/CD Variables / AWS Secrets Manager で管理してるだけなのに、毎回ローカルに無いことを問題扱いされて説明する羽目になる
- 複数のAIツール（Claude Code / Codex / Cursor）でルールが食い違って、どれが正なのか分からなくなる
- 半年前に決めた技術選定の理由を、自分でもAIでも答えられない
自分はぜんぶ経験があります。で、いろいろ調べた末にたどり着いたのが ADR（Architecture Decision Record） でした。
この記事では、ADRって結局なに？ どう運用すれば続くの？ そして AIコーディングと組み合わせると何が起きるのか？ を、最小限のところだけまとめます。
設計ドキュメントとは何が違う？
最初に整理しておくと、ADR は「設計ドキュメント」とも別物です。
| 設計ドキュメント | ADR | |
|---|---|---|
| 目的 | 今のシステム全体像 | 特定の判断の理由 |
| 粒度 | システム単位 | 決定1件 |
| 鮮度 | 常に最新を保つ | 決定時点で固定 |
| 保存場所 | Wiki / Notion | Gitリポジトリ内 |
ADRは「決まった瞬間の判断」を冷凍保存するイメージです。
あとからその判断が覆ったら、ADRは書き換えず 新しいADRを起こして "Superseded by ADR-00XX" と書く。ここが地味に効きます。「あの時はこう考えてたけど、今はこっちにした」という遷移そのものが資産になる。
最小フォーマット
派生形はいくつかありますが、最初は原典の Nygard 形式が一番ラクです。5項目だけ。
# ADR-0007: ディレクトリ構造を機能別 (feature-based) に統一する
## Status
Accepted (2026-05-30)
## Context
当初はファイル種別 (components/ / utils/ / types/) でディレクトリを切っていたが、
1機能の修正で複数ディレクトリを横断する必要があり、
新規メンバーやAIが関連ファイルを見つけにくい状態が続いていた。
## Decision
ディレクトリは機能 (feature) 単位で切る。
`src/features/<機能名>/` 配下に components / hooks / types / utils を配置する。
複数機能で共有するものだけ `src/shared/` に置く。
## Consequences
- ✅ 1機能の修正がほぼ1ディレクトリで完結する
- ✅ AIが関連ファイルを文脈として認識しやすくなる
- ⚠️ 横断的なユーティリティの置き場（shared）に例外ルールが必要
- ⚠️ 既存コードの移行に時間がかかる
これだけ。「Decision」と「Consequences（良い影響も悪い影響も）」を能動態で書く のがコツです。
「〜できる」「〜になる」と言い切る。「〜できるかもしれない」と濁さない。
AIコーディング時代に ADR が効いてくる理由
ここからが本題、というか自分が一番伝えたいところ。
Claude Code や Codex みたいな AI コーディング支援を使うようになってから、ADRの価値が一段上がった という実感があります。理由は5つ。
1. AIに「過去の判断」を文脈として渡せる
AIは指示されたタスクには強いけど、「このプロジェクトが何を避けたいのか」「なぜ今この構成なのか」は知らない。
ADRを docs/adr/ に置いておくと、AIが「この変更って ADR-0007 と矛盾してませんか？」と気づいてくれる確率がぐっと上がります。実際、自分は CLAUDE.md や AGENTS.md に「重要な設計判断は docs/adr/ を参照」と書くだけで、的外れな提案が目に見えて減りました。
2. AIが書くコードの「レビュー基準」になる
AIが提案してきたコードに対して、「これ ADR-0012 に書いた方針と違うんだけど」と人間が即座に判断できる。
レビュー基準が頭の中だけにあると、AIの出力が増えるほど判断疲れします。外部化されたレビュー基準としての ADR は、AI時代にむしろ必要性が上がります。
3. AIをADR執筆のアシスタントにできる
「これからやろうとしている変更について、Nygard 形式で ADR のドラフト書いて」と頼めば、論点の抜けや代替案の検討漏れを補ってくれる。
人間が書くと面倒だった Context や Consequences の網羅性が、AIの助けで一段上がります。書くハードルが下がるので、運用が続きやすくなる という効果がじわじわ効きます。
4. 「コードに現れない決まり事」をAIに渡せる
ここが個人的には一番デカいかもしれない。
普段フロントエンドとバックエンドを触っていて困るのが、コードを読んでも分からないルール の存在です。たとえば:
-
インフラ層 / アプリケーション層 / モバイルアプリ層の 責務分界（このバリデーションはアプリ側、レート制限はインフラ側、みたいな線引き）
-
APIキー・シークレットの管理ポリシー
Firebase / Stripe / AI API のキーはローカルの.envにも置かない。実際の置き場は次のどれか:- 本番サーバーに入って手で環境変数として設定する
- GitHub Secrets（Repository / Environment / Organization）
- GitLab CI/CD Variables（Masked / Protected オプション）
- AWS Secrets Manager / AWS Systems Manager Parameter Store
ローカル環境ではキー未設定やサンプルキーが入っていることが多いので、AIが毎回「キーが無いので動きません」と指摘してくる。これは2つの解き方ができます:
- 新しいサービスを導入するタイミングで ADR に書いておく: 例えば「Stripe を導入する」「Firebase を導入する」と決めた時に、そのADR の中に 「ローカル環境ではキー未設定が正常状態。本番は GitHub Secrets から注入する」 と一行だけ入れておく。これだけで、次にAIがこのプロジェクトを触ったとき、同じ指摘は出なくなる。
-
ルール側 / サブエージェント側で弾く: 同じことは ADR でなくても解決できます。ルールファイル（
CLAUDE.md/.cursor/rulesなど）に直接書く、あるいは レビュー用のサブエージェントやスキルを用意してそこでチェックさせる という選択肢もあります。
ADR が唯一解ではないので、自分のワークフローに合う方を選べばOK。ただし複数のAIツールを併用するなら、最終的にADRを単一ソースにしておく方がラクです。
これらはコード上に書いていないので、AIに「いい感じに直して」と頼むと毎回ルールを踏み外した提案が返ってきます。判断基準を渡さなければAIレビュアーも同じ指摘を繰り返す。
ADR を1本書いておけば、人間レビューもAIレビューも同じ単一ソースを参照できる。
おまけに 「なぜそれを採用しなかったか」（却下した選択肢）も残せる ので、「なぜここで○○を使わないんですか？」とAIが提案してくる無駄も消せます。
5. 複数のAIツールの「共通言語」になる
これも体感としてかなり効いてます。
自分は Claude Code と Codex を両方使うことが多いんですが、AIコーディングツールはそれぞれ独自の設定ファイルを持っています。
| ツール | 設定ファイル |
|---|---|
| Claude Code | CLAUDE.md |
| Codex / GPT 系エージェント | AGENTS.md |
| Cursor | .cursor/rules |
| GitHub Copilot | .github/copilot-instructions.md |
同じルールを各ファイルに重複コピペするのは、書くのもしんどいし、ルールが食い違ったらどっちが正なのか分からなくなる。CLAUDE.md を更新したのに AGENTS.md の更新を忘れて、Codex だけ古いルールで動いてた…みたいなことが普通に起きます。
そこで、真の判断基準は docs/adr/ に置くと決めてしまって、各ツールの設定ファイルからは「重要な設計判断は docs/adr/ を参照」と一行書くだけにする。すると:
- Claude Code でも Codex でも、同じ判断基準 で動いてくれる
- ルールを更新するときは ADR 1ファイルだけ書き換えればOK
- 「Claude では通った提案が Codex では弾かれる」みたいなブレが減る
- 新しいAIツールを試すときも、
docs/adr/を参照させるだけで即立ち上げ可能
要は ADR が AI 間の "single source of truth"（単一ソース） になる、という使い方です。
チーム内で複数AIを併用する流れは今後も増えると思っているので、ここで一度「ベンダー非依存のチームルール置き場」を作っておくと、ツールの乗り換えや追加が一気にラクになります。
AIと組み合わせる時の注意点
いいことばかり書きましたが、当然落とし穴もあります。むしろこっちが本題かもしれない。
1. AIに事後生成させると一気に形骸化する
「決まった後に AI に ADR 書かせとこう」が一番危険。
当時の論点や却下された代替案の生々しさが抜けて、「正解ぽいけど中身がない」ADR が量産されます。Olaf Zimmermann の言う "Fairy Tale" アンチパターン（Pros しか書かない / 代替案を1つしか検討しない）に、AI生成ADRはハマりやすい。
→ 判断の最中に、人間が論点を吐き出してAIに整形させる くらいの分担がちょうどいい。
2. AIが過去ADRを「絶対」として扱ってしまう
ADRは「その時点での判断」であって、永遠の正解ではない。でもAIに「ADRを参照して」と言うと、古いADRを盲信して、状況が変わった今の文脈に合わない提案を返してくる ことがある。
→ Deprecated / Superseded のステータス管理を怠ると、AIにとっても人間にとっても地雷になります。ステータスの鮮度はAI時代のほうがシビア。
3. AIに書かせたあと、必ず一度人間が手を入れる
ADRの下書きはAIに任せてOK、というかむしろアシスタントとして使い倒した方がいいです。論点の整理も網羅性チェックもAIの得意分野。
ただ、生成された文章をそのままコミットしない。最後に一度人間が読み返して、2〜3箇所だけ書き換える。これだけで読みやすさが全然変わります。
具体的には:
- 「重要です」「以下の点が挙げられます」「総じて言えば」みたいなAI特有の前置きや締めを削る
- 「〜することができます」を「〜できる」に短縮する
- 体験談や違和感のある部分は 自分の言葉に言い換える
ADRは最終的に 人間が判断を引き継ぐためのもの なので、AIの草稿 + 人間の最終チェック、というのがちょうどいい分担です。
ゼロから人間が書く必要はないけど、ゼロチェックでマージするのも違う、という間くらい。
4. AIが書きすぎる
放っておくとAIは丁寧に書きすぎます。3,000字のADRが量産されると誰も読まなくなる。
「1ファイル500字目安、超えたら粒度がデカすぎるサイン」 を人間側のガードレールとして持っておくと良いです。
導入してよかったこと（AIと関係なく効いた話）
AI関連を抜きにしても、2つ効きました。
1. 半年後の自分が助かる
ADRを書いておくと、しばらく経ってから戻ってきても「なんでこうしたか」が即わかる。未来の自分への手紙 として効きます。AIに聞いても答えが出ない（コードに書いてないから）情報なので、これは ADR にしか残せない価値。
2. 書く過程で論点がはっきりする
これは意外な副作用でした。Context と Consequences を書こうとすると、「あれ、自分この観点ちゃんと考えてなかったな」と気づくことが結構ある。書くこと自体が思考の道具になります。AIに下書きさせて、自分でツッコミを入れる、というやり方とも相性がいい。
まとめ
- ADR は「重要な設計判断の理由」を残す短い文書
- Nygard形式の5項目（Status / Context / Decision / Consequences）から始めればOK
- 一度確定した判断は書き換えない。覆ったら新ADRを起こして "Superseded by ADR-XXX" でリンク
- AI時代のメリット: 過去判断をAIに渡せる / レビュー基準になる / 執筆アシスタントになる / コードに現れない決まり事を渡せる / 複数AIツールの共通言語になる
- AI時代の注意点: 事後生成・古いADR盲信・AI文体そのままコミット・書きすぎ。AI下書き + 人間の最終チェック がちょうどいい分担
設計の"なぜ"が流れていく感じがあるなら、騙されたと思って3本書いてみてください。AIと組んでいるなら、なおさら。
参考リンク
- Documenting Architecture Decisions — Michael Nygard (原典)
- Architecture Decision Record — Martin Fowler bliki
- adr.github.io — ADRコミュニティのハブ
- adr/madr — MADR公式
- joelparkerhenderson/architecture-decision-record — ADRの総合ガイド集
- npryce/adr-tools — bash製の採番CLI
- How to create ADRs — and how not to (Olaf Zimmermann) — アンチパターン集