What is an Architecture Decision Record?

An ADR is a short document that captures one significant architecture decision, the context that forced it, and its consequences. Recording decisions this way gives future engineers the reasoning behind the system, not just the outcome.

What is the Nygard ADR format?

It is the original lightweight template by Michael Nygard with five core sections: Title, Status, Context, Decision, and Consequences. This builder follows that format and adds an optional Alternatives section for the options you rejected.

How should I name the file?

Convention is a zero-padded number plus a slug, like 0007-use-event-sourcing.md, stored in a docs/adr folder. The builder shows you the suggested filename based on the record number and title.

When should a status be Superseded?

Mark an ADR as Superseded when a later record reverses or replaces its decision, and reference the new ADR number. Accepted records are never edited or deleted, only superseded, so the history stays intact.

Is my decision data uploaded anywhere?

No. The builder runs entirely in your browser, so your architecture decisions stay private and are never sent to a server.

Architecture Decision Record (ADR) Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Record the why behind your architecture

Code shows what a system does; an Architecture Decision Record shows why it does it that way. ADRs are short, immutable documents that capture one decision and the forces behind it. Months later, when someone asks “why did we choose this database?”, the answer is a single file instead of a lost Slack thread. This builder produces ADRs in the well-known Nygard format.

How it works

The builder assembles the five canonical Nygard sections in order. The Title is prefixed with a zero-padded record number. The Status field captures the lifecycle stage (Proposed, Accepted, Deprecated, or Superseded). Context describes the technical and business forces at play. Decision states the choice in active voice (“We will use…”). Consequences lists what becomes easier and harder as a result. An optional Alternatives considered section records the rejected options so the trade-off is visible.

Each multi-line list field is rendered as Markdown bullets, and the tool suggests a conventional filename like 0007-use-event-sourcing.md so the record drops straight into a docs/adr/ directory.

Tips and example

Write titles as short noun phrases or imperatives: “Use PostgreSQL for the orders service”, not “Database decision”.
State the decision in active voice — “We will…” — so there is no ambiguity about what was agreed.
Always fill in negative consequences. An ADR that lists only benefits hides the real cost of the decision.
Never edit an Accepted ADR. If the decision changes, write a new record and mark the old one Superseded, referencing the new number.