engineering
Architecture Decision Record
Write Architecture Decision Records (ADRs) that capture context, options considered, decision rationale, and consequences — creating a searchable decision log for future engineers.
ADRarchitecturedecisionsdocumentationtechnical-decisions
Works well with agents
Works well with skills
architecture-decision-record/
SKILL.md
Markdown| 1 | |
| 2 | # Architecture Decision Record |
| 3 | |
| 4 | ## Before you start |
| 5 | |
| 6 | Gather the following from the user: |
| 7 | |
| 8 | 1. **What decision needs to be recorded?** (Technology choice, pattern adoption, architectural change) |
| 9 | 2. **What problem triggered this decision?** (The constraint, requirement, or pain point) |
| 10 | 3. **What options were considered?** (At least 2-3 alternatives, including "do nothing") |
| 11 | 4. **Who are the stakeholders?** (Teams or individuals affected by this decision) |
| 12 | 5. **Is the decision already made or still in proposal?** (Status: proposed, accepted, deprecated, superseded) |
| 13 | |
| 14 | If the user says "we decided to use Kafka," push back: "What problem does Kafka solve that your current approach doesn't? What alternatives did you evaluate? An ADR without alternatives considered is just an announcement." |
| 15 | |
| 16 | ## ADR template |
| 17 | |
| 18 | ### Header |
| 19 | |
| 20 | Every ADR starts with a sequential number, title, and metadata. |
| 21 | |
| 22 | ``` |
| 23 | # ADR-0017: Use PostgreSQL for Event Storage Instead of DynamoDB |
| 24 | |
| 25 | - **Status**: Accepted |
| 26 | - **Date**: 2025-01-15 |
| 27 | - **Decision makers**: @alice (tech lead), @bob (architect), @carol (DBA) |
| 28 | - **Consulted**: Platform team, Data engineering team |
| 29 | - **Supersedes**: ADR-0008 (if applicable) |
| 30 | ``` |
| 31 | |
| 32 | Use a descriptive title that states the decision, not the problem. "Use PostgreSQL for Event Storage" is a decision. "Event Storage" is a topic. |
| 33 | |
| 34 | ### 1. Context |
| 35 | |
| 36 | Describe the situation that requires a decision. Include: |
| 37 | |
| 38 | - The business or technical driver |
| 39 | - Current state and its limitations |
| 40 | - Constraints (timeline, budget, team expertise, compliance) |
| 41 | - Non-functional requirements that influence the decision |
| 42 | |
| 43 | Write this for an engineer joining the team 12 months from now. They were not in the room — give them enough context to understand why this decision was even necessary. |
| 44 | |
| 45 | ### 2. Options Considered |
| 46 | |
| 47 | List every option evaluated, including "do nothing." For each option, describe how it addresses the problem and its tradeoffs. |
| 48 | |
| 49 | For each option, include pros, cons, and an estimated cost or effort. Always include "do nothing" as an option — sometimes the cost of change exceeds the cost of the current pain. |
| 50 | |
| 51 | ### 3. Decision |
| 52 | |
| 53 | State the chosen option clearly and concisely. |
| 54 | |
| 55 | State the chosen option in one sentence. Then explain the rationale — why this option over the alternatives. Connect the reasoning to the constraints stated in the context. Explicitly address why each rejected option was not chosen. |
| 56 | |
| 57 | ### 5. Consequences |
| 58 | |
| 59 | Document what changes as a result of this decision — both positive and negative. |
| 60 | |
| 61 | Include three categories: **Positive consequences** (benefits gained), **Negative consequences** (costs and limitations accepted), and **Risks** (what could go wrong, with mitigation strategies). |
| 62 | |
| 63 | ### 6. Follow-Up Actions |
| 64 | |
| 65 | List concrete next steps. Every action needs an owner and a deadline. |
| 66 | |
| 67 | ## ADR numbering and filing |
| 68 | |
| 69 | - Number ADRs sequentially: ADR-0001, ADR-0002, etc. |
| 70 | - Store ADRs in a dedicated directory: `docs/adr/` or `decisions/` |
| 71 | - Use filenames that match: `0017-use-postgresql-for-event-storage.md` |
| 72 | - Maintain an index file (`README.md` or `INDEX.md`) linking to all ADRs with title, status, and date |
| 73 | |
| 74 | When a decision is reversed, don't delete the original ADR. Mark it as **Superseded** and link to the new ADR that replaces it. |
| 75 | |
| 76 | ## Quality checklist |
| 77 | |
| 78 | Before finalizing the ADR, verify: |
| 79 | |
| 80 | - [ ] Title states the decision, not just the topic |
| 81 | - [ ] Context explains the problem without jumping to the solution |
| 82 | - [ ] At least 3 options are evaluated, including "do nothing" |
| 83 | - [ ] Each option includes pros, cons, and cost or effort estimate |
| 84 | - [ ] Rationale explicitly explains why rejected options were not chosen |
| 85 | - [ ] Consequences include both positive and negative outcomes |
| 86 | - [ ] Risks are identified with mitigation strategies |
| 87 | - [ ] Follow-up actions have owners and deadlines |
| 88 | - [ ] Status is clearly marked (proposed, accepted, deprecated, superseded) |
| 89 | |
| 90 | ## Common mistakes to avoid |
| 91 | |
| 92 | - **Writing the ADR after the decision is forgotten.** Write the ADR while the context is fresh — ideally as part of the decision-making process, not weeks later. Retrospective ADRs lose the "why" behind rejected options. |
| 93 | - **Only documenting the chosen option.** The value of an ADR is understanding why alternatives were rejected. Without options considered, a future engineer can't tell if circumstances have changed enough to revisit the decision. |
| 94 | - **Confusing ADRs with design docs.** An ADR captures a decision and its rationale. A design doc describes how to implement it. Keep ADRs focused on the what and why, not the implementation details. |
| 95 | - **No "do nothing" option.** Always include it. Sometimes the cost of change exceeds the cost of the current pain. Making that explicit prevents unnecessary migrations. |
| 96 | - **Vague consequences.** "There may be some performance impact" is not useful. "Write throughput ceiling drops from 500K to 200K ops/sec, requiring sharding above that threshold" gives future engineers something actionable. |
| 97 |