Rich (with options)8 sections · ~400–800 words

MADR (Markdown Architectural Decision Records)

Adam Bien, Olaf Zimmermann, et al. — adr.github.io

Nygard with explicit options-considered and pros/cons per option. The format you want when there's a real comparison to make.

Use it when

There are 2+ real options and the comparison is the substance of the decision.
You want a consistent structure across teams so reviewers know exactly where to push back.
Your decision is going into a long-lived repo and may be re-read by people who weren't there.

Avoid when

Lightweight, low-stakes calls — the structure becomes ceremony.
Decisions where the 'options considered' would be theatre (you already know the answer).

Strengths

Forces you to write the alternatives down, which prevents 'we never considered X' surprises six months later.
Pros/cons per option survives compression — even a busy reviewer gets the gist.
Has a tooling ecosystem (adr-tools, log4brains) that consumes this exact format.

Weaknesses

Easy to drift into checkbox-completion mode where every option is a strawman.
The 'Decision Outcome' section is sometimes a single sentence wrapped in a heading. Looks ceremonial.

Sections

7 required · 1 optional

Explicit options and pros/cons per option. The format you want when there's a real comparison.

01
Title
Required
ADR-NNNN: short noun phrase describing the decision (not the answer).
```
ADR-0042: Choose a router for the operator console
```
02
Status
Required
Proposed | Rejected | Accepted | Deprecated | Superseded by [ADR-NNNN](nnnn-link)
```
Accepted
```
03
Context and Problem Statement
Required
The forces and the question — phrased as a question. Reviewers should be able to disagree with the framing here.
```
The operator console needs nested routes, typed parameters, and SSR. Should we use Next.js App Router, TanStack Router on Vite, or React Router v7?
```
04
Decision Drivers
Required
Bullet list of what actually decides this. Not a wish list — the criteria that, if a candidate fails them, would knock it out.
```
- Type-safe route parameters end-to-end
- SSR for SEO on public pages
- Operator team has 4 of 6 engineers fluent in Next.js
```
05
Considered Options
Required
Bullet list, one line each. The order is the order you'll evaluate them in.
```
- Next.js App Router
- TanStack Router on Vite
- React Router v7 (Remix)
```

Decision Outcome

Required

Chosen option, plus a one-paragraph 'because' that names the decisive driver(s).

Chosen: Next.js App Router. Decisive driver: typed routes + SSR + team fluency. The other two are technically excellent but would cost a quarter of ramp-up.

Pros and Cons of the Options

Required

Per-option subsection. Pros and Cons each get a short bullet list. Be honest — strawman pros/cons devalue the format.

### Next.js App Router

**Pros**
- Typed routes via `experimental.typedRoutes`.
- Native SSR with React Server Components.

**Cons**
- Cache Components is still settling — you'll learn the hard edges.

More Information

Optional

Links: prior ADRs, RFCs, benchmarks, the meeting where this was actually decided.

- Supersedes ADR-0019
- Benchmark notes: /docs/router-bench-2026-04.md
- Discussion: #arch-router (2026-04-08)

Worked example

A real ADR written in the MADR format. Copy the markdown and adapt it.

ADR-0042: Choose a router for the operator console

Status

Accepted

Context and Problem Statement

The operator console (app.crastinating.pro) needs nested routes, typed route parameters, and SSR for the public-share view of a decision. Should we adopt Next.js App Router, TanStack Router on Vite, or React Router v7 (Remix)?

Decision Drivers

Type-safe route parameters end-to-end (no as string casts in pages).
SSR for SEO on public-share pages.
Operator team fluency: 4 of 6 engineers are already fluent in Next.js.
We want one routing primitive across web/app/brief/playbook — already

three of those are Next.

Considered Options

Next.js App Router (16.2)
TanStack Router on Vite
React Router v7 (Remix)

Decision Outcome

Chosen: Next.js App Router.

Decisive driver: typed routes + SSR + team fluency. The other two are technically excellent and TanStack's type inference is arguably the best in class — but adopting either would cost ~one engineer-quarter of ramp-up across the four front-end apps. We don't have that quarter.

Pros and Cons of the Options

Next.js App Router

Pros

experimental.typedRoutes gives us link-time type safety.
Native SSR via React Server Components.
Same primitive across all four apps in the monorepo.

Cons

Cache Components is still settling; some sharp edges around

use cache + cacheLife semantics.

The framework moves fast — we will pay an upgrade tax 1–2× per year.

TanStack Router on Vite

Pros

Best-in-class typed search params and route params.
Faster cold dev start than Next.

Cons

No first-class SSR. We'd need a separate Vite SSR setup or a hybrid host.
New primitive for the team — ramp-up cost.

React Router v7 (Remix)

Pros

Excellent loaders/actions story.
SSR out of the box.

Cons

The merge with Remix is recent; some patterns are still in flux.
New primitive for the team relative to existing Next apps.

More Information

Supersedes ADR-0019 (where we picked plain Vite + React Router v6 for the

console — that decision predated typedRoutes shipping).

Benchmark notes: /docs/router-bench-2026-04.md
Discussion thread: #arch-router (2026-04-08).

Field of application

Honest accounts of where this template was the right shape — and where it wasn't.

Context
Picking a frontend router across four apps.
Outcome
MADR's Considered Options forced us to write the TanStack case honestly, then explicitly reject it. Six months later when the question came up again, the doc was the answer.
Context
Picking a CSS strategy when the answer was already Tailwind 4.
Outcome
Wrong shape. The Considered Options section was theatre — three strawmen. Should have used Y-Statement or just a memo.

Tags:comparison options tooling friendly