46 lines
1.7 KiB
Markdown
46 lines
1.7 KiB
Markdown
|
# 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.
|