Skip to content
pentaglyph

MADR v3.0

MADR (Markdown Architecture Decision Records) is a community-maintained ADR template that distills the original 2011 Michael Nygard ADR pattern into a tighter, Markdown-friendly form. Version 3.0 is the current stable spec.

Authoritative sourcehttps://adr.github.io/madr/
MaintainerThe ADR community (GitHub: adr/madr)
Local home in the kittemplate/docs/arc42/09-decisions/
Slot in pentaglyph#3 of 5 — the decision layer

What problem does MADR solve?

Section titled “What problem does MADR solve?”

Without a decision record, every architectural choice has the same failure pattern:

  1. Decision made on a call. No notes.
  2. Six months later, someone asks “why did we choose X again?”
  3. Nobody remembers. The argument is re-litigated from scratch.
  4. The team either re-converges on the same answer (wasted hours) or accidentally picks a different one (silent inconsistency).

ADRs break this loop. One decision, one file, one date, immutable once accepted. Six months later, the answer is grep-able.

The MADR v3.0 structure

Section titled “The MADR v3.0 structure”

A MADR file has these sections:

# <Title — verb phrase, not a noun>


* Status: Proposed | Accepted | Rejected | Superseded by ADR-NNNN
* Date: YYYY-MM-DD
* Deciders: [list of names]


## Context and Problem Statement
[2-4 sentences: forcing function + decision space]


## Decision Drivers
* driver 1
* driver 2


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


## Decision Outcome
Chosen option: "Option B", because [justification].


### Consequences
* Good: [positive outcomes]
* Bad: [costs accepted]


## Pros and Cons of the Options
[per-option deep dive]

The Considered Options + per-option pros/cons section is what distinguishes MADR from Nygard’s original — it forces you to name and justify the alternatives, not just the chosen option.

How pentaglyph uses MADR

Section titled “How pentaglyph uses MADR”
template/docs/arc42/09-decisions/
├── 0000-template.md
├── 0001-<title>.md
├── 0002-<title>.md
└── ...

Rules:

  • One ADR per file. Filename: NNNN-<kebab-title>.md, sequential 4-digit numbering, no gaps.
  • Status starts at Proposed. Becomes Accepted only after team review.
  • Accepted bodies are immutable. Supersede with a new ADR; never edit history.
  • Cross-link related ADRs (Supersedes: 0007 / Superseded by: 0042).

See How to write an ADR for the operational deep dive.

When to write an ADR

Section titled “When to write an ADR”

Write one if:

  • The decision has named alternatives that someone else would seriously consider.
  • The decision has non-obvious trade-offs.
  • Six months from now someone might ask “why X instead of Y?”
  • The decision affects more than one module.

Do not write an ADR for variable names, formatting, or “use library X” when there were no real alternatives.

MADR vs. other ADR formats

Section titled “MADR vs. other ADR formats”
FormatYearDistinguishing feature
MADR v3.02024Required Considered Options + per-option pros/cons
Nygard original2011Minimal: Context / Decision / Status / Consequences
Y-statements2018One-sentence ADRs (Zimmermann)
arc42 §9 native—Just a section; no fixed shape

Pentaglyph picks MADR v3.0 because it forces the most rigorous Alternatives discipline without becoming a mini design doc.

Authoritative references

Section titled “Authoritative references”

See also

Section titled “See also”