Architecture Decision Record (ADR) Template

## ROLE

You are a principal architect who has authored and reviewed hundreds of Architecture Decision Records across organizations of all sizes. You understand that ADRs are not bureaucratic overhead — they are the institutional memory that prevents teams from relitigating the same decisions, helps new team members understand why the system is built the way it is, and provides the context needed to know when a decision should be revisited. You have seen the damage caused by undocumented architectural decisions: teams that repeat past mistakes, engineers who reverse decisions without understanding the original constraints, and organizations that cannot onboard new architects because the rationale behind the system exists only in the heads of people who left. Your ADR process is lightweight enough to encourage adoption but thorough enough to capture the essential context.

## OBJECTIVE

Create a comprehensive ADR template and process guide for a [TEAM SIZE: 5-10 / 10-25 / 25-50 / 50-100 / 100+] person engineering organization building [PRODUCT TYPE: web application / mobile app / SaaS platform / microservices / data platform / developer tools / embedded systems / enterprise software]. The team's architectural decision-making process is currently [STATE: informal and verbal / partially documented in wiki pages / inconsistent across teams / non-existent]. The goal is to establish a lightweight, consistently-followed ADR practice that captures decisions within [TIME: 30 minutes / 1 hour / 2 hours] of writing time per decision.

## TASK: COMPLETE ADR TEMPLATE & PROCESS GUIDE

### Section 1 — ADR Document Structure

Define the standard ADR document template with these sections. The header contains the ADR number (sequential, never reused), title formatted as a short decision statement rather than a topic (use "Use PostgreSQL for Primary Data Storage" not "Database Selection"), status (proposed, accepted, deprecated, superseded by ADR-XXX), date of the last status change, and the decision makers listing who participated in and approved the decision. The Context section describes the forces at play: what is the technical or business situation that requires a decision, what problem are we solving, what constraints exist (budget, timeline, team expertise, existing infrastructure, compliance requirements), and what has changed since the last related decision that makes this decision necessary now. This section should be written so that someone unfamiliar with the project can understand why this decision matters. Target [LENGTH: 200-400] words for context. The Decision Drivers section lists the specific criteria that will be used to evaluate options, ordered by priority. Each driver should be a clear, measurable statement rather than a vague quality: not "good performance" but "must handle [NUMBER] requests per second with p99 latency under [TIME]", not "easy to maintain" but "the team has at least [NUMBER] engineers with production experience in the technology", not "cost effective" but "total cost of ownership under [$AMOUNT] per month at projected scale." Include both technical drivers (performance, scalability, reliability, security, maintainability) and business drivers (time to market, licensing cost, hiring availability, vendor lock-in risk, compliance requirements).

### Section 2 — Options Analysis Framework

Define the options evaluation section that presents [NUMBER: 2-5] viable alternatives with equal rigor. For each option, provide the following analysis. Name and brief description in one sentence explaining what this option entails at the highest level. Detailed description in [LENGTH: 150-300] words explaining how this option would be implemented, what the architecture would look like, and what the development and operational workflow would involve. Advantages listed as bullet points covering every benefit of this option relative to the decision drivers — be specific and quantitative where possible. Disadvantages listed as bullet points covering every drawback, risk, and limitation — be equally rigorous here as in the advantages, resisting the temptation to minimize drawbacks of the preferred option or exaggerate drawbacks of rejected options. Proof of concept results if applicable: if a spike or prototype was built to evaluate this option, include the results with specific numbers (latency measurements, throughput benchmarks, development time for a representative feature, migration effort estimate). Cost analysis including licensing or subscription costs, infrastructure costs at current and projected scale, development effort to implement, operational effort to maintain, and migration costs if transitioning from an existing system. Risk assessment identifying the top [NUMBER: 2-4] risks of choosing this option with likelihood, impact, and mitigation strategies for each. Include a comparison matrix that scores each option against each decision driver on a [SCALE: 1-5 / 1-10 / meets/partially meets/does not meet] scale, with the scoring rationale documented for any non-obvious scores.

### Section 3 — Decision & Rationale

Document the chosen option and the reasoning that led to the selection. The decision statement should be a single clear sentence: "We will use [OPTION] for [PURPOSE]." The rationale section explains why this option was selected over the alternatives, organized by decision driver: for each driver, state which option scored highest on that driver and why, and which drivers were the tiebreakers when options were closely matched. Be explicit about the trade-offs being accepted: "We are choosing [OPTION A] over [OPTION B] despite [SPECIFIC DISADVANTAGE] because [REASONING], and we accept the risk of [SPECIFIC RISK] because [MITIGATION STRATEGY]." Document any dissenting opinions: if team members disagreed with the decision, record their concerns and the reasoning for proceeding despite the disagreement. This is not about blame — it is about intellectual honesty and providing future decision-makers with the full context. If the decision was influenced by constraints that may change over time (budget limitations, team size, regulatory requirements, vendor contracts), explicitly note these as conditions that could trigger a re-evaluation. Define the decision scope and boundaries: what does this decision cover and what does it explicitly not cover, preventing scope creep where a database selection decision gets interpreted as a mandate for data modeling patterns.

### Section 4 — Implementation Plan & Consequences

Describe how the decision will be implemented and what its consequences are. Define the implementation approach: will this be implemented all at once or incrementally, does it require a migration from an existing system, what is the timeline for implementation, and who is responsible for leading the implementation. Identify the positive consequences: what improvements will the team experience, what new capabilities will be available, what problems will be resolved, and what metrics should improve. Identify the negative consequences: what new constraints does this decision impose on future work, what technical debt does it create, what learning investment is required, and what operational burden does it add. List the follow-up actions with owners and deadlines: specific tasks that must be completed to implement the decision, documentation that must be updated, team members who must be trained, monitoring and alerting that must be configured, and any dependent decisions that are now unblocked or newly required. Define the success criteria: how will we know this decision was correct, what metrics will we measure [TIMEFRAME: 1 month / 3 months / 6 months] after implementation, and what would cause us to revisit this decision.

### Section 5 — Decision Lifecycle Management

Define the process for managing ADRs throughout their lifecycle. The proposal stage: any engineer can write an ADR proposal, which is submitted as a pull request to the [REPOSITORY: dedicated ADR repo / docs folder in the main repo / wiki]. The review stage: the PR triggers a review from [REVIEWERS: the architecture guild / senior engineers / affected team leads / the entire engineering team], with a review period of [DURATION: 3 business days / 1 week / 2 weeks] during which reviewers comment with questions, concerns, and alternative perspectives. The acceptance stage: after the review period, the decision maker (the architect, engineering manager, or consensus of the review group) updates the status to accepted and merges the PR, or requests revisions if the analysis is incomplete. The supersession stage: when a new decision replaces an old one, the old ADR's status is updated to "superseded by ADR-XXX" with a brief note explaining what changed, and the new ADR references the old one in its context section. ADRs are never deleted — even bad decisions have valuable context. Define the re-evaluation triggers: significant changes to the constraints listed in the original ADR (budget change, team growth, technology maturity, compliance requirements), recurring problems that suggest the decision is not working as expected (tracked through incident post-mortems and retrospectives), and scheduled review dates for decisions with explicit time-bound constraints. Establish the ADR index: maintain a searchable table of all ADRs with columns for number, title, status, date, category, and affected components, making it easy to find relevant prior decisions when evaluating a new one.

### Section 6 — ADR Examples & Anti-Patterns

Provide [NUMBER: 2-3] complete example ADRs for common architectural decisions that teams face. Example one: choosing between a monolithic and microservices architecture for a new product, with the context explaining the team size, expected scale, and delivery timeline, three options analyzed (monolith, microservices from day one, modular monolith with extraction plan), and the decision to start with a modular monolith with clearly defined module boundaries that can be extracted into services when specific scaling triggers are hit. Example two: selecting an authentication strategy with options analyzed for session-based auth, JWT tokens, and OAuth2 with a third-party provider, evaluating security, development effort, user experience, and operational complexity. Include these as complete, filled-out templates that demonstrate the level of detail and analysis rigor expected. Document the anti-patterns that undermine the ADR process: the rubber stamp ADR where the decision was already made and the ADR is written after the fact to justify it rather than to evaluate options honestly, the novel-length ADR that tries to document every tangentially related consideration and becomes too long for anyone to read or review, the options theater ADR that presents obviously inferior options alongside the preferred choice to create the illusion of analysis, the missing context ADR that documents what was decided but not why which makes it useless for future re-evaluation, and the orphaned ADR that is written but never reviewed, never communicated to the team, and never referenced again.