ATTRIBUTION: thanks to Martin Cleaver https://github.com/mrjcleaver and the Agentics-Foundation https://agentics.org/ -- I took chat notes, and restructured for future reference below.
A lightweight, durable way to capture why an architectural decision was made (not just what was built), so teams can revisit decisions with context instead of re-litigating from scratch.
Tip
ADR = one decision, one file. Keep it durable, searchable, and easy to supersede.
- Copy the template section into your repo as
docs/adr/ADR-0XX-<slug>.md - Write ADRs at decision time (or immediately before)
- Treat Accepted ADRs as authoritative; when things change, supersede with a new ADR
Important
Accepted ADRs are immutable. If the decision changes, write a new ADR that supersedes it.
Table of Contents
-
ADR (Architecture Decision Record) — Documentation Pattern
- How to use this monofile gist
- What an ADR is (and is not)
- Why teams use ADRs
- When to write an ADR
- How PRDs interact with ADRs
- ADR lifecycle & statuses
- Naming & organization
- Hygiene guidelines (keep it durable)
- Common failure modes (avoid)
- Variants (use sparingly)
- Tailoring notes (optional extensions)
-
Prompt Templates (for drafting ADRs)
- 1) Draft a full ADR from notes
- 2) Generate options + trade-offs (when you only know the problem)
- 3) Tighten an ADR decision statement (make it unambiguous)
- 4) Review an ADR for hygiene + missing content
- 5) Convert a Mini-ADR into the full template
- 6) Write a superseding ADR (change an accepted decision)
- 7) Experimental / time-boxed ADR (agentic/AI-friendly)
ADR = one decision, one file.
It records:
- the problem and constraints
- the options considered
- the decision made
- the rationale (trade-offs)
- the consequences (good/bad/follow-ups)
- the conditions under which you’d revisit it
ADR is not:
- an implementation spec
- a PR description
- a post-hoc justification
- a dumping ground for notes
Note
ADRs capture decision-level information. Implementation detail belongs in design docs, tickets, PRs, and runbooks.
ADRs help you:
- preserve decision context and rationale
- improve onboarding and governance
- reduce “why did we do this?” churn
- enable future reversibility (or conscious irreversibility)
Write ADRs for high-leverage decisions, such as:
- platform/tool selection (build vs buy, vendor choice)
- system boundaries and ownership (domains, services, data)
- integration patterns (sync/async, events, APIs, messaging)
- security/compliance posture (authn/z, encryption, auditability)
- scalability/reliability approaches (SLOs, HA, DR, caching)
Avoid ADRs for:
- minor refactors and trivial changes
- short-lived experiments unless promoted to a decision
- “we changed a config” updates (unless they alter architecture meaningfully)
Tip
If the decision is something you’ll argue about again in 6–12 months, it probably deserves an ADR.
Short answer:
- PRDs define what must be built and why (from a product perspective).
- ADRs capture how and why key technical decisions were made to realize that PRD.
- They operate at different altitudes and should reference each other asymmetrically.
| Artifact | Owns | Answers |
|---|---|---|
| PRD (Product Requirements Document) | Product intent | What problem are we solving? For whom? What does success look like? |
| ADR (Architecture Decision Record) | Technical judgment | Given the PRD, why did we choose this approach over alternatives? |
Important
- A PRD never justifies architecture.
- An ADR never redefines product scope.
Diagram (as written):
User / Market Need
↓
PRD
↓
Architectural Constraints
↓
ADR(s)
↓
Implementation
Optional: Mermaid version (same meaning, nicer rendering on GitHub)
flowchart TD
A[User / Market Need] --> B[PRD]
B --> C[Architectural Constraints]
C --> D[ADR(s)]
D --> E[Implementation]
- PRD references ADRs (lightly)
In the PRD, include a small section:
## Architectural Considerations
- See ADR-012 (Event-driven ingestion)
- See ADR-017 (Multi-tenant auth model)This signals:
- Architecture is intentional
- Product scope assumes these decisions exist
- Product does not re-litigate them
- ADR explicitly names the PRD as context
In the ADR:
## Context
This decision supports PRD-045: Real-time Collaboration v1.This anchors the decision to:
- a concrete product outcome
- a specific moment in time
- known assumptions
- One PRD → many ADRs (normal)
A single PRD often spawns multiple ADRs:
- PRD section: Non-functional requirements → Typical ADR: scaling/performance ADR
- PRD section: Security requirements → Typical ADR: auth/data isolation ADR
- PRD section: Integrations → Typical ADR: API/eventing ADR
- PRD section: Rollout plan → Typical ADR: migration/backward-compat ADR
Note
If a PRD spawns zero ADRs, the decision surface is probably trivial—or undocumented.
Belongs in PRD:
- User personas
- User journeys
- Functional requirements
- Success metrics
- Business constraints
- “Must / Should / Won’t”
Belongs in ADR:
- Build vs buy
- Framework/platform choice
- Data model boundaries
- Sync vs async
- Consistency trade-offs
- Operational complexity accepted
Rule:
- If a sentence starts with “We will use…”, it almost always belongs in an ADR.
PRD changes:
- may invalidate ADR assumptions
- do not edit old ADRs
- write a new ADR if the decision changes
ADR supersedes:
## Status
Superseded by ADR-031Then the PRD updates its references.
- ❌ PRD embeds architecture diagrams → locks implementation prematurely
- ❌ ADR argues product value → wrong artifact
- ❌ PRD edited to justify a technical choice → backward reasoning
- ❌ One mega-ADR per product → unreviewable, unchangeable
Tip
- PRDs ask for outcomes.
- ADRs admit trade-offs.
- If trade-offs are hidden in the PRD, you lose learning.
- If product intent leaks into ADRs, you lose accountability.
Recommended statuses:
- Proposed — drafted, under review, not yet binding
- Accepted — decision is active; treat as authoritative
- Superseded — replaced by a newer ADR (link to the new one)
- Deprecated — no longer recommended, but not directly replaced
Rule of thumb:
- Accepted ADRs are immutable. If the decision changes, write a new ADR that supersedes it.
Important
“Immutable” means: no content changes beyond typos or broken links. Anything that changes meaning goes in a new ADR.
- ID: sequential (
ADR-001,ADR-002, …) - Title: short, specific, searchable (e.g., “Adopt Postgres for OLTP”)
- Location:
docs/adr/orarchitecture/adr/ - One decision per file
- Prefer filenames like:
ADR-012-adopt-postgres.md
- Write before or at decision time
- Keep under 1–2 pages
- Make assumptions explicit
- Include “Do nothing” when it’s a real alternative
- Link to the artifacts (RFCs, tickets, PRs, benchmarks), not vice versa
Tip
If you must link out, link to evidence (benchmarks, evals, tickets) and context (RFCs), not summaries.
- describing implementation details instead of the decision
- omitting rejected options (or hiding trade-offs)
- unclear “Decision” statement (no single answer)
- justification theatre (written after the fact to defend a predetermined choice)
Warning
If “Decision” contains multiple possibilities (“we might…” “we will probably…”), it’s not a decision yet.
- Mini-ADR: Context → Decision → Consequences (fast-moving teams)
- Time-boxed ADR: includes a forced review date
- Experimental ADR: Proposed + success criteria + rollback plan
Useful additions by context:
- Platform governance: decision authority, exception process, multi-org constraints
- Regulated environments: controls mapping, evidence links, approvals, audit trail
- Open-source: community impact, compatibility, contribution model, deprecation policy
- AI/agentic systems: model choice, autonomy bounds, evals, auditability, fallback modes
Note
This is the canonical full ADR template. Keep a copy in your repo and instantiate per decision.
Template (copy/paste)
<!-- Filename: ADR_Master_Template.md -->
# ADR-XXX: <Decision Title>
## Status
Proposed | Accepted | Superseded | Deprecated
## Date
YYYY-MM-DD
## Owners
- DRI: <name/handle>
- Reviewers: <names/roles>
- Approver (optional): <name/role>
## Decision Drivers
List the key forces shaping the decision:
- <driver 1: e.g., delivery speed>
- <driver 2: e.g., cost constraints>
- <driver 3: e.g., security/compliance requirements>
- <driver 4: e.g., scale/SLO targets>
- <driver 5: e.g., team skills/operational burden>
## Context
**Problem statement:**
- What problem are we solving, and for whom?
**Product context (PRD link/anchor):**
- Supports: PRD-0XX: <PRD title> (<link>)
- Architectural considerations section (optional): <link/anchor>
**Current state:**
- What exists today (systems, workflows, constraints)?
**Constraints:**
- Technical:
- Organizational:
- Regulatory/Compliance:
- Timeline/Delivery:
**Assumptions (explicit):**
- <assumption 1>
- <assumption 2>
**Non-goals (optional, but helpful):**
- <non-goal 1>
- <non-goal 2>
## Options Considered
### Option A: <Name>
**Description:**
- What it is, and how it would work at a high level.
**Pros:**
- <pro 1>
- <pro 2>
**Cons:**
- <con 1>
- <con 2>
**Risks / Unknowns:**
- <risk 1>
- <risk 2>
**Operational impact (optional):**
- On-call burden, observability, runbooks, upgrades.
---
### Option B: <Name>
**Description:**
- …
**Pros:**
- …
**Cons:**
- …
**Risks / Unknowns:**
- …
**Operational impact (optional):**
- …
---
### Option C: Do nothing / Status quo (include when relevant)
**Description:**
- Keep existing approach; document what “do nothing” actually entails.
**Pros:**
- …
**Cons:**
- …
**Risks / Unknowns:**
- …
## Decision
**We will:** <chosen option>
**Decision statement (crisp):**
- “<A single sentence that a new joiner can repeat accurately.>”
## Rationale
Why this option over others:
- <reason 1: link to driver>
- <reason 2: trade-off accepted>
- <reason 3: what was deprioritized and why>
Key trade-offs consciously accepted:
- We accept <trade-off> to gain <benefit>.
- We choose not to optimize for <deprioritized dimension> because <reason>.
## Consequences
### Positive
- <benefit 1>
- <benefit 2>
### Negative
- <cost/limitation 1>
- <cost/limitation 2>
### Neutral / Follow-ups
Required mitigations / tasks:
- [ ] <task 1> (owner: <name>, due: <date>)
- [ ] <task 2> (owner: <name>, due: <date>)
Decisions unlocked or constrained:
- Unlocks: <future direction enabled>
- Constrains: <future limitation introduced>
## Validation / Revisit Criteria
What would invalidate this decision?
- <signal 1: e.g., cost exceeds $X/month>
- <signal 2: error rate > Y% for Z days>
- <signal 3: compliance requirement changes>
Review trigger(s):
- Review on: YYYY-MM-DD (optional)
- Or review when: <event occurs>
## References
- PRD: PRD-0XX (<link>)
- RFC: <link>
- Ticket/Epic: <link>
- PR(s): <link>
- Benchmarks/Evals: <link>
- Diagrams: <link>
## Supersedes / Superseded by (optional)
- Supersedes: ADR-0XX
- Superseded by: ADR-0YYUse this when you need to write or review ADRs quickly and consistently.
-
Title + ID
ADR-0XX: Verb + Object + Scope(e.g., “Adopt Redis for rate limiting”)
-
Decision Drivers (3–7 bullets)
- cost, scale, reliability, security, delivery speed, team skills
-
Context (keep it factual)
- problem + current state + constraints + assumptions
- include PRD link / PRD ID if this decision supports a specific PRD
-
Options (at least 2; include Do nothing when relevant)
- pros/cons/risks at the decision level (not implementation details)
-
Decision (one sentence, unambiguous)
- “We will …”
-
Rationale (trade-offs)
- explicitly state what you’re not optimizing for
-
Consequences (good/bad/follow-ups)
- include action items if needed
-
Revisit criteria
- signals that would make you change your mind
-
References
- tickets/RFCs/PRs/benchmarks/diagrams
- include PRD link if applicable
-
Status & governance
- Proposed → Accepted (then immutable; supersede via new ADR)
- Decision statement is one sentence and not vague
- Assumptions are explicit
- At least one alternative option is documented
- Trade-offs are stated plainly (what you sacrificed and why)
- Consequences include follow-ups/mitigations when needed
- Revisit criteria are concrete (thresholds, events, review date)
- References link to evidence (benchmarks, evals, tickets, diagrams)
- If this supports a PRD: PRD is referenced in Context and References
- Is the problem clear and bounded?
- Are options meaningfully different (not strawmen)?
- Does the decision align with the stated drivers?
- Are risks/unknowns called out (not hidden)?
- Are consequences realistic and actionable?
- Is there an escape hatch (revisit criteria / rollback plan if applicable)?
- If a PRD exists: does the ADR stay technical (no product scope edits)?
If the decision changes:
- Do not edit the accepted ADR beyond typo fixes.
- Write a new ADR that Supersedes the old one.
- Add cross-links in both:
- old ADR: “Superseded by ADR-0YY”
- new ADR: “Supersedes ADR-0XX”
- Update PRD “Architectural Considerations” references accordingly.
Use this when the decision is real but time is tight:
- Context (include PRD link if relevant)
- Decision
- Consequences
- Revisit criteria
- References
If it grows in impact, promote it into the full template.
Add these fields (or include in Consequences / Revisit Criteria):
- Success criteria (what “good” looks like)
- Kill criteria (what forces rollback)
- Time-box (review date)
- Fallback plan (what you do if it fails)
Copy/paste these into your LLM workflow. Replace bracketed fields.
Tip
For best results, paste your notes under “Inputs” or “Context” verbatim, then refine.
Prompt
You are an expert software architect. Create an Architecture Decision Record (ADR) using the provided ADR master template.
Inputs:
- Decision title: [title]
- Date: [YYYY-MM-DD]
- Status: Proposed
- Related PRD (if any): [PRD-ID + title + link]
- Problem statement: [text]
- Current state: [text]
- Constraints: [list]
- Assumptions: [list]
- Decision drivers (prioritized): [list]
- Options considered (A/B/C): [describe each]
- Preferred option (if known): [option]
- Evidence/links: [list]
- Open questions: [list]
Requirements:
- Keep it under ~2 pages.
- Include “Do nothing / status quo” if it’s a realistic option.
- Make the Decision statement one crisp sentence.
- Make trade-offs explicit (what we are NOT optimizing for).
- Add concrete revisit criteria (thresholds/events).
- Do NOT redefine product scope from the PRD.
Prompt
Propose 3–5 viable architectural options for this problem and compare them.
Problem:
[problem statement]
Product context (optional):
- PRD: [PRD-ID + title + link]
- Non-functional requirements from PRD: [list]
Constraints:
[list]
Drivers (prioritized):
[list]
For each option include:
- Short description
- Pros (3–6)
- Cons (3–6)
- Risks/unknowns (2–5)
- When it’s the best choice
Also include “Do nothing / status quo” if applicable.
Prompt
Rewrite the “Decision” section into a single clear sentence that is unambiguous and testable.
Here is the current ADR decision text:
[paste decision text]
Also suggest 2 alternative phrasings and explain the difference in meaning briefly.
Prompt
Act as an ADR reviewer. Identify:
1) missing sections or weak areas,
2) ambiguous language,
3) hidden trade-offs,
4) missing alternatives,
5) unclear assumptions,
6) weak revisit criteria,
7) PRD/ADR boundary violations (product scope in ADR, architecture justification in PRD).
Then propose exact edits (bullet list of changes) without rewriting the entire ADR.
ADR:
[paste ADR]
Prompt
Expand this Mini-ADR into a full ADR using the ADR master template. Keep it concise (1–2 pages).
Mini-ADR:
[paste mini ADR]
If information is missing, infer reasonable placeholders and mark them as “TBD”.
Prompt
Create a new ADR that supersedes an earlier accepted ADR.
Inputs:
- Old ADR summary: [text]
- What changed and why now: [text]
- Related PRD (if any): [PRD-ID + title + link]
- New constraints/drivers: [list]
- New options considered: [list]
- Proposed new decision: [text]
Requirements:
- Include “Supersedes ADR-0XX”
- Explain the migration path / transition consequences
- Include kill criteria / rollback if relevant
- Note whether PRD “Architectural Considerations” references need updates
Prompt
Draft an Experimental ADR (Status: Proposed) for the following decision, including:
- success criteria (metrics, evals, thresholds)
- kill criteria (what forces rollback)
- time-boxed review date
- auditability/observability requirements
- fallback mode (manual or safer baseline)
Decision topic:
[text]
Context:
[text]
Product context (optional):
- PRD: [PRD-ID + title + link]
Constraints:
[list]
LinkedIn // GitHub // Medium // Twitter/X
A bit about David Youngblood...
David is a Partner, Father, Student, and Teacher, embodying the essence of a true polyoptic polymath and problem solver. As a Generative AI Prompt Engineer, Language Programmer, Context-Architect, and Artist, David seamlessly integrates technology, creativity, and strategic thinking to co-create systems of enablement and allowance that enhance experiences for everyone.
As a serial autodidact, David thrives on continuous learning and intellectual growth, constantly expanding his knowledge across diverse fields. His multifaceted career spans technology, sales, and the creative arts, showcasing his adaptability and relentless pursuit of excellence. At LouminAI Labs, David leads research initiatives that bridge the gap between advanced AI technologies and practical, impactful applications.
David's philosophy is rooted in thoughtful introspection and practical advice, guiding individuals to navigate the complexities of the digital age with self-awareness and intentionality. He passionately advocates for filtering out digital noise to focus on meaningful relationships, personal growth, and principled living. His work reflects a deep commitment to balance, resilience, and continuous improvement, inspiring others to live purposefully and authentically.
David believes in the power of collaboration and principled responsibility in leveraging AI for the greater good. He challenges the status quo, inspired by the spirit of the "crazy ones" who push humanity forward. His commitment to meritocracy, excellence, and intelligence drives his approach to both personal and professional endeavors.
"Here’s to the crazy ones, the misfits, the rebels, the troublemakers, the round pegs in the square holes… the ones who see things differently; they’re not fond of rules, and they have no respect for the status quo… They push the human race forward, and while some may see them as the crazy ones, we see genius, because the people who are crazy enough to think that they can change the world, are the ones who do." — Apple, 1997
Why I Exist? To experience life in every way, at every moment. To "BE".
What I Love to Do While Existing? Co-creating here, in our collective, combined, and interoperably shared experience.
How Do I Choose to Experience My Existence? I choose to do what I love. I love to co-create systems of enablement and allowance that help enhance anyone's experience.
Who Do I Love Creating for and With? Everyone of YOU! I seek to observe and appreciate the creativity and experiences made by, for, and from each of us.
When & Where Does All of This Take Place? Everywhere, in every moment, of every day. It's a very fulfilling place to be... I'm learning to be better about observing it as it occurs.
I've learned a few overarching principles that now govern most of my day-to-day decision-making when it comes to how I choose to invest my time and who I choose to share it with:
- Work/Life/Sleep (Health) Balance: Family first; does your schedule agree?
- Love What You Do, and Do What You Love: If you have what you hold, what are YOU holding on to?
- Response Over Reaction: Take pause and choose how to respond from the center, rather than simply react from habit, instinct, or emotion.
- Progress Over Perfection: One of the greatest inhibitors of growth.
- Inspired by "7 Habits of Highly Effective People": Integrating Covey’s principles into daily life.
David is dedicated to fostering meaningful connections and intentional living, leveraging his diverse skill set to make a positive impact in the world. Whether through his technical expertise, creative artistry, or philosophical insights, he strives to empower others to live their best lives by focusing on what truly matters.
— David Youngblood