ADR#XXX Title
Topic
Describe the decision you want to make.
What is the technical or architectural concern?
Write clearly and briefly.
Problem
Explain:
- Why this decision is needed
- What issue or limitation currently exists
- What risks may happen if nothing changes
Focus on context, not the solution.
Options
List the possible solutions you are considering.
For each option, describe:
- What the solution is
- Its advantages
- Its disadvantages or trade-offs
Include at least one alternative besides your preferred choice.
Decision
State which option you choose.
Be clear and direct: “We choose Option X.”
Reasoning
Explain why you selected this option.
Answer:
- Why is this better than the alternatives?
- What trade-offs are accepted?
- How does this align with project goals?
Discussion History
When creating ADR guidelines, the Discussion History section is not the decision itself. Instead, it records how the team arrived at the decision.
It serves as a lightweight audit trail so future readers can understand:
- When the discussion happened
- Who raised the concern (optional)
- What alternatives were considered
- How the decision evolved over time
- Whether previous assumptions or decisions were changed
The goal is to preserve important context that may otherwise be lost in meeting notes, chat messages, emails, or issue trackers.
What to Include
- Date of discussion
- Key concerns or problems raised
- Important findings or discoveries
- Significant changes in direction
- Agreements reached during discussions
What Not to Include
- Detailed meeting minutes
- Every comment from every participant
- Repetition of information already documented in the Problem, Options, or Decision sections
- Unrelated discussions