Architecture Decision Record Writer
The Architecture Decision Record Writer produces a well-structured ADR that captures the full context behind a technical decision, evaluates alternatives with explicit trade-offs, and documents the consequences for future team members. It follows the widely adopted ADR format (title, status, context, decision, consequences) while adding depth that turns a perfunctory record into a genuinely useful historical document.
Software architects, senior engineers, tech leads, and engineering managers use this template when making significant technical decisions: choosing a database, adopting a framework, defining an API strategy, selecting a deployment model, or establishing a coding convention. It is particularly valuable for distributed teams where decisions are made asynchronously and the reasoning must be captured for people who were not in the room.
The prompt goes beyond a blank template by requiring you to articulate the forces driving the decision (technical constraints, business requirements, team capabilities, timeline pressure) and to evaluate each option against these forces. This structured comparison prevents the common failure mode where an ADR says "we chose X" without explaining why X beat the alternatives. The consequences section explicitly separates positive outcomes, negative trade-offs, and risks, giving future readers the complete picture they need to understand whether the original reasoning still holds.
This prompt is just the starting point
Score it with AI, optimize it with one click, track versions, and build your prompt library.
The Prompt
Write an Architecture Decision Record (ADR) based on the following inputs: **Decision Title**: [SHORT DESCRIPTIVE TITLE, e.g., "Use PostgreSQL as the primary datastore", "Adopt event-driven architecture for order processing", "Migrate from REST to GraphQL for the public API"] **Status**: [proposed / accepted / deprecated / superseded by ADR-XXX] **Context and Problem Statement**: [DESCRIBE THE SITUATION THAT REQUIRES A DECISION. Include: - What system or component is affected - What problem or opportunity triggered this decision - Any relevant constraints (budget, timeline, team skills, compliance requirements) - Current state (what exists today, if anything)] **Options Considered**: 1. [OPTION 1: Name and brief description] 2. [OPTION 2: Name and brief description] 3. [OPTION 3: Name and brief description] [Add more if applicable. Include the "do nothing" option if relevant.] **Decision Drivers** (the forces that matter most for this decision): - [e.g., "Must handle 10,000 concurrent connections"] - [e.g., "Team has deep expertise in Python but no Go experience"] - [e.g., "Must be SOC 2 compliant"] - [e.g., "Budget limited to $500/month for infrastructure"] Write the ADR with these sections: 1. **Title**: ADR-[NUMBER]: [DECISION TITLE] 2. **Status**: [As provided above] 3. **Date**: [TODAY'S DATE] 4. **Context**: Expand the problem statement into 2-3 paragraphs that give a reader with no prior context everything they need to understand why this decision was necessary. Include the technical landscape, business drivers, and constraints. 5. **Decision Drivers**: List each driver as a prioritized, numbered item with a brief explanation of why it matters. 6. **Options Considered**: For each option, provide: - A 2-3 sentence description of how it would work - **Pros**: 3-5 specific advantages, tied to the decision drivers - **Cons**: 3-5 specific disadvantages, tied to the decision drivers - **Estimated effort**: Rough implementation effort (small / medium / large) - **Risk level**: (low / medium / high) with a one-sentence justification 7. **Decision**: State the chosen option clearly in one sentence. Then explain in 2-3 paragraphs why this option was selected over the alternatives, referencing specific decision drivers and trade-offs. 8. **Consequences**: - **Positive**: What improves as a result of this decision - **Negative**: What trade-offs the team accepts - **Risks**: What could go wrong and what mitigation is in place - **Follow-up actions**: Specific tasks that need to happen to implement this decision (with owners if known) 9. **References**: Links or citations to relevant documentation, benchmarks, or prior ADRs.
Usage Tips
- Write the context for someone joining the team in six months: The most common ADR failure is assuming the reader has the same context as the decision makers. Include details that feel obvious today but will not be in the future.
- Include the "do nothing" option: Explicitly evaluating the status quo forces you to articulate why change is necessary and establishes a baseline for comparing alternatives.
- Be honest about the cons of the chosen option: An ADR that lists only positives for the selected option loses credibility. Future readers will trust the document more if it openly acknowledges trade-offs and explains why they were acceptable.
- Link decision drivers to business outcomes: "Must handle 10,000 concurrent connections" is stronger when paired with "because our Q3 growth projections show peak traffic doubling." This helps future readers evaluate whether the original constraints still apply.
- Store ADRs in the repository, not a wiki: ADRs are most useful when they live alongside the code they describe. Use a
/docs/adr/directory in your repository so they are versioned, searchable, and naturally discovered during code review.
Get more from this prompt
Save it, score it with AI, optimize it, and track every version. Free to start.