Topic: madr adr template
MADR (Markdown ADR) Template Explained
MADR is the Markdown-Any-Decision-Record format — a structured, machine-readable evolution of Nygard's original ADR. Here's the 4.0 template, the YAML frontmatter, and a one-paragraph view of why MADR exists when "ADR" already does.
TL;DR
MADR adds YAML frontmatter with structured metadata (status, date, deciders, consulted, informed) on top of a Nygard-style body. The headings are slightly renamed (Decision Drivers instead of "Forces", Considered Options instead of "Alternatives") so tooling can parse them reliably. Use MADR when you want machine-readable ADRs — exporters, dashboards, audits.
The MADR 4.0 template
One file per decision, named NNNN-short-slug.md in docs/decisions/. The frontmatter is the part that distinguishes MADR from a free-form Markdown ADR; tooling depends on it being well-formed.
---
status: "accepted"
date: 2026-04-24
decision-makers: ["@your-handle", "@reviewer-1"]
consulted: ["@subject-matter-expert"]
informed: ["@team-channel"]
---
# Use Postgres over MongoDB for the v1 datastore
## Context and Problem Statement
What forces are at play? What problem are we trying to solve?
2-4 sentences of context — team size, scale assumptions, deadlines.
End with the question the decision answers.
## Decision Drivers
* <driver 1, e.g. "team has Postgres operational experience">
* <driver 2, e.g. "data is relational">
* <driver 3, e.g. "compliance requires point-in-time recovery">
## Considered Options
* Postgres
* MongoDB
* DynamoDB
## Decision Outcome
Chosen option: "Postgres", because it scores highest on the
decision drivers above and the team can operate it on day one.
### Consequences
* Good, because we get strict schemas and SQL.
* Good, because Postgres has mature replication tooling.
* Bad, because we lose the schema flexibility a document store offers.
* Neutral, because read performance is comparable for our workload.
### Confirmation
Reviewed at the next quarterly architecture sync; the migration plan
in PR #341 implements this decision.
## Pros and Cons of the Options
### Postgres
* Good, because relational with strong consistency
* Good, because team experience
* Bad, because vertical scale ceiling
### MongoDB
* Good, because flexible schemas
* Bad, because operational unfamiliarity
* Bad, because the v1 data model is genuinely relational
### DynamoDB
* Good, because zero-ops
* Bad, because vendor lock-in is a board-level concern
* Bad, because secondary-index limitations don't match our query patterns
## More Information
* Linked PR: #341
* Original chat: <ChatGPT / Claude conversation URL>
* Supersedes: —
The frontmatter fields, explained
| Field | Required | Notes |
|---|---|---|
status | yes | One of: proposed, rejected, accepted, deprecated, superseded by [ADR-NNNN](nnnn-…md). Lowercase by convention; tooling matches case-sensitively. |
date | yes | ISO 8601 (YYYY-MM-DD). The decision date, not the file-creation date. |
decision-makers | recommended | YAML list of handles. The people who own the decision and would be the right reviewers if it's revisited. |
consulted | optional | People whose opinion was sought. Useful for audit-trail clarity ("we did consult security"). |
informed | optional | People notified of the outcome. Often a channel name rather than individuals. |
The consulted and informed fields come from the RACI taxonomy. They feel ceremonial in a 5-person team and become genuinely useful in a 50+ person org where "who knew about this" is an audit question.
MADR vs Nygard ADR — when to use which
| Concern | Nygard ADR | MADR |
|---|---|---|
| Format | Free-form Markdown, 5 sections | YAML frontmatter + structured Markdown body |
| Tooling friendly | Limited (regex-parseable headings) | Yes (YAML is unambiguous) |
| Best for | Small teams, repo-only consumers | Larger orgs, dashboards, exports, multi-team audits |
| Onboarding cost | Almost zero | Mild — readers learn the field names |
| 250-word goal | Yes | Yes (longer in practice because of structured options) |
If you're starting out, the Nygard Markdown ADR is enough. Migrate to MADR when you have a real reason — a compliance review that needs structured exports, an internal dashboard that wants to count decisions per team, an LLM context that needs predictable parsing. MADR's overhead pays for itself when something downstream actually depends on the structure.
How WhyChose helps
WhyChose can output decisions in either Nygard or MADR shape. The MADR exporter populates the frontmatter from your AI chat metadata: date from the conversation timestamp, decision-makers from the chat's participants, consulted blank for you to add, and the body sections filled from the conversation segment that produced the decision. The open-source extractor ships the JSON shape; the MADR rendering is a 60-line script in the README. Run it locally if you want extraction to stay inside your environment.
Related questions
What does MADR stand for?
"Markdown Any Decision Record." The "any" is deliberate — the format is meant for non-architectural decisions too (product, ops, policy) where the structure still helps. In practice most usage is for architecture, hence the conflation with "ADR."
Is MADR an official standard?
It's an open spec maintained on GitHub at adr/madr, currently at version 4.0. Not a formal standards-body output, but widely adopted enough that most ADR tooling that promises "structured ADRs" means MADR. The spec is short and stable; breaking changes between major versions have been minor.
Can I mix MADR and plain Markdown ADRs in the same repo?
Technically yes; pragmatically no. Once tooling expects frontmatter, an unfrontmattered ADR breaks the parser silently. Pick one format per repo and stick with it. If you're migrating, do it in one PR with a script — partial migration is the worst of both worlds.
Further reading
- ADR template in Markdown — the simpler Nygard format MADR is built on top of.
- The Nygard ADR template — the original 5-section format, the historical anchor.
- ADR example: Postgres vs MongoDB — a worked example using a Nygard-shaped record (the same content fits cleanly into MADR).
- The ADR GitHub Action — a CI pipeline scaffolded for Nygard; the page documents the one-line regex change to make the lint MADR-aware (frontmatter + status: + the three required sections).
- How to update an ADR (without breaking the audit trail) — MADR's structured frontmatter (status, date, decision-makers) maps directly onto the update protocol; this page covers what changes vs what stays immutable across status transitions and supersession.
- ADR supersession pattern — when to supersede, when to annotate, and how to stay bidirectional — MADR uses a
supersedeskey in YAML frontmatter for the forward pointer; the standalone supersession-pattern page documents the two-file atomic protocol, cascade chains, bidirectional integrity checks, and orphan recovery when a supersession PR is reverted. - ADR numbering scheme — padding, gaps, and collision recovery — MADR's filename convention is the same 4-digit pattern as Nygard; the merge-base allocator and never-renumber discipline apply unchanged.
- ADR status template — format, fields, and the lifecycle beyond Accepted — MADR's frontmatter conventions are the closest to the recommendations on the status template page; covers the optional Trial-Period state, the shields.io badge variant for human readers, and the five companion fields (Date, Decision-by, Reviewers, Trial-Until, Tags) that pair with MADR's structured shape.
- ADR storage format comparison — MADR is the body shape; this storage-comparison page covers where MADR-shaped files actually live (Markdown in repo as default, or migration to Notion / Confluence / SharePoint), with the per-team-shape decision matrix and the 4–16 hour migration paths between layers.
- TOGAF ADR template — extends MADR's structured frontmatter with seven enterprise-architecture fields (EA Domain, ADM Phase, ABB, Stakeholder Mapping, Requirements Traceability, Capability Impact, Repository Placement) so MADR-shaped ADRs fit into a TOGAF Architecture Repository; the body remains pure MADR and only the frontmatter grows.
- ADR review checklist — what to look for before merging — MADR's YAML frontmatter (especially the
status:field and the structuredoptions:block) maps to two additional structural checklist items beyond the Nygard baseline; this page covers the full 12-item review across structure, reasoning quality, traceability, and longevity. - ADR lightweight template — LADR, Y-Statements, and the minimum viable format — MADR is described here as the structured midpoint between LADR and Nygard-complete; this page covers the lighter end of the spectrum: the three-field LADR variant and the Y-Statement one-sentence form. The format-selection decision table explains when each format fits — LADR for prospective ADRs under time pressure, MADR for structured CI integration, Nygard for mature retrospective practices.