Skip to main content

ADR Templates: Nygard, MADR, Y-Statement

What This Concept Is​

Three ADR templates dominate practice. Each emphasizes different things.

  • Michael Nygard's original (2011). The minimum viable ADR: title, status, context, decision, consequences. Optimized for brevity and for long lifespan in a source-controlled folder.
  • MADR (Markdown Any Decision Records). Nygard plus explicit decision drivers, considered options, and pros/cons. Better for decisions with multiple live alternatives.
  • Y-statement. A single-sentence form: "In the context of X, facing Y (with constraints C), we decided Z, to achieve Q, accepting downside D." Used for one-line decision logs and executive summaries.

All three agree on the core: you capture context, decision, and consequences. They differ in how much scaffolding they give for weighing alternatives.

Why It Matters Here​

Template choice changes what the author is forced to think about. A Nygard ADR can hide weak reasoning inside prose. MADR makes the alternatives visible and refusal to name them becomes conspicuous. A Y-statement compresses the whole decision to a single sentence, which is excellent for indexes but useless as the primary record.

Pick a template consciously. Most teams default to Nygard and then extend; some default to MADR for regulated or multi-option decisions; Y-statements usually appear as a one-line summary inside a longer ADR.

Concrete Example​

Same decision, three renderings.

Nygard:

# ADR-0021: Adopt OpenTelemetry for distributed tracing

## Status
Accepted - 2026-03-04

## Context
We have three disparate tracing systems (Zipkin, Datadog APM, homegrown),
and debugging cross-service requests requires joining traces by hand.

## Decision
Standardize on OpenTelemetry with OTLP export. Retire the homegrown
tracer in Q3; keep Datadog as the backend.

## Consequences
- shared semantic conventions across services
- one more dependency to update during runtime upgrades
- existing dashboards must be rebuilt against OTel metric names

MADR:

# ADR-0021: Adopt OpenTelemetry for distributed tracing

## Context and Problem Statement
Three tracing stacks, no joinable traces across services.

## Decision Drivers
- single query surface for cross-service debugging
- vendor flexibility for backend
- minimize per-service instrumentation burden

## Considered Options
1. OpenTelemetry (OTLP)
2. Stay with Datadog APM proprietary SDKs
3. Extend the homegrown tracer

## Decision Outcome
Chosen: OpenTelemetry, because it is the only option that satisfies
vendor flexibility and joinable traces.

## Pros and Cons
- OTel: + vendor-neutral, + strong community; - additional dependency
- Datadog SDKs: + lowest setup effort; - vendor lock-in on traces
- Homegrown: + zero migration; - every backend integration is custom work

Y-statement:

In the context of cross-service debugging across three tracing stacks, facing inability to join traces under ops pressure, we decided to adopt OpenTelemetry with OTLP export, to achieve vendor flexibility and unified semantic conventions, accepting an extra runtime dependency and a dashboard rebuild.

Common Confusion / Misconception​

"Template choice is a style question." It is not. MADR forces alternative-comparison; Nygard permits prose that obscures it. A team that cannot articulate alternatives should use MADR.

"Y-statements are a full ADR." They are not. Use Y-statements for summaries and dashboards, never as the sole record.

"The template has to be the same across the whole org." Consistency helps discovery, but hybrid organizations (e.g., platform team on MADR, product teams on Nygard) work fine as long as the folder is shared and discoverable.

How To Use It​

  1. Pick a default at the repo level (usually Nygard) and document the choice in a library/raw/adr/README.md.
  2. Allow teams to promote specific decisions to MADR when more than two serious options exist.
  3. Include a one-line Y-statement at the top of every ADR regardless of template, for human scanability.
  4. Never mix template sections without labeling - do not paste MADR fields into a Nygard skeleton without updating the filename/heading.

Check Yourself​

  1. Which template would you pick for: (a) choosing a CI provider with 4 real candidates; (b) deciding whether to enable strict TypeScript; (c) setting cross-service retry policy?
  2. What does a Y-statement force the author to name that a Nygard ADR does not?
  3. Can an MADR ADR have only one option? What would that mean?

Mini Drill or Application​

Take one decision from the past 30 days and render it in all three templates. Then answer:

  • Which template best represents the decision you actually made?
  • In which template was the weakest part of your reasoning most visible?
  • Which would you ship?

Read This Only If Stuck​