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.
Writing each section well
Title: Use an imperative or a noun phrase that names the thing being decided, not the outcome. “Choose between SQL and NoSQL” is a bad title — you do not name decisions after the act of choosing. “Use PostgreSQL for the orders service” is good. Include the scope (which service or subsystem) so records stay specific.
Status: Move from Proposed → Accepted as a record gains consensus. Use Deprecated when the context has changed but no new decision replaces it yet. Use Superseded when a later ADR reverses or replaces the decision; always include a cross-reference to the new ADR number.
Context: Describe the forces that made this a decision rather than an obvious default. Relevant forces include: team skills, operational constraints, cost, existing technology, regulatory requirements, and the time horizon. Do not write “we needed a database” — write what made the choice non-obvious.
Decision: A single active-voice statement starting “We will…” makes it unambiguous. Avoid passive constructions (“It was decided that…”) that obscure who owns the decision.
Consequences: This is the section most often written poorly. List both positive and negative consequences. If you only list positives, you are writing a sales pitch, not an honest record. Common negative consequences: new operational burden, knowledge dependency on a specialist, vendor lock-in, performance trade-offs, or constraints on future decisions.
Alternatives considered: Explain why each rejected option was inferior given the forces in the context section. A future reader should be able to understand from this section why the “obvious” alternative was not chosen, so they do not re-open the debate without new evidence.
A minimal worked example
# 0005-use-postgres-for-orders
Status: Accepted
Date: 2024-03-14
## Context
The orders service needs relational integrity between orders, line items, and
payment records. The team has strong SQL expertise. MongoDB was in use for the
user profile service and there was pressure to standardise on one database.
## Decision
We will use PostgreSQL for the orders service.
## Consequences
Good: ACID transactions across order + payment tables; familiar tooling.
Bad: Separate database cluster from the profile service; team must maintain
two database technologies until profile is migrated or MongoDB is adopted wider.
## Alternatives considered
MongoDB: Rejected because multi-document transactions, while available since 4.0,
add operational complexity and the team lacks MongoDB DBA experience.When to write an ADR
Not every decision deserves a record. Write one when the decision:
- Is hard to reverse later (database choice, event schema, auth protocol)
- Has non-obvious trade-offs the team debated
- Will be questioned by new team members in six months
- Overrides what someone would consider the obvious default
Skip it for trivial choices (which logging format, how to name a variable) that have no lasting architectural consequence.