The MADR 4.0 spec in 15 minutes

What MADR adds over Nygard

Nygard's format gives you five sections in a plain Markdown file: Title, Status, Context, Decision, Consequences. No frontmatter, no machine-parseable header, no formal alternatives section. Fast to fill, near-zero adoption friction. You write a Markdown file and you're done.

MADR 4.0 adds structure that pays off as the corpus grows:

• YAML frontmatter — a machine-parseable header with title, status, date, deciders, and optionally consulted and informed. CI can validate the header without reading the full body; tooling can build indexes and status dashboards from the header alone.
• Formal "Considered Options" section — MADR separates the list of options from the prose rationale. In Nygard's format, alternatives live in Context (about forces and motivations) or Consequences (about outcomes) — often they get buried or skipped. MADR makes them a named section, so a future reader can scan "what else was on the table" in 10 seconds without parsing the reasoning.
• "Decision Outcome" with an explicit "because" clause — the format encourages Chosen option: "[option]", because [justification and its tradeoffs] rather than just naming the choice. The "because" is the load-bearing part of any ADR; making it structurally required means fewer records where the decision is stated but the rationale is missing.
• Pros and Cons sub-lists per option — each Considered Option can have its own Good because... and Bad because... bullet list. When comparing three or four options, this structure is far cleaner than prose paragraphs trying to weave tradeoffs for multiple candidates in sequence.
• "More Information" section — a lightweight way to link back to an RFC, spike, or pull request without trying to fit that context into the main sections. When running an RFC-to-ADR handoff (the step most teams miss), More Information is where the RFC link lives.

The MADR 4.0 template

Here is the minimal MADR 4.0 template. The sections in brackets are prompts, not headings — replace them with actual content. The consulted, informed, Decision Drivers, Pros and Cons, and More Information sections are optional and can be omitted for lightweight decisions.

---
status: accepted
date: 2026-06-05
deciders: [alice, bob]
consulted: [carol]
informed: [team-channel]
---

# [short title of the decision — name the choice, not the problem]

## Context and Problem Statement

[The situation and why it requires a decision. What constraint or goal is
driving the need to choose?]

## Decision Drivers

* [driver 1 — a force, a constraint, a requirement]
* [driver 2]

## Considered Options

* [option 1]
* [option 2]
* [option 3]

## Decision Outcome

Chosen option: "[option 1]", because [justification and its tradeoffs].

### Consequences

* Good, because [positive consequence]
* Bad, because [negative consequence or risk]
* Neutral, because [neither good nor bad]

## Pros and Cons of the Options

### [option 1]

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]

### [option 2]

* Good, because [argument d]
* Bad, because [argument e]

## More Information

[Link to RFC, spike, or PR. Omit if not applicable.]

The frontmatter block is the new part compared to Nygard. status can be proposed, accepted, deprecated, or superseded by [ADR-XXXX]. date is the accepted-or-last-modified date (not the creation date — the commit history has creation date; the frontmatter date tracks the last substantive change). deciders is the list of people who made the call; consulted is people whose input was sought before the decision; informed is downstream notification targets such as a Slack channel or mailing list.

See the MADR template reference page for a worked example with a real decision filled in.

MADR 4.0 vs earlier MADR versions

MADR 3.x used a looser frontmatter schema. The key differences in 4.0:

• tags removed — the 3.x tags field had unclear semantics (some teams used it for decision category, others for keywords, others for team names). MADR 4.0 replaced it with the more precise informed field, which explicitly means "notify these people or channels, do not consult them." If your 3.x files have tags, drop the field during migration.
• deciders formalized as a YAML list — in 3.x, some teams wrote deciders: Alice, Bob (a string) rather than deciders: [alice, bob] (a list). MADR 4.0 specifies the list form; CI validation tools that target 4.0 will reject the string form. The migration script is a one-liner.
• date field semantics clarified — 3.x left date ambiguous (creation date or acceptance date?). MADR 4.0 specifies it as the date the decision was accepted or last substantively changed. Creation date is in git history; the frontmatter date signals "this is when the decision was finalized."
• consulted promoted to frontmatter — in 3.x, the consulted parties were mentioned in prose inside Context. MADR 4.0 promotes consulted to a frontmatter field, enabling tooling to extract the consultation graph (who was consulted across the ADR corpus) and identify decisions where key stakeholders were never involved.

Most teams with fewer than 30 existing 3.x ADRs migrate in a single PR. The migration is mechanical: drop tags, convert string deciders to list form, check for any date values that look like creation dates and update them to acceptance dates. No section content needs to change.

MADR vs Nygard: which to choose

Choose MADR if:

• You plan to publish the corpus as a browsable site — Log4Brains uses MADR natively and the YAML frontmatter is what it reads to build the status index and decider list
• You want CI validation — the GitHub Action for ADR validation has a MADR 4.0 schema target that catches frontmatter typos and invalid status transitions in seconds
• Your team makes decisions across multiple domains (not just architecture) and wants a single format for all of them
• You're building tooling on the corpus — the frontmatter makes parsing fast without needing to read Markdown body content

Choose Nygard if:

• You want zero tooling — a text editor and git is all you need; there's nothing to install and nothing to configure
• You're onboarding engineers who haven't seen ADRs before and want the lowest possible friction; Nygard's five sections fit in a 200-word example and are immediately legible
• Your ADR corpus is small (under 20 records) and unlikely to grow to the scale where tooling matters
• You want to match the format described in most published ADR guidance — Thoughtworks Radar, Michael Nygard's original post, and most engineering culture blogs use Nygard examples

The practical tradeoff: MADR ADRs take slightly longer to fill correctly because the structure is more explicit. Nygard ADRs are faster but require more discipline to include alternatives — nothing in the template requires them, so under-pressure engineers skip them. Over time, a Nygard corpus tends to accumulate records where the Decision section says "we chose X" with no mention of what was considered and rejected. That's the failure mode MADR's Considered Options section prevents.

For a team of three to five engineers who are already ADR-comfortable, MADR is strictly better. For a team where ADR adoption is uncertain, Nygard's lower friction may be the difference between the practice starting and dying on the first PR review comment about frontmatter YAML syntax. See the ADR tooling comparison for the full breakdown across tools.

Tooling that targets MADR 4.0

Three tools form the current MADR ecosystem:

• Log4Brains — generates a browsable Next.js static site from MADR ADRs. Reads YAML frontmatter directly; the web UI shows the status lifecycle, deciders, and the full ADR body as a formatted page. The Log4Brains setup guide covers the full install-and-deploy path including GitHub Pages. Best for teams publishing a public ADR corpus or for platform orgs where non-engineers need to read decisions without navigating git.
• adr-tools (npryce) — the most referenced ADR creation tool, written in Bash. Creates plain Nygard files by default but can be configured with a custom template to scaffold MADR output. The adr new command then fills the template. Most teams using MADR pair adr-tools (for creation) with Log4Brains (for publication) — the two tools have complementary scopes.
• GitHub Action (Peter Evans) — CI step that validates ADR file format, naming conventions, and status transitions. Has a MADR 4.0 schema option. Catches frontmatter typos, missing required fields (status, date, deciders), and invalid status transitions (accepted → proposed is a schema violation; accepted → superseded is valid). Runs in under a second on a 100-file corpus.

The standard MADR setup at scale is: adr-tools for scaffolding new files, GitHub Action for CI validation on every PR, Log4Brains for the publication layer if a web UI is needed. Each tool is independent — you can adopt any one without the others.

How AI chat output maps onto MADR structure

One more angle worth naming explicitly: MADR 4.0's structure makes it the natural output target for automatic decision extraction from AI chat history.

A typical engineer session in ChatGPT or Claude naturally produces most of the MADR sections. The engineer sets up the problem ("we need to choose a job queue library") — that's Context and Problem Statement. They name constraints ("must support Redis, must have retry semantics, must be open source") — those are Decision Drivers. They ask the model to compare options ("compare BullMQ, Bee-Queue, and Kue") — that's Considered Options with a Pros and Cons breakdown. They make a call ("okay, going with BullMQ") — that's Decision Outcome. The rejected options and the reasons they were rejected are explicit in the thread.

The informal reasoning in chat sessions is often richer than hand-written ADRs. There's less incentive to abbreviate when you're thinking out loud to a language model that's asking follow-up questions, compared to when you're writing for a PR review with a mental timer running. The gap is structure: the information is there but not in MADR shape.

The open-source extractor maps chat content onto MADR sections: the setup maps to Context, named constraints to Decision Drivers, compared options to Considered Options, the final call to Decision Outcome, rejected options and reasons to Pros and Cons. The resulting records aren't as polished as hand-written ADRs — some Considered Options descriptions will be brief, some Decision Outcome "because" clauses will be compressed — but they're in MADR format, they're in the corpus, and they're a starting point for promotion to a formal record if the decision turns out to be load-bearing.

This is why MADR 4.0 is the default output format for extraction: its structured sections map more cleanly onto the natural shape of a reasoning session than Nygard's freeform prose sections do. The dogfooding walkthrough shows the full extraction pipeline — 1,200 chats to 38 structured records — and what the MADR output looks like before and after the triage pass. The ChatGPT export guide and Claude export guide have the mechanics of getting the source files.

Per the ADR staleness data, the ceremony cost is the primary reason ADR practices die. Auto-generated MADR records from chat extraction address that directly: they're the 80% of decisions that aren't worth full ADR ceremony, captured anyway, in a format the 20% of decisions that do warrant ceremony already use. The two tiers are compatible because they're the same format at different completeness levels.

To run the extractor against your ChatGPT export or Claude export and get MADR 4.0 output, the quickest path is the open-source extractor — three commands, runs locally, no data uploaded anywhere. If you want the extraction plus triage interface and team sharing, the waitlist is open.

Further reading

• MADR template reference — copy-paste template with a worked example and the YAML frontmatter schema in full
• Nygard ADR template — the five-section plain-text format, with guidance on when Nygard beats MADR
• ADR tooling comparison — adr-tools vs Log4Brains vs adr-log vs hand-rolled, across 12 dimensions
• Log4Brains setup guide — from npm install to GitHub Pages, with the monorepo workspace configuration
• GitHub Action for ADR validation — CI enforcement for MADR 4.0 format, naming, and status transitions
• ADR vs Decision Log vs RFC — when each artifact is the right tool, and the RFC-to-ADR handoff pattern
• Worked ADR example — a real Postgres vs MongoDB decision in both Nygard and MADR format