Post
JA EN

DDD開発でADRをどう使うか——メリット・デメリットと場面別の実践

Posted
By
40 min read
DDD開発でADRをどう使うか——メリット・デメリットと場面別の実践
  • 想定読者： DDD（ドメイン駆動設計）でプロジェクトを進めていて、設計判断の記録にADRを使うか迷っている、あるいは使い方を固めたいエンジニア・テックリード。AIアシスト開発をしている人には、その勘所も併せて示す
  • 前提知識： DDDの基本概念（Bounded Context、ユビキタス言語）。ADR（Architecture Decision Record）が「設計判断を1ファイル1決定で残す手法」だと知っていると読みやすい
  • 所要時間： 約22分

概要

DDDとADRをどう組み合わせるか——これは「相性が良いから全部記録しよう」では失敗する。DDDとADRは、手放しで相性が良いわけではない。ADRは「点の決定を打って残す」スナップショット型なのに対し、DDDの戦略的設計（境界、ユビキタス言語）は「学びながら育てるモデル」で、粒度も思想もぶつかる。

だが、両者が噛み合う層は確かにある。境界の引き方、コンテキスト間の関係、却下した代替——こうした「戦略的で、重くて、後から理由を問われる決定」に絞れば、ADRはDDDの弱点をちょうど埋める。DDDネイティブな記録手段（Context Map、Bounded Context Canvas など）は「いまどうなっているか（What）」を表すのは得意だが、「なぜそうしたか・何を捨てたか（Why）」を残す役割は手薄だからだ。

本記事は、DDD開発でADRを使うときのメリットとデメリットを正直に並べ、その上で具体的な使い方——何をADRにする／しないか、AGENTS.md などの制約ファイルとどう分担するか、新規大規模・小規模・バグフィックス・エンハンスの場面ごとにどう変えるか——を示す。結論を一言で言えば、「ADRは戦略的な重い決定だけに絞り、現在の状態はコードとDDDツールに任せる」。この線引きさえ守れば、ADRは増えすぎて形骸化することも、書いたのに読まれず死蔵することもない。そして——ADRの起票・整形・supersede 処理・整合性チェックといった管理作業そのものはAIに任せられる。人が握るべきは、戦略的な決定と「Whyの妥当性検証」だけだ。

DDD+ADRのメリット

ADRがDDDに対して提供する価値は、主に4つだ。

1. 境界・関係の「なぜ」が残る。 DDDで最も失われやすいのが、「なぜこの境界にしたか」「なぜこのコンテキスト間関係（Conformist / ACL など）を選んだか」という理由だ。境界そのものはコードのディレクトリ構造に残るが、却下した代替や当時の制約は残らない。半年後に「なぜ清掃とフロント業務を別コンテキストにしたんだっけ」となったとき、ADRがあれば即座に当時の判断を思い出せる。

2. 引き直しが速くなる。 DDDの境界は仮説であり、進めながら見直すのが本来の姿だ。ADRには「削除せず、新しいADRで上書きする（superseded by ADR-NNN）」という append-only の原則がある12。境界を引き直すとき、「なぜ最初その境界にしたか」が残っていれば、当時の前提と今の状況の差分だけを見て判断できる。残っていないと「そもそもなぜ」の考古学から始まり、引き直しが重くなる。

3. 引き継ぎとレビューの共通根拠になる。 新しくチームに入った人、コードレビューをする人、本番化を引き継ぐ人——彼らが「なぜこうなっているか」を毎回口頭で聞かずに済む。決定の理由が文書で参照できることが、レビュー摩擦を下げる2。

4. （AI開発の場合）AIが過去の決定を勝手に覆さなくなる。 AIアシストでコードを書かせていると、AIは流暢に「もっと良い設計」を提案し、苦労して引いた境界を黙って作り直すことがある。CLAUDE.md や AGENTS.md に「設計変更の前にADRを確認せよ」という1行を足し、決定をADRとして参照可能にしておくと、AIは「この境界はADR-005で意図的にこう決めた」と気づいて、勝手な上書きを思いとどまる2。決定の履歴が、AIに対するソフトなガードレールとして働く。

DDD+ADRのデメリット・相性の悪さ

一方で、ADRをDDDに持ち込むと生じる摩擦も正直に挙げておく。これを知らずに「全部ADRにしよう」とすると事故る。

1. 粒度がずれている。 ADRは「点の決定を1ファイル1決定で確定して残す」。だがDDDの戦略的設計は「連続的に育つモデル」だ。accepted というステータスの確定感と、「まだ仮説です」というDDDの態度は、本来そりが合わない。ユビキタス言語の個々の用語や、集約の細かいフィールドまでADRにすると、変化のたびに supersede が多発し、台帳がノイズだらけになる。

2. 二重管理でズレる。 ADRに「現在こうなっている」という状態まで書くと、コードが変わるたびにADRが古くなる。逆に、現在の制約を書く AGENTS.md 側に決定の経緯まで書き込むと、ファイルが肥大化する。ADRとコード（および制約ファイル）の同期を怠ると、古い記述が現実と食い違い、かえって混乱を生む。

3. 書く手間がある。 ADRを書くのは「誰も時間のない追加の一手間」になりがちだ3。プロジェクトの速度を優先する場面で、決定のたびにADRを起こしていると、記録作業が本流を止める。

4. 過剰になると形骸化する。 「すべての決定をADRに」と力むと、件数が膨れ、誰も読まなくなる。ADRの件数をKPIにした瞬間に、中身のない記録が量産される（Goodhartの法則4）。

これらのデメリットは、いずれも「ADRを使う範囲を絞る」ことで回避できる。次節でその線引きを示す。

DDDネイティブ手段との棲み分け——What と Why

「だったらDDDの道具だけで決定を残せないのか」という疑問が出る。実際、DDDには記録の道具立てが揃っている。だが、そのほぼすべてが「いまどうなっているか（What）」を表すもので、ADRが担う「なぜ（Why）」の穴は埋めない。

DDDネイティブ手段何を残すかWhy の穴
Context Map5境界間の関係（Conformist / ACL / Partnership 等）の現在図「なぜその関係を選び、何を却下したか」は残らない
Bounded Context Canvas6各境界の責務・UL・ビジネスルール・前提・未解決問題ルールが「何か」は残すが、理由・却下案・変更履歴は持たない
Core Domain Charts7core / supporting / generic の戦略分類現在状態の可視化であり、決定の理由・履歴ではない
ユビキタス言語の用語集用語の現在の合意「なぜその語に決めたか」は残らない

唯一、whyに正面から踏み込むのが Cyrille Martraire の Living Documentation8 だが、これは「アノテーションで決定の根拠をコードに埋め込む」アプローチで、ADRの「独立した時系列の決定台帳」とは形が違う（Martraire 自身、ADRを置き換えるのではなく包含する立場だ）。

つまり棲み分けはこうなる。

1
2
3

Context Map / Canvas / Core Domain Charts / 用語集  →  いまのモデル（What）
コード + テスト                                      →  現在の挙動（What）
ADR                                                  →  なぜ・却下案・履歴（Why）

Zennで議論されている言い方2が端的だ——「ADRは『なぜ（why）』を保つが、『いま何が起きているか（now）』には答えない。現在の仕様はコードとテストに置くべきだ」。DDDツールが現在の構造を、コードが現在の挙動を、ADRが決定の理由を担う。役割を混ぜないことが、デメリットを避ける土台になる。

具体的な使い方

何をADRにする／しないか

これが最も重要な線引きだ。基準はシンプルにする2。

ADRにする：

  • 覆すのが高コストな決定（境界の引き方、データストア選定など）
  • 複数の代替を本気で比較した決定（却下した案こそ価値がある）
  • 3か月後に理由が自明でなくなりそうな決定
  • 公開仕様やコンテキスト境界に影響する決定

ADRにしない：

  • バグ修正、単純なリファクタ
  • 自明な技術選択（議論の余地がないもの）
  • 可逆な実装詳細（後でいくらでも変えられるもの）
  • 単一モジュール内にとどまるローカルな決定

判断に迷ったら、このフローで切る。

flowchart TB
    A["設計上の決定が発生"]
    B{"可逆で<br>局所的か？"}
    C["ADRは不要<br>(コードとテストで足りる)"]
    D{"複数の代替を比較した<br>or 3か月後に理由が<br>自明でなくなるか？"}
    E["ADRを書く<br>(却下案と理由を残す)"]
    A --> B
    B -->|"はい"| C
    B -->|"いいえ"| D
    D -->|"いいえ"| C
    D -->|"はい"| E

フォーマット

Michael Nygard の古典的フォーマット1、あるいはその軽量版（MADR-lite）2で十分だ。

1
2
3
4
5
6

# ADR-NNN: <決定のタイトル>
## Status: accepted / superseded by ADR-MMM
## Context: どんな状況で、何を決めねばならなかったか
## Decision: 何を決めたか
## Alternatives considered: 検討して却下した案と、その理由
## Consequences: 良い影響 / 悪い影響 / トレードオフ / フォローアップ

DDD文脈で特に効くのは Alternatives considered だ。「なぜ Partnership ではなく Conformist にしたか」「なぜ単一集約に統合せず2つに分けたか」——却下の理由こそ、後の引き直し判断を速くする。

AGENTS.md / CLAUDE.md との分担

AIアシスト開発をしているなら、ADRと制約ファイルの分担を意識する。AGENTS.md は「いまの制約（What）」を毎ターンAIに渡し（push型）、ADRは「なぜそうしたか（Why）」を必要なときに引かれる（pull型）かたちで残す。ユビキタス言語の禁則や不変条件は AGENTS.md に現在形で短く、その決定の経緯と却下案はADRに——と振り分ける。両者を混ぜると、AGENTS.md が経緯で肥大化するか、ADRが現状とズレる。

なぜ AI 時代にこの分担が効くのか、そもそも「AIがADRを読む」とは何が起きているのか——その背景と裏付けは、別記事 AI時代にADRが再評価される理由 で論考としてまとめた。本記事は使い方に絞る。

supersede の使い方

境界や関係を引き直すときは、元のADRを編集せず、新しいADRで上書きする。元ADRの Status を「superseded by ADR-NNN」に変え、新ADRに「なぜ引き直すか（当時の前提と今の差分）」を書く。これで決定の履歴が残り、「同じ議論を蒸し返す」ことを防げる。

ADRの管理はAIに任せる——ただしWhyの検証は人が握る

決定が高速で量産される現場では、ADRを書く手間がボトルネックになる。ここは思い切って、ADRの「管理」をAIに任せるのが現実的だ。AIに委ねられるタスクは広い——

  • 起票：コミットやPRから「これは記録に値する決定だ」と検知し、ADR化を提案する
  • 初稿生成：差分（変更内容・コミットメッセージ）から Context / Decision / Consequences を埋める3
  • 整形と採番：フォーマット統一、連番付与、作成日時・モデル・セッションIDなどのメタデータ付与（これを標準化した Agent Decision Records9 のような枠組みもある）
  • supersede 処理：境界を引き直したとき、旧ADRの Status 更新と相互リンク張りを行う
  • 整合性チェック：ADRと現在のコード／AGENTS.md の食い違いを検出する
  • 参照応答：「なぜXにしたか」と問われたら、該当ADRを引いて答える

ここまでをAIが回せば、ADRは「書く手間で放置される文書」から「自動で維持される台帳」に変わる。決定の検知から採番・supersede・整合性チェックまで、定型作業はAIのほうが速く、抜けがない。

だが、AIに任せてはいけない一線がある。 AIが差分から書けるのは「何を変えたか」までだ。「なぜその案を選び、他を却下したか」は差分に現れない人間の判断であり、AIに書かせれば推測で埋められる。前述したデメリットの最も危険な形がこれだ——もっともらしいが実際とは違うWhyが、レビューを素通りして台帳に固定され、後の引き継ぎ判断がその嘘のWhyを前提に下される。だから分担はこう引く——管理（起票・整形・採番・supersede・整合性チェック・参照）はAIに、戦略的な決定そのものと「Whyの妥当性検証」は人に。AIが台帳を回し、人は要所だけ監督する。この運用の技術的背景と限界は、論考記事で詳しく扱う。

レビューがボトルネックにならない書かせ方

「AIが管理、人がWhyを検証」にすると、今度は人のレビューが新たなボトルネックになりかねない。決定が量産されるほど、検証すべきADRも増えるからだ。鍵は、AIにレビューしやすい形で書かせること。レビューの速さは中身より「書き方」で大きく変わる。

実証もある（ADRそのものではなくPR説明の研究だが）。AI生成のPR説明を分析した研究（18,256件）では、AIが書き、人が補完した説明はレビュー時間が短く、マージされやすかった10。一方でLLMは放っておくと冗長に流れる傾向（verbosity bias）があり、「簡潔に」と頼むだけでは効きにくい11。だから構造で縛るのが現実的だ。具体的には、AIに次の形を守らせる。

  • 構造を固定する。 自由記述させず、テンプレートに沿わせる。決定を1文に構造化する Y-statement12 が好例だ——「In the context of 文脈, facing 課題, we decided for 採用案 and against 却下案, to achieve 目的, accepting that トレードオフ」。文脈・採用案・却下した案・トレードオフが1文に収まる。
  • 結論と理由を先頭に置く。 レビュアーが「なぜ?」を推測せずに済む。冒頭の1〜2文で「何を・なぜ」を言い切らせる。
  • 却下案を1行ずつ並べる。 人がWhyを検証するのは、この「却下した案とその理由」が妥当かの一点だ。箇条書きにしておけば、レビューはそこだけ見れば済む。
  • 詳細はリンクで逃がす。 本文は短く保ち、長い議論や該当コードはリンク参照にする。
  • AIの初稿を100%採用しない。 whyの部分は人が補う前提で扱う。前掲の研究でレビュー時間が短くなったのは、まさにAIの下書きに人が手を入れたケースだった10。

要は、AIには「人の目をWhy検証の一点に集められる形」で書かせる。Y-statement の「against（却下案）」1行を見れば妥当性を判断できる——そういう構造にしておけば、管理をAIに委ねても人のレビューはボトルネックになりにくい。レビュー対象が大きい・冗長だと人ほど見逃しやすい、というコードレビュー側の定量的な裏付けは 論考記事 にまとめた。

場面別の使い分け

同じDDD+ADRでも、プロジェクトの性質でADRの厚みは変えるべきだ。4つの場面で示す。

新規・大規模プロジェクト

最も手厚くADRを使う場面。Event Storming などで戦略設計を固めたら、その成果から戦略ADRを起こす——境界の分割、ユビキタス言語の重要な決定、コンテキスト間関係、技術スタック選定。数本〜十数本になる。架空のホテル予約システムで、7フェーズの裏に並走する10本のADRを実演した 別記事 が、この場面の具体例だ。

小規模プロジェクト

境界が1〜2個しかないなら、ADRは数本で足りる。MADR-lite で「なぜこの2つに分けたか」「なぜこのライブラリを選んだか」程度を軽く残す。ここで大規模と同じ厚みのADRを書こうとすると、デメリット（手間・過剰化）だけが効いてくる。「フルの仕様駆動開発はやりすぎ、決定の理由だけ軽く残す」という発想2が、この規模にちょうど合う。

バグフィックス

原則、ADRは書かない。 バグ修正は「可逆・自明・局所」のどれかに当たることが多く、前述の判断フローで「不要」に落ちる。例外は、バグの根本原因が過去の設計判断にあり、その判断自体を変える場合だ。このときは「なぜ元の設計が問題だったか」をADRに残す——多くの場合、それは既存ADRの supersede になる。「修正した」ことではなく「設計方針を変えた」ことが記録に値する。

エンハンス・機能追加

境界が動くかどうかで分岐する。

  • 境界が動かない（既存コンテキスト内に機能を足すだけ）→ ADR不要。コードとテストで足りる。
  • 境界が動く（新しいコンテキストを追加する、既存の境界を引き直す）→ ADRを書く。新コンテキストの追加なら新規ADR、境界の引き直しなら supersede。前掲の実演記事では、β運用中に「団体予約」コンテキストを新設した決定（新規ADR）と、フロント業務／清掃の境界を引き直した決定（supersede）が、まさにこの場面に当たる。

判断軸は一貫している——「ドメインの構造に関わる決定か、実装の中で閉じる決定か」。前者だけがADRに値する。

まとめ

DDDとADRは手放しで相性が良いわけではない。粒度も思想もぶつかる。だが、戦略的で重い決定にだけ絞れば、ADRはDDDの弱点（「なぜ」が残らない）をちょうど埋める。

  • メリット：境界・関係の理由が残る／引き直しが速い／引き継ぎ・レビューの共通根拠／（AI開発なら）AIのガードレール。
  • デメリット：粒度ミスマッチ／二重管理のズレ／書く手間／過剰化による形骸化。いずれも「範囲を絞る」ことで回避できる。
  • 棲み分け：現在の状態（What）はコードとDDDツール（Context Map・Canvas など）に、決定の理由（Why）はADRに。混ぜない。
  • 何をADRにするか：覆すのが高コスト／複数の代替を比較した／理由が後で自明でない／境界に影響する決定だけ。バグ修正・自明な選択・可逆な実装詳細は書かない。
  • 場面別：新規大規模は手厚く、小規模は数本、バグフィックスは原則書かない、エンハンスは「境界が動くときだけ」。

ADRは、書くこと自体が目的ではない。戦略的な決定の理由を、後から人とAIが引けるかたちで残す——その一点に絞れば、DDD開発の強い味方になる。

関連記事

このテーマに関連する他の記事もご覧ください：

参考資料

本文中の引用番号に対応する参考資料を番号順に記載しています。

  1. Documenting Architecture Decisions - Michael Nygard, Relevance / Cognitect (2011-11-15). ADRの発祥。Status / Context / Decision / Consequences 形式。adr.github.io で公式ハブ化。【信頼性: 高】 ↩︎ ↩︎2

  2. A Prescription for SDD Fatigue: Recording Architectural Decisions with ADRs in the AI Era - Kosk, Zenn (2026). 「ADRはwhyを保つがnowには答えない」「いつ書くか／書かないか」の基準、MADR-lite、supersede、「設計変更前にADRを確認」のCLAUDE.mdルール。【信頼性: 中】（実務家ブログ） ↩︎ ↩︎2 ↩︎3 ↩︎4 ↩︎5 ↩︎6 ↩︎7

  3. From Stale Docs to Living Architecture: Automating ADRs with GitHub + LLM - Iraj Hedayati, Medium (2025-09-14). PRの差分からLLMがADR初稿を生成し、人がレビュー・refine するワークフロー。【信頼性: 中】（実務家ブログ） ↩︎ ↩︎2

  4. ADR / Pitch / キックオフメモの実装ガイド ─ 「なぜ書くか」から運用設計まで - 本ブログ. ADRの一般運用論（1ファイル1決定、連番不変、”やらない”も書く、増えすぎ問題、件数KPI化のGoodhart暴走）。 ↩︎

  5. Context Mapping in Domain-Driven Design - Avanscoperta（DDDコミュニティ）. Bounded Context 間の関係（Conformist / ACL / Partnership 等）を可視化・文書化。関係パターンは残すが選択の理由は残らない。【信頼性: 中〜高】 ↩︎

  6. Bounded Context Canvas - ddd-crew（Nick Tune ほか）. 各境界を設計・文書化するテンプレート。Business Decisions / Assumptions / Open Questions 欄を持つが、決定の理由・却下案・変更履歴は明示的には残さない。CC BY 4.0。【信頼性: 中〜高】 ↩︎

  7. Core Domain Charts（Nick Tune） - Nick Tune（解説: esilva.net, 2023）. ケイパビリティを core / supporting / generic と複雑さ・差別化度で可視化する戦略ツール。現在状態の可視化であり、決定ログではない。【信頼性: 中】 ↩︎

  8. Living Documentation: Continuous Knowledge Sharing by Design - Cyrille Martraire, Pearson / Addison-Wesley (2019). ISBN 9780134689418. アノテーションで決定の根拠を残す手法を扱い、「ドキュメントは対象物そのもの＝コードに置く」思想を展開。ADRを置き換えず包含する立場。【信頼性: 高】（専門家の単著） ↩︎

  9. Agent Decision Records (AgDR) - me2resh, GitHub (2025). AIエージェントの自律決定をADRとして記録する拡張標準。作成主体=AI、必須メタデータ（モデル識別子・セッションID・timestamp）、status=proposed / executed / superseded、hook/skill/promptで自動化。ADRの管理をAIに任せる運用の発展形。【信頼性: 中】 ↩︎

  10. Generative AI for Pull Request Descriptions: Adoption, Impact, and Developer Interventions - Tao Xiao, Hideaki Hata, Christoph Treude, Kenichi Matsumoto, PACMSE (2024, DOI: 10.1145/3643773). AI生成PR説明 18,256件を分析。AIが書き人が補完した説明はレビュー時間が短く、マージされやすい。※PR説明であってADRではない（ADRへは類推）。【信頼性: 高】 ↩︎ ↩︎2

  11. Concise Thoughts: Impact of Output Length on LLM Reasoning（ほかLLM出力長制御研究） - (2024-). LLMは verbosity bias（冗長への系統的バイアス）を持ち、長さ指示に従いにくい。簡潔化には「簡潔に」という指示より、構造（テンプレート）での制約が有効。【信頼性: 中〜高】 ↩︎

  12. Architecture Decision Record Template: Y-Statements - Olaf Zimmermann (SATURN 2012). 決定の文脈・採用案・却下案・トレードオフを1文（1段落）に構造化するADR形式。「各決定を1スライドに収められるか」という要請が発端。MADR / Nygard と並ぶ主要テンプレート。【信頼性: 中〜高】 ↩︎

AI・テクノロジー
DDD ADR 設計 アーキテクチャ 意思決定 AGENTS.md
This post is licensed under CC BY 4.0 by the author.