MADR template

Copy full and minimal MADR Markdown templates with decision drivers, options, pros and cons, outcome, consequences, and confirmation.

Last reviewed: 8 October 2026.

Format

MADR means Markdown Architectural Decision Records. Its template separates the problem, the options you considered, and the reason for choosing one. Use it when a reviewer needs to understand the comparison as well as the outcome.

Choose MADR when a four-section Nygard record leaves important comparison detail implicit. The full template makes drivers, considered options, per-option pros and cons, the outcome, consequences, and confirmation visible. The minimal variant keeps the mandatory core.

The full and minimal templates below follow the MADR 4.0.0 release. Pin the template version your team adopts so reviews use a consistent structure. The adr/madr project maintains the source, and the MADR guide explains the format and its history.

Use the generator with the Full / Minimal toggle for the lean template (adr-template-minimal.md). For a leaner record, compare the Nygard template.

Full or minimal MADR?

Minimal: record the context and problem, the considered options, and the decision outcome and consequences. Choose it for a bounded decision whose comparison can be explained in a few sentences.
Full: add decision drivers, per-option pros and cons, confirmation, more information, and optional metadata. Choose it when several reviewers, quality concerns, or operational risks need to be considered explicitly.

Add optional sections only when they help explain the choice. A shorter record still needs to name a real alternative and say why it was not selected.

MADR vs Nygard: compare the structures

MADR — full template

---
# These are optional metadata elements. Feel free to remove any of them.
status: "{proposed | rejected | accepted | deprecated | … | superseded by ADR-0123}"
date: {YYYY-MM-DD when the decision was last updated}
decision-makers: {list everyone involved in the decision}
consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
---

# {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question. Consider adding links to collaboration boards or issue management systems. Make the scope of the decision explicit, for instance, by calling out or pointing at structural architecture elements (components, connectors, ...).}

## Decision Drivers

* {decision driver 1, for instance, a desired software quality, faced concern, constraint or force}
* {decision driver 2}
* …

## Considered Options

* {title of option 1}
* {title of option 2}
* {title of option 3}
* …

## Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

### Consequences

* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
* …

### Confirmation

{Describe how the implementation / compliance of the ADR can/will be confirmed. Is there any automated or manual fitness function? If so, list it and explain how it is applied. Is the chosen design and its implementation in line with the decision? E.g., a design/code review or a test with a library such as ArchUnit can help validate this. Note that although we classify this element as optional, it is included in many ADRs.}

## Pros and Cons of the Options

### {title of option 1}

{example | description | pointer to more information | …}

* Good, because {argument a}
* Good, because {argument b}

* Neutral, because {argument c}
* Bad, because {argument d}
* …

### {title of other option}

{example | description | pointer to more information | …}

* Good, because {argument a}
* Neutral, because {argument b}
* Bad, because {argument c}
* …

## More Information

{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}

MADR — minimal template

# {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question. Consider adding links to collaboration boards or issue management systems. Make the scope of the decision explicit, for instance, by calling out or pointing at structural architecture elements (components, connectors, ...).}

## Considered Options

* {title of option 1}
* {title of option 2}
* {title of option 3}
* …

## Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

### Consequences

* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
* …

Worked MADR example: choosing a Redis cache

This illustrative decision compares no cache, an in-process cache, and a Redis TTL cache. It is the caching decision from our Redis ADR example presented in MADR. Use Full or Minimal below to see which detail each variant retains, then copy the Markdown as a starting point for your own decision.

Preview

Decision metadata

status: "accepted"
date: "2026-02-01"
decision-makers: "API guild, SRE"
consulted: "DB owners"
informed: "Product teams using approved routes"

Use Redis for short-lived application caching

Context and Problem Statement

Repeated reads hammer the database on hot API paths. We need acceleration without erasing the boundary between fast path and system of record.

Decision Drivers

Latency and load on primary storage
Correctness when cache misses or evicts
Operations already know Redis in this environment

Considered Options

No cache — simplest; still slow and expensive at peak
In-process only — uneven under horizontal scale
Redis TTL cache — shared, measurable, not authoritative

Decision Outcome

Chosen option: "Redis TTL cache", because it is shared, measurable, and SRE already operates Redis; database remains source of truth.

Consequences

Good, because fewer DB reads on hot paths; key design and invalidation become explicit review topics
Bad, because Redis unavailability or slowness must degrade safely
Bad, because cache correctness becomes a correctness topic, not perf-only

Confirmation

Cache owners + SRE sign-off in review before enabling new cached routes in prod.

Pros and Cons of the Options

No cache

Good, because simplest mental model
Bad, because hot paths stay expensive at peak

In-process only

Good, because no extra infra hop
Bad, because uneven hit rates under horizontal scale

Redis TTL cache

Read-through, TTL-bound, allowlisted routes.

Good, because shared cache and existing ops playbooks
Good, because TTL keeps staleness bounded when designed well
Bad, because extra dependency and careful invalidation work

More Information

SRE flush runbook; naming convention for keys; allowlist process for new routes.

What to learn from the example

Drivers explain the criteria: latency, correctness, and operational experience make the comparison specific to this team.
Alternatives remain visible: the record explains why a shared cache was chosen over no cache or a process-local cache.
Consequences describe the cost: safe fallback and invalidation work remain responsibilities after the choice is accepted.
Confirmation names a check: reviewers must agree how the implementation will be checked before cached routes go live.

Open generator with this format preselected (also persisted in local storage on this site).

Compare all ADR formats · Browse worked ADR examples