Skip to content
Product Lifecycle Templates

Architecture Decision Record

beta  ·  Family decision-docs  ·  Phase develop  ·  Sizes lean, full  ·  ~2,000 tokens

Records one architecturally significant decision: the forces that made it necessary, the options genuinely considered, the option chosen, and the consequences accepted. Immutable once accepted; superseded by a new record rather than edited.

Fast reference for using the ADR bundle. For the full reasoning, history, and sources, read adr_companion.md.

When to use

Section titled “When to use”
  • A decision is expensive or slow to reverse: a persistence engine, a data model, a public API shape, an auth scheme, a language or framework, a hard dependency.
  • Reasonable engineers disagreed, and the disagreement is worth preserving.
  • A future reader will predictably ask “why is it like this, and did they consider X?”
  • The decision looks wrong from outside but was deliberate. This is the highest-value record you will ever write.
  • You are backfilling a decision made months ago that the team keeps re-litigating. Legitimate, and explicitly endorsed practice. Date it when the decision was made, and say it was reconstructed.

When NOT to use

Section titled “When NOT to use”
  • The decision is cheap to reverse. Use the reversibility test, not a significance test: if undoing it next quarter costs an afternoon, it does not need a record. This is the single most useful filter, and skipping it is how a decisions directory fills with noise.
  • The decision has not been made yet. You want an RFC or a design proposal. An RFC requests input; an ADR records an outcome. Run the RFC, then write the ADR when the call is made.
  • It is an implementation detail. A variable name, a minor refactor, a library version bump.
  • It is already stated in a rulebook. If your methodology or contributing guide already mandates it, an ADR restating it adds a second source of truth, which is worse than none.
  • You are writing it so nobody can be blamed later. That is not a record, and everyone can tell.

Pick a variant

Section titled “Pick a variant”
  • Lean (default, and it is not a compromise): the three sections MADR marks mandatory. Most decisions are recorded honestly in half a page. A short record that gets written beats a thorough one that does not.
  • Full: when the decision is contested, crosses teams, carries regulatory or safety weight, or you expect to defend it to an auditor. Adds Decision Drivers, Confirmation, Pros and Cons of the Options, and More Information.

Grow lean into full by adding sections; never reorder the shared ones. The full variant is a strict superset.

The scaling signal is the contestedness of the decision, not the importance of the system.

Quality rubric (self-grade before you commit)

Section titled “Quality rubric (self-grade before you commit)”
  • The title names the decision, not the topic. A stranger scanning the folder knows what was chosen.
  • The context describes the situation, not the argument you won. It was not written backwards from the conclusion.
  • The context records conditions that could stop being true, so a future reader can tell whether the decision has expired.
  • “Do nothing” appears in Considered Options, or its absence is deliberate.
  • No straw men. Every option listed was genuinely on the table.
  • The outcome is in active voice (“We will …”), and a human being is named in decision-makers.
  • There is at least one real negative consequence, and it is one someone would actually act on. “Small learning curve” does not count.
  • The chosen option has honest cons listed, not just the rejected ones.
  • (Full) Decision Drivers exist and are falsifiable: at least one option fails at least one driver. If every option passes every driver, the real reason is still unwritten.
  • (Full) Confirmation names a real check, or honestly states that nothing enforces this.
  • status is correct, and if this supersedes an earlier record, that record has been updated to point here.
  • Filed at docs/internal/decisions/NNNN-kebab-title.md with a fresh, never-reused number.
  • Every guidance comment deleted; no placeholders remain.

Named anti-patterns (the usual wrecks)

Section titled “Named anti-patterns (the usual wrecks)”
  1. Approval theater. Records written after the fact for decisions nobody contested, so the folder looks disciplined. They bury the records that matter.
  2. The CYA record. Written to spread accountability rather than inform. The tells are passive voice and a decision-makers field that is either empty or lists the entire org chart.
  3. Decision without alternatives. The costliest of these, whatever its frequency. The record cannot answer the only question it will ever be asked.
  4. Stale status. A record still marked accepted for something ripped out two years ago is not merely useless; it actively misleads whoever finds it.
  5. Scope bloat. Everything becomes an ADR, and the architecture gets harder to see. The artifact inverts its own purpose.
  6. All-upside consequences. If the decision cost nothing, it was not a decision.
  7. The wiki. Records stored anywhere but the repo are reliably records nobody reads.

Coming from Nygard’s format?

Section titled “Coming from Nygard’s format?”

Every Nygard section maps into MADR without loss. You are not rewriting anything, you are renaming.

Nygard (2011) MADR (this template)
Title Title (H1)
Status status in YAML frontmatter
Context Context and Problem Statement
Decision Decision Outcome
Consequences Consequences (under Decision Outcome)
(not in Nygard) Considered Options, and the rest of the full variant

The one substantive addition is that MADR makes Considered Options a mandatory section, where Nygard’s five sections have no dedicated home for the alternatives at all. Promoting them to a required list of their own is the most useful thing MADR changed, because the alternatives are the section teams silently drop, and a record without them cannot answer the only question it will ever be asked. (That is this bundle’s reading of the difference between the two formats, not a claim about what Nygard intended.)

Compatibility note: the develop-adr skill

Section titled “Compatibility note: the develop-adr skill”

This bundle’s pairs_with is develop-adr in pm-skills, which drafts an ADR interactively.

Be aware that the two currently differ. The skill’s bundled template follows Nygard’s format (Status / Context / Decision / Consequences / Alternatives Considered / References). This bundle follows MADR v4, which is the format the wider product-on-purpose organization has standardized on for its own decision records, and which its project scaffolding expects at docs/internal/decisions/.

Until they converge, use the mapping table above: content drafted by the skill transfers into this template section for section. If you are recording a decision inside a product-on-purpose repository, use this template, because it is the format the org’s tooling and conventions expect.

(This divergence was found while building this bundle, and it is logged as a finding for pm-skills rather than silently patched. It is exactly the kind of drift a template library exists to surface.)

The artifacts

Section titled “The artifacts”

adr_template-lean.md · ~2,000 tokens

---
status: "{{status}}"
date: "{{date}}"
decision-makers: ["{{decision_makers}}"]
doc_type: adr
size: lean
source_template: adr
source_template_version: 0.1.0
---


<!--
LEAN ADR. The three sections MADR marks mandatory, and nothing else. This is the right default:
most decisions are recorded honestly in half a page, and a short record that gets written beats a
thorough one that does not. To grow this into a full ADR, ADD sections (see adr_template-full.md);
never rename or reorder the ones below, because the full variant is a strict superset of this one.


WHERE THIS FILE GOES
  docs/internal/decisions/NNNN-short-kebab-title.md
Numbered sequentially from 0001. Numbers are never reused, not even for a record that ends up
rejected or superseded. The number is an address, not a ranking.


IMMUTABILITY, THE RULE THAT MAKES THIS ARTIFACT WORTH ANYTHING
Once this record is accepted, do not rewrite the decision. Write a NEW record and set this one's
status to "superseded by ADR-NNNN". A decisions folder that silently rewrites itself is just a
wiki with extra steps. The trail is the product.
(One narrow exception, and only one: a factual error in the record, as opposed to a change in the
decision, is corrected in place with the correction dated and the error named. See
adr_companion.md section 6 for why that line sits exactly there.)


HOW TO FILL THIS IN
1. Read the comment under each heading: WHAT it wants, WHY it matters (with a pointer into
   adr_companion.md for the deep reasoning), guiding questions to ASK, a GOOD and a WEAK
   example, and the TRAP to avoid.
2. Replace each {{placeholder}} with your content.
3. If a section does not apply, write "N/A" and one line of why, rather than deleting it.
4. Before you ship: self-grade against adr_guide.md, then DELETE every HTML comment. They are
   guidance, not content.
-->


# {{title}}


<!-- WHAT  A short title naming BOTH the problem solved and the option chosen, in plain words.
           Phrased as a statement, not a question.
     WHY   The title is the only part of this record most people will ever read. A decisions
           directory is browsed as a list of filenames; a title that names a topic instead of a
           decision is invisible in that list.
           Deep dive: adr_companion.md section 3 (Anatomy > Title).
     ASK   What was the problem? What did we choose? Scanning the folder, would a stranger know?
     GOOD  "The meta declares the size contract; single-size bundles are a legal shape"
     WEAK  "Database decision" (a topic, not a decision; nobody can act on it)
     TRAP  Naming the topic rather than the decision. "Caching" is a folder name. "Use Redis for
           the session cache, accepting a new operational dependency" is a record. -->


## Context and Problem Statement


<!-- WHAT  The forces in play, and the problem they create, in two or three sentences or a short
           story. Make the SCOPE explicit: name the components or boundaries this decision binds.
     WHY   Context is what expires. The decision may stay right while the reason for it quietly
           stops being true, and the only way a future reader can tell is if you wrote down the
           conditions you were under. This section is the record's shelf-life label.
           Deep dive: adr_companion.md section 3 (Anatomy > Context and Problem Statement).
     ASK   What forces are pressing (technical, business, organizational)? What constraint,
           deadline, or skill gap is real? What breaks if we do nothing? What does this bind?
     GOOD  "Seven of the 27 Tier-1 types are single-size, so the next bundle we build is likely to
           be one, and the gate cannot pass it: two checks hardcode the assumption that every
           bundle ships exactly lean and full."
     WEAK  "We need to decide on our caching strategy." (restates that a decision exists; names
           no force, no constraint, and nothing that would ever stop being true)
     TRAP  Writing the context AFTER the decision, as justification. Then it records the argument
           you won, not the situation you were in, and it teaches a future reader nothing. -->


{{context_and_problem}}


## Considered Options


<!-- WHAT  The options genuinely on the table. Titles only here; the reason the winner won goes in
           Decision Outcome below. (The full variant adds a "Pros and Cons of the Options" section
           for weighing each one properly. If you find you need it, you want that variant.)
     WHY   The rejected options are the reason this artifact exists. A record that lists only the
           winner cannot answer the one question it will actually be asked, which is "did you
           think about X?" Without the alternatives, a future team re-litigates from zero.
           Deep dive: adr_companion.md section 3 (Anatomy > Considered Options), and the
           anti-pattern in section 7 (recording the decision but not the alternatives).
     ASK   What else was seriously on the table? What was the obvious option we rejected, and the
           one a newcomer will ask about in six months? Is "do nothing" one of them?
     GOOD  * Make the meta the size contract, enforced in both directions
           * Waive the checks whenever a variant file is absent
           * Require every type to ship two variants, padding out a full for single-size types
     WEAK  A single bullet, or a list padded with options nobody would ever have chosen.
     TRAP  Straw men. Two decoys and a winner is not a decision record, it is a press release.
           If an option was never real, leave it out and say so if it comes up. -->


* {{option_1}}
* {{option_2}}
* {{option_3}}


## Decision Outcome


<!-- WHAT  The option chosen, and the justification, in active voice: "We will ...", not "It was
           decided ...". Then the consequences, honestly, both directions.
     WHY   Active voice puts a decision-maker back into the sentence. Passive voice ("it was
           decided") is how a record becomes accountability theater: everyone signed, nobody chose.
           Deep dive: adr_companion.md section 3 (Anatomy > Decision Outcome); the
           responsibility-deflection failure is in section 7.
     ASK   Which option, and because of what? What gets harder now? What are we knowingly paying?
     GOOD  "Chosen option: the meta is the contract, because it lets the gate tell a deliberately
           single-size bundle apart from a half-built one, which is the only thing a governance
           gate exists to do."
     WEAK  "After discussion, option A was selected as the best fit." (no agent, no reason)
     TRAP  Listing only good consequences. Nygard is explicit that ALL consequences are listed,
           not just the positive ones. A record with no cost is a record nobody believes. -->


Chosen option: "{{chosen_option}}", because {{justification}}.


### Consequences


<!-- WHAT  What becomes easier, and what becomes harder. Name the price you agreed to pay.
     WHY   The negative consequences are the highest-value lines in the whole record. They are
           what a future reader checks against reality to decide whether the decision still holds.
           Deep dive: adr_companion.md section 3 (Anatomy > Consequences).
     ASK   What is now harder or more expensive? What risk did we accept on purpose? What would
           have to become true for this to have been the wrong call?
     GOOD  Bad, because "sizes_available is now load-bearing: a bundle whose meta omits it fails
           the gate rather than being skipped. That is a deliberate behavior change. A contract
           you can silently omit is not a contract."
     WEAK  "Bad, because there is a small learning curve." (a cost nobody would ever act on)
     TRAP  A "Bad, because" line so weightless it is really a "Good" in disguise. If you cannot
           name a real cost, you have probably not understood the decision yet. -->


* Good, because {{positive_consequence}}
* Bad, because {{negative_consequence}}

Provenance

Section titled “Provenance”

The reasoning, the history and every source, in the repository:

  • Companion - the long-form argument: why these sections, where the sources disagree, and what the bundle refuses to claim
  • History - what changed in this bundle, and when
  • Research log - every source consulted, with what each one actually supports
  • Catalog metadata - the machine-readable record this page is generated from

Catalog record: 9 sections across 1 format(s).