コンテンツにスキップ
pentaglyph

MADR v3.0

MADR（Markdown Architecture Decision Records） はコミュニティでメンテナンスされている ADR テンプレートで、2011 年の Michael Nygard ADR パターン を Markdown 親和的なタイトな形に蒸留したものです。v3.0 が現行の安定版仕様です。

正本リンクhttps://adr.github.io/madr/
メンテナADR コミュニティ（GitHub: adr/madr）
キット内の hometemplate/docs/arc42/09-decisions/
pentaglyph 内のスロット5 つ中 #3 ― 判断層

MADR は何を解決するのか

Section titled “MADR は何を解決するのか”

判断記録がないと、すべてのアーキテクチャ選択は同じ失敗パターンを辿ります:

  1. 通話で決定。メモなし
  2. 半年後、誰かが「X を選んだのって、なんでだっけ?」と聞く
  3. 誰も覚えていない。議論がゼロから蒸し返される
  4. チームは同じ答えに再収束する（時間の無駄）か、間違って違う選択をする（暗黙の不整合）

ADR がこのループを断ち切ります。1 決定、1 ファイル、1 日付、accept 後は immutable。半年後、答えは grep 可能。

MADR v3.0 構造

Section titled “MADR v3.0 構造”

MADR ファイルには次のセクションがあります:

# <タイトル ― 動詞句であって名詞ではない>


* Status: Proposed | Accepted | Rejected | Superseded by ADR-NNNN
* Date: YYYY-MM-DD
* Deciders: [名前のリスト]


## Context and Problem Statement
[2〜4 文: forcing function + decision space]


## Decision Drivers
* driver 1
* driver 2


## Considered Options
* Option A
* Option B
* Option C


## Decision Outcome
Chosen option: "Option B"、なぜなら [justification]。


### Consequences
* Good: [良い結果]
* Bad: [受け入れたコスト]


## Pros and Cons of the Options
[option ごとの深掘り]

Considered Options + option ごとの pros/cons セクションが MADR を Nygard 原典と区別する点です ―― 選んだ option だけでなく、代替案を名指して justify することを強制します。

pentaglyph での MADR の使い方

Section titled “pentaglyph での MADR の使い方”
template/docs/arc42/09-decisions/
├── 0000-template.md
├── 0001-<title>.md
├── 0002-<title>.md
└── ...

ルール:

  • 1 ADR 1 ファイル。ファイル名は NNNN-<kebab-title>.md、連続 4 桁、ギャップなし
  • Status は Proposed で開始。チームレビュー後にのみ Accepted に
  • Accepted 本文は immutable。新 ADR で supersede。歴史を編集しない
  • 関連 ADR を相互リンク（Supersedes: 0007 / Superseded by: 0042）

運用の深掘りは ADR の書き方 を参照。

ADR を書くべきとき

Section titled “ADR を書くべきとき”

書くのは:

  • 他の誰かが本気で検討しそうな、名前のある代替案がある
  • non-obvious なトレードオフがある
  • 半年後に「なぜ Y ではなく X?」と聞かれそう
  • 決定が 2 つ以上のモジュールに影響する

ADR を書かないのは: 変数名、フォーマッティング、「ライブラリ X を使う」で現実的な代替案がない場合。

MADR vs 他の ADR フォーマット

Section titled “MADR vs 他の ADR フォーマット”
フォーマット年区別する特徴
MADR v3.02024Considered Options + option ごと pros/cons が必須
Nygard 原典2011ミニマル: Context / Decision / Status / Consequences
Y-statements20181 文 ADR（Zimmermann）
arc42 §9 ネイティブ―ただのセクション、固定形なし

pentaglyph は MADR v3.0 を選びます。 Alternatives の規律を最も厳格に強制しつつ、ミニデザイン doc にならないためです。

正本リンク

Section titled “正本リンク”

関連

Section titled “関連”