Architecture Decision Record (ADR)
ADR-XXXX: <Template, Short, descriptive title> Architecture Decision Record (ADR)
Notes & Guidelines
- File name: adr-0001-template.md
- One decision per ADR
- Keep it short, clear, and factual
- Decisions should support long-term scalability and operational excellence
- ADRs are living documents and may be superseded
1. Status
| Draft | Accepted | Rejected | Deprecated | Postponed |
2. Context
Problem / Need
Describe the problem or need that requires a decision (1–5 sentences). Explain why this decision is necessary now. Clearly formulate the problem to solve, make explicit decisions to move forward, align with target architecture, and set foundations for operational excellence and organizational scalability. Specific challenge or requirement. Avoid combining multiple architecture decisions in one document.
- Background and constraints (technical, business, regulatory, organizational)
- Scope and assumptions
3. Decision
Describe the decision clearly and concisely (1–3 sentences).
- What is being decided?
- Where does it apply?
- When does it take effect?
4. Rationale (Justification)
Explain why this decision was made.
4.1. Advantages
- …
- …
- …
4.2. Known drawbacks / accepted risks
- …
- …
- …
5. Alternatives Considered / Considered Options
List the alternatives that were evaluated and briefly explain why they were not chosen.
- Alternative A – reason rejected
- Alternative B – reason rejected
- Alternative C – reason rejected
6. Consequences, Impacts & Follow-up Actions
Describe the consequences of this decision.
- Technical impact
- Organizational / process impact
- Cost or operational impact
- Required follow-up actions (tasks, reviews, migrations, documentation updates)
7. References
- Links to relevant documentation
- Standards, RFCs, blog posts, or research
- Related ADRs
8. Related ADRs
ADR-XXXX: <Template, Short, descriptive title> Ultra-light Architecture Decision Record (ADR)
Use this when speed and simplicity are more important than detail.
1. Status:
| Draft | Accepted | Rejected | Deprecated |
2. Context
…
3. Decision
…
4. Rationale (Justification):
…
3. Consequences, Impacts & Follow-up Actions
…
https://adr.github.io/