adr.crastinating.pro
Standard5 sections · ~250–500 words

Michael Nygard's ADR

Michael Nygard, 2011

The original. Five sections, written in prose. The format every other ADR template is reacting to.

Use it when

  • Your team has never written an ADR and needs a low-friction starting point.
  • The decision is a meaningful tradeoff that deserves a paragraph or two — not a one-liner.
  • You want to commit decisions to the same repo as the code they govern.

Avoid when

  • The decision has more than three competing options worth comparing on a matrix — Nygard's prose blurs comparisons.
  • You're capturing many small decisions per week — the prose overhead doesn't scale.

Strengths

  • Universally understood. No reviewer needs an onboarding doc to read one.
  • Forces you to write the consequences down, which is where most teams stop thinking.
  • Plain markdown — renders anywhere, diffable forever.

Weaknesses

  • No explicit options-considered section. Alternatives often get smuggled into Context.
  • Status lifecycle is informal — supersedes and accepts dates have to be added by convention.

Sections

5 required · 0 optional

Five sections of prose. Universally readable; no special training needed.

  1. 01

    Title

    Required

    Number + short noun phrase. The number is allocated when the ADR is created, never reused.

    ADR-007: Use Postgres for the decision store
  2. 02

    Status

    Required

    One of: Proposed, Accepted, Superseded by ADR-NNN, Deprecated. Status changes are themselves a new ADR.

    Accepted — 2026-04-12
  3. 03

    Context

    Required

    The forces in play: technical, political, social, project-local. Describe the situation that *required* a decision, not the decision itself.

    We need a primary store for decision documents and the audit trail. Reads are heavy; writes are append-mostly. The team's existing operational expertise is in Postgres; nobody on call knows Mongo.
  4. 04

    Decision

    Required

    The position you're taking, in active voice. Subject is the team. Verb is decisive.

    We will use a single Postgres 16 instance, hosted on Neon, as the primary datastore for decision documents and the audit log.
  5. 05

    Consequences

    Required

    What becomes easier *and harder* as a result. Be honest about the harder side — that's the entire point of the section.

    Easier: One query language for app + analytics. JSONB gives us schemaless flexibility for the metadata bag without giving up joins. Harder: We're locked into vertical scaling for the next ~18 months. Cross-region replication becomes a project, not a checkbox.

Worked example

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

ADR-0007: Use Postgres for the decision store

Status

Accepted — 2026-04-12

Context

We need a primary store for decision documents (brief and adr artifacts) and the append-only audit trail. Reads are heavy; writes are append-mostly. The team's existing operational expertise is in Postgres; nobody on the on-call rotation has run Mongo or DynamoDB at scale.

A second-tier requirement: we want to ship analytics on decision velocity (median days-from-proposed-to-accepted) without standing up a separate warehouse for the first 12 months.

Decision

We will use a single Postgres 16 instance, hosted on Neon, as the primary datastore for decision documents and the audit log. JSONB columns will hold the document body and the metadata bag; structured columns hold status, deciders, and timestamps for query.

Consequences

Easier

  • One query language for application code and analytics. No ETL job for the

first 12 months.

  • JSONB gives us schemaless flexibility for the metadata bag without giving

up joins on status and decider_id.

  • Backups, point-in-time restore, and read replicas are checkbox features on

Neon.

Harder

  • We're locked into vertical scaling for the next ~18 months. If decision

volume grows 100×, we will need to revisit (and that revisit will itself be an ADR).

  • Cross-region replication becomes a project, not a config change.
  • We give up the option of fan-out writes to a search index without explicit

triggers — full-text search will be tsvector for now, which is fine until it isn't.

Field of application

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

Tags:classicprosestarter