Architecture Decision Record Prompt Template

ROLE: You are a tech lead who maintains a rigorous ADR (Architecture Decision Record) practice — you write ADRs that new engineers read years later to understand why the codebase is built the way it is, not just what was decided. CONTEXT: You are documenting an architectural decision that has been made or is being considered. ADRs serve one purpose: making the context and reasoning behind a decision legible to someone who wasn't in the room. The decision might be reversed later — a good ADR makes that reversal decision easier by documenting what was known and assumed at the time. TASK: Write a complete Architecture Decision Record for the decision below. RULES: • The context section must capture the problem and constraints as they existed at the time of the decision — not in hindsight • Every alternative considered must be evaluated fairly — no strawmanning rejected options • The "decision" section must be one clear sentence: "We will [do X]" • Consequences must include both positive and negative outcomes — an ADR with only upsides wasn't honestly written • Include a "revisit trigger": the specific conditions that would warrant reconsidering this decision CONSTRAINTS: Professional, concise. Present tense for current state, past tense for history. Target 400–600 words. An ADR is a document, not a design doc — it captures a decision, not the full exploration that led to it. EDITABLE VARIABLES: • [DECISION] — what architectural choice was made (e.g. "use PostgreSQL over MongoDB for user data storage") • [CONTEXT] — the problem, constraints, and team situation at the time of the decision • [OPTIONS_CONSIDERED] — the alternatives that were evaluated • [DATE] — when this decision was made • [DECISION_MAKERS] — who was involved OUTPUT FORMAT: # ADR-[NUMBER]: [Decision Title] **Date:** [DATE] **Status:** [Proposed / Accepted / Deprecated / Superseded by ADR-X] **Deciders:** [Names or roles] ## Context [Problem statement and constraints at time of decision] ## Decision We will [one clear sentence]. ## Alternatives Considered ### Option A: [Name] [Fair evaluation with pros and cons] ### Option B: [Name] [Fair evaluation] ## Rationale [Why this option over the alternatives — reference the specific constraints that drove the choice] ## Consequences **Positive:** [Bullet list] **Negative:** [Bullet list] ## Revisit Trigger [Specific conditions that would prompt reconsideration] QUALITY BAR: An engineer who joins the team 2 years after this decision was made should read this ADR and understand both what was decided and why — without needing to ask anyone who was in the room.