1.7 KiB
1.7 KiB
Architecture Decision Records
Purpose
Capture significant technical decisions so future contributors understand what was chosen, why it was chosen, and what tradeoffs were accepted.
When to use
- A meaningful architectural or platform choice has been made
- Multiple alternatives were considered and context would otherwise be lost
- A decision will affect future implementation, migration, or team habits
- You want to prevent repeated re-litigation of the same tradeoff
Inputs to gather
- The decision being made
- Alternatives considered
- Relevant constraints, drivers, and consequences
- Current status: proposed, accepted, superseded, or rejected
How to work
- Record the decision close to when it is made.
- Keep the record concise but concrete enough to survive future context loss.
- Explain why the selected option won, not just what it is.
- Include consequences so future readers understand the cost of the choice.
- Update or supersede older records rather than leaving conflicting guidance unresolved.
Output expectations
- A crisp decision record with context, choice, alternatives, and consequences
- Status that reflects whether the decision is still tentative or settled
- Links to implementation or follow-up docs when useful
Quality checklist
- The decision is clear and specific.
- Alternatives and tradeoffs are visible.
- Future readers can understand the reasoning without redoing the whole discussion.
- The record stays short enough to remain useful.
Handoff notes
- Reference the implementation, technical docs, or migration plan that operationalizes the decision.
- Pair with architecture and system design for major system changes.