Architecture Decision Records in Markdown: The MADR Format Explained

Quick answer

An Architecture Decision Record (ADR) is a short file — usually one per decision — that documents a single significant technical choice: the problem, the options weighed, and what got picked. MADR (Markdown Architectural Decision Records) is the template most teams reach for. It adds a structured list of considered options with pros and cons on top of the basic context-decision-consequences shape, so the reasoning behind a decision survives long after the people who made it have moved on.

If you already keep a docs/ folder in Markdown, adding ADRs costs you one new subdirectory and a naming convention. No new tooling required.

Step-by-step

Pick a template variant

MADR 4.0.0 ships four variants of the same template, and the difference is entirely about how much explanatory text you keep:

• Full (adr-template.md) — every section, with guidance comments explaining what to write in each one
• Minimal (adr-template-minimal.md) — only the mandatory sections, still with explanations
• Bare full (adr-template-bare.md) — every section, no guidance text
• Bare minimal (adr-template-bare-minimal.md) — mandatory sections only, no guidance

The MADR project recommends starting with the full or minimal template while your team is still learning the format, then switching to a bare variant once writing an ADR feels routine.

Write the Context and Problem Statement

Open with the question you're actually answering, and what's constraining the answer — a performance requirement, a team's existing skill set, a deadline. One or two paragraphs is usually enough. This is the section that makes the record useful six months later, when nobody remembers the meeting where the decision got made.

List Considered Options with pros and cons

This is what separates MADR from simpler ADR formats. A minimal example:

## Considered Options

* PostgreSQL — mature, strong JSON support, team already runs it in prod
* DynamoDB — scales without ops overhead, but query patterns are rigid
* SQLite — simplest to run locally, doesn't fit a multi-writer service

Keep each option to one line unless the tradeoff genuinely needs more room.

Record the Decision Outcome

State which option you chose and why, in a single "because" sentence: "Chosen option: PostgreSQL, because the team already operates it and the JSON support covers our semi-structured fields." The canonical MADR example — itself an ADR documenting the decision to use MADR — follows exactly this shape: Context and Problem Statement, Considered Options, Decision Outcome.

File naming and where records live

Store ADRs in a docs/decisions (or docs/adr) directory, one file per decision, numbered sequentially: 0001-use-postgres-for-primary-store.md, 0002-adopt-graphql-for-the-public-api.md. Optional YAML front matter — status, date, deciders — can sit at the top of each file if you want that metadata queryable. Haven't used front matter before? See our guide to YAML front matter. Once a file is written, don't edit it to reflect a later change of mind. Write a new ADR that supersedes it, and link the two together. Teams that already write spec.md and plan.md files for spec-driven development will recognize the pattern: a durable, numbered, plain-text record of a decision that shouldn't be quietly rewritten.

Common problems and fixes

The full template feels heavy, so nobody writes ADRs. Switch to the bare-minimal variant. A three-line Context, a bullet list of options, and a one-sentence outcome is still a real ADR — the ceremony was optional, the record wasn't.

Nobody agrees on what counts as "architectural." Here's a quick filter: if you can state the decision as a single sentence — "In the context of the payments service, facing PCI scope creep, we decided for a hosted checkout to keep card data out of our servers, accepting less UI control" — that's a Y-Statement, and it's a useful test. Takes more than one sentence to explain? It probably deserves the fuller MADR treatment, options list and all.

An old ADR gets edited in place and the history disappears. Never edit an accepted ADR to match a new decision. Write a new numbered file, mark the old one as superseded, and link forward and back between the two. The whole value of an ADR is that it's a dated record, not a living document.

The document that should be an ADR ends up scattered across pull request descriptions instead. The same discipline that makes a CONTRIBUTING.md people actually follow work applies here too: one canonical file, one clear location, short enough that people actually read it. A PR description disappears into history; a numbered file in docs/decisions doesn't.

MADR isn't the only option, for what it's worth. The original Nygard ADR format (2011) uses five fields — title, status, context, decision, consequences — and skips the options comparison entirely. It's faster to write when a decision was fairly obvious in hindsight. Y-Statements go further and compress everything into one sentence. Pick the weight that matches how contested the decision actually was.

Doing this with Carets

Writing and reviewing ADRs is plain Markdown editing, and that's exactly what Carets is built for. Files stay in Markdown and plain text, so your docs/decisions folder stays portable if you ever move it into a different repo or tool — no proprietary format to fight with later. Organize decision records into their own project and tag them by system area (payments, auth, infra) so a specific ADR is a search away instead of a scroll through a long list. And because Carets is native and fast on iPhone, iPad, and Mac, you can draft the Context and Problem Statement right after the meeting where the decision came up, then finish the Considered Options section back at your desk without switching tools.

Carets is available on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

What is an Architecture Decision Record (ADR)?

A short markdown file that captures a single significant technical decision — the problem, the options considered, and the choice made — so future contributors understand the reasoning without re-litigating it.

What does MADR stand for?

Markdown Architectural Decision Records. It's a specific ADR template, first released in 2017, that plays on "matter" — decisions that matter — and adds a structured options-with-pros-and-cons comparison on top of the basic ADR idea.

Where should ADRs live in a repo?

In a docs/decisions (or docs/adr) directory, one markdown file per decision, named with a sequential number and short title, e.g. 0003-use-postgres-for-primary-store.md.

Should I edit an old ADR when a decision changes?

No. Leave the original file as a historical record and write a new ADR that supersedes it, linking back to the one it replaces.

Is MADR better than the original Nygard ADR format?

Neither is strictly better for every case. MADR adds a Considered Options section with pros and cons, useful when a decision involved real tradeoffs; the plain Nygard format (title, status, context, decision, consequences) is faster to write when the choice was more straightforward.

Conclusion

An ADR only helps if someone actually writes it down — which is the whole argument for MADR: a Markdown template light enough to fill out the same day a decision gets made, with just enough structure to make sense of it a year later. Pick the template weight that matches your team's decision cadence, keep records in a numbered docs/decisions directory, and supersede rather than rewrite when a decision changes.