ADR (Architecture Decision Records)
When to Create ADR
Create ADR when:
- Technology stack changes (new framework, database, language)
- Architecture pattern decisions (microservices, event-driven, etc.)
- Significant design decisions with long-term impact
Do NOT create ADR for:
- Daily implementation decisions
- Small feature additions
- Bug fixes
- Refactoring without architecture changes
Directory Structure
docs/adr/
├── index.md # ADR registry
├── 0001-title.md # First ADR
├── 0002-title.md # Second ADR
└── ...
Decision Principles
- No architecture astronautics -- Every abstraction must justify its complexity. If you cannot explain why a layer exists to a new team member in one sentence, remove it.
- Trade-offs over best practices -- Name what you are giving up, not just what you are gaining. Every ADR "Consequences" section must have both Positive and Negative entries.
- Domain first, technology second -- Understand the business problem before picking tools or frameworks.
- Reversibility as criterion -- Prefer decisions that are easy to change over ones that are "optimal" right now. When two options are close, choose the more reversible one. Note reversibility explicitly in the ADR.
DDD Considerations
Evaluate options against bounded context boundaries, aggregate consistency, and domain event flows.
Context Mapping
When ADRs involve integration between contexts, identify the context mapping pattern (Shared Kernel, Customer/Supplier, Conformist, Anti-Corruption Layer, Open Host Service, Separate Ways) in the ADR.
Architecture Pattern Decision Matrix
When an ADR evaluates architectural patterns, use this matrix as a starting point for trade-off analysis:
| Pattern |
Use When |
Avoid When |
Key Trade-off |
| Modular Monolith |
Small team, unclear domain boundaries, early-stage |
Independent scaling or deployment needed per module |
Simplicity vs deployment flexibility |
| Microservices |
Clear domain boundaries, team autonomy needed, independent scaling |
Small team, early-stage product, unclear boundaries |
Autonomy vs operational complexity |
| Event-Driven |
Loose coupling, async workflows, audit trail needed |
Strong consistency required, simple request-response |
Decoupling vs eventual consistency complexity |
| CQRS |
Read/write asymmetry, complex query requirements |
Simple CRUD domains, small data volume |
Query optimization vs system complexity |
This matrix belongs in the "Considered Options" section of an ADR. Customize rows and trade-offs for the specific project context.
Communication
- Use the C4 model (Context, Containers, Components, Code) to communicate architecture at the right level of abstraction in ADR diagrams or descriptions.
- Always present at least two options with explicit trade-offs in the "Considered Options" section.
ADR Template
# [Title of the Architectural Decision]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-NNNN]
## Context and Problem Statement
[Describe the context and problem statement in 2-3 sentences]
## Considered Options
* [Option 1] - Brief description
* [Option 2] - Brief description
* [Option 3] - Brief description
## Decision Outcome
Chosen option: "[Option X]", because [justification].
## Consequences
### Positive
* [Benefit 1]
* [Benefit 2]
### Negative
* [Drawback 1]
* [Drawback 2]
### Reversibility
[How easy is it to change this decision later? What would reversal cost?]
Naming Convention
- Format:
NNNN-title-with-hyphens.md
- Example:
0001-use-redis-for-vector-search.md
Lifecycle
- ADRs are immutable once accepted
- If a decision changes, create a new ADR that supersedes the old one
- Never delete ADRs, even if superseded
1---2name: adr-patterns3description: Architecture Decision Records patterns including templates, naming conventions, and lifecycle management. Use when documenting significant architectural decisions.4---5
6# ADR (Architecture Decision Records)
7
8## When to Create ADR
9
10**Create ADR when:**
11- Technology stack changes (new framework, database, language)
12- Architecture pattern decisions (microservices, event-driven, etc.)
13- Significant design decisions with long-term impact
14
15**Do NOT create ADR for:**
16- Daily implementation decisions
17- Small feature additions
18- Bug fixes
19- Refactoring without architecture changes
20
21## Directory Structure
22
23```
24docs/adr/
25├── index.md # ADR registry
26├── 0001-title.md # First ADR
27├── 0002-title.md # Second ADR
28└── ...
29```
30
31## Decision Principles
32
33- **No architecture astronautics** -- Every abstraction must justify its complexity. If you cannot explain why a layer exists to a new team member in one sentence, remove it.
34- **Trade-offs over best practices** -- Name what you are giving up, not just what you are gaining. Every ADR "Consequences" section must have both Positive and Negative entries.
35- **Domain first, technology second** -- Understand the business problem before picking tools or frameworks.
36- **Reversibility as criterion** -- Prefer decisions that are easy to change over ones that are "optimal" right now. When two options are close, choose the more reversible one. Note reversibility explicitly in the ADR.
37
38## DDD Considerations
39
40Evaluate options against bounded context boundaries, aggregate consistency, and domain event flows.
41
42## Context Mapping
43
44When ADRs involve integration between contexts, identify the context mapping pattern (Shared Kernel, Customer/Supplier, Conformist, Anti-Corruption Layer, Open Host Service, Separate Ways) in the ADR.
45
46## Architecture Pattern Decision Matrix
47
48When an ADR evaluates architectural patterns, use this matrix as a starting point for trade-off analysis:
49
50| Pattern | Use When | Avoid When | Key Trade-off |
51|---------|----------|------------|---------------|
52| Modular Monolith | Small team, unclear domain boundaries, early-stage | Independent scaling or deployment needed per module | Simplicity vs deployment flexibility |
53| Microservices | Clear domain boundaries, team autonomy needed, independent scaling | Small team, early-stage product, unclear boundaries | Autonomy vs operational complexity |
54| Event-Driven | Loose coupling, async workflows, audit trail needed | Strong consistency required, simple request-response | Decoupling vs eventual consistency complexity |
55| CQRS | Read/write asymmetry, complex query requirements | Simple CRUD domains, small data volume | Query optimization vs system complexity |
56
57This matrix belongs in the "Considered Options" section of an ADR. Customize rows and trade-offs for the specific project context.
58
59## Communication
60
61- Use the C4 model (Context, Containers, Components, Code) to communicate architecture at the right level of abstraction in ADR diagrams or descriptions.
62- Always present at least two options with explicit trade-offs in the "Considered Options" section.
63
64## ADR Template
65
66```markdown
67# [Title of the Architectural Decision]
68
69## Status
70[Proposed | Accepted | Deprecated | Superseded by ADR-NNNN]
71
72## Context and Problem Statement
73[Describe the context and problem statement in 2-3 sentences]
74
75## Considered Options
76* [Option 1] - Brief description
77* [Option 2] - Brief description
78* [Option 3] - Brief description
79
80## Decision Outcome
81Chosen option: "[Option X]", because [justification].
82
83## Consequences
84
85### Positive
86* [Benefit 1]
87* [Benefit 2]
88
89### Negative
90* [Drawback 1]
91* [Drawback 2]
92
93### Reversibility
94[How easy is it to change this decision later? What would reversal cost?]
95```
96
97## Naming Convention
98
99- Format: `NNNN-title-with-hyphens.md`
100- Example: `0001-use-redis-for-vector-search.md`
101
102## Lifecycle
103
104- ADRs are **immutable** once accepted
105- If a decision changes, create a **new ADR** that supersedes the old one
106- **Never delete ADRs**, even if superseded
majiayu000