Create an ADR when making decisions about technology choices, system boundaries, API design, data models, or architectural patterns.
When to Write an ADR
- Choosing between technologies or frameworks.
- Defining service boundaries or API contracts.
- Changing data models or storage strategies.
- Establishing new patterns that other code will follow.
- Any decision that would be hard to reverse.
Process
- Create the ADR file:
docs/adr/NNNN-<short-title>.md - Number sequentially (0001, 0002, etc.).
- Fill in the template below.
- Submit as a PR for review before implementation begins.
Template
# NNNN. <Title>
## Status
Proposed | Accepted | Deprecated | Superseded by [NNNN]
## Context
What is the problem or decision we need to make? What forces are at play?
Keep this to 2-3 sentences.
## Options Considered
### Option A: <name>
- Pros: ...
- Cons: ...
### Option B: <name>
- Pros: ...
- Cons: ...
## Decision
What did we decide and why?
## Consequences
What are the positive and negative results of this decision?
What becomes easier? What becomes harder?
Rules
- Keep it concise — one page max.
- Document the why, not just the what.
- Always include at least two options considered.
- An ADR that says "we chose X because it's the best" without explaining alternatives is incomplete.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.