Architecture Decision Record (ADR) Template
An Architecture Decision Record template for PM-engineering teams. Capture the context, options considered, and rationale behind key technical decisions — before institutional memory walks out the door. Free to copy, download, and use. No signup required.
# Architecture Decision Record **ADR Number:** ADR-[NNN] **Title:** [Short noun phrase describing the decision, e.g. "Use PostgreSQL as primary datastore"] **Date:** [Date] **Status:** Proposed / Accepted / Deprecated / Superseded by ADR-[NNN] **Authors:** [Names] **Deciders:** [Names] --- ## Context > What is the situation? What problem are we solving? What forces are in play? > Write this for a new engineer who joins 6 months from now — they need to understand *why* this decision was a decision at all. [Write here] --- ## Decision Drivers > What factors matter most in making this decision? List them in priority order. 1. [e.g., Must handle 10,000 concurrent connections] 2. [e.g., Must be operated by a 2-person team without a dedicated DBA] 3. [e.g., Must support JSONB for flexible schema needs] 4. [e.g., Must have strong Python client libraries] --- ## Options Considered ### Option 1: [Name] **Description:** [What is this option?] **Pros:** - [Pro 1] - [Pro 2] **Cons:** - [Con 1] - [Con 2] **Estimated Cost/Effort:** [Low / Medium / High] --- ### Option 2: [Name] **Description:** **Pros:** - **Cons:** - **Estimated Cost/Effort:** --- ### Option 3: [Name] *(if applicable)* **Description:** **Pros:** - **Cons:** - --- ## Decision > State the decision clearly and unambiguously. **We will [chosen option].** [Brief rationale — why this option over the others, in 2–4 sentences] --- ## Consequences ### Positive - [What becomes easier or better?] - [What risks does this eliminate?] ### Negative / Trade-offs - [What becomes harder?] - [What do we give up?] ### Neutral - [What changes but isn't clearly better or worse?] --- ## Implementation Plan | Step | Owner | Target Date | |---|---|---| | | | | | | | | --- ## Review Triggers > Under what conditions should this ADR be revisited? - [ ] If we exceed [X] users / [X] requests per second - [ ] If [dependency/library] reaches end of life - [ ] If team size grows beyond [X] engineers - [ ] On annual review: [Date] --- ## Related Decisions | ADR | Relationship | |---|---| | ADR-[NNN] | Depends on / Supersedes / Related to | --- ## References - [Link to relevant RFC, blog post, benchmark, or prior art]
How to use this ADR Template template
Write the Context section for the future, not the present
The most important and most-skipped section. Write it as if you're explaining the situation to a new engineer who joins in 12 months and has zero context. What was the scale? What were the constraints? Why was this a hard decision? Without context, a future ADR reader can't evaluate whether the decision is still correct.
Always document at least 2 options — even the ones you rejected
An ADR with one option isn't a record of a decision — it's a justification of something already decided. The value of an ADR is understanding why Option B was rejected, so the next engineer doesn't have to investigate and rediscover the same tradeoffs.
Be explicit about trade-offs, not just benefits
The 'Consequences: Negative' section is the hardest to write and the most valuable. What do you give up by making this choice? What becomes harder? A decision with no downsides wasn't a real decision. Documenting trade-offs prevents future engineers from being blindsided by them.
Set review triggers at time of decision
ADRs without review conditions become permanent law. Write down the conditions that should trigger a revisit (scale thresholds, team size changes, library EOL). Schedule an annual review at minimum. Accepted ADRs should be revisited, not just archived.
Want a ADR Template grounded in your actual customer data?
PMRead ingests your customer interviews, feedback, and Slack threads — and generates PRDs backed by real evidence, not guesses.
Frequently asked questions
Who should write ADRs — PMs or engineers?
Engineers typically write the technical sections (options, consequences, implementation). PMs write or review the Context and Decision Drivers — they know the product constraints that motivated the decision. The best ADRs are co-authored. If a PM can't explain the Context, the decision lacked a clear product rationale.
How many ADRs should a team maintain?
One per significant architectural decision. 'Significant' means: decisions that affect multiple teams, decisions about foundational technology (database, auth, deployment), or decisions that are hard to reverse. Don't write ADRs for individual feature implementations — write them for cross-cutting architectural choices.
Where should ADRs live?
In the repository, in a /docs/adr/ directory, numbered sequentially (ADR-001, ADR-002). Keeping them in the repo means they're versioned alongside the code they describe, discoverable via grep, and part of the normal code review process.
Can ADRs be changed after they're accepted?
The record itself shouldn't be edited — it's a historical document. If the decision changes, write a new ADR that supersedes the old one, and update the old ADR's status to 'Superseded by ADR-[NNN]'. This preserves the full decision history, which is the entire point.
Other free templates