Architecture Decision Record Authoring

Write clear, useful ADRs that capture the context, options, and rationale behind technical decisions. Good ADRs prevent re-litigation of decisions and help new team members understand the codebase.

Quick Reference

MADR Template Levels

Level	When to Use	Required Fields
Lightweight	Quick decisions, low impact	Status, Context, Decision, Consequences
Standard	Most architectural decisions	+ Date, Decision-makers, Drivers, Options
Full	Critical/reversible decisions	+ Confirmation, Traceability

ADR Lifecycle

proposed → accepted → [deprecated → superseded]
                   ↘ rejected

Lightweight ADR Template

For quick decisions with limited impact:

### ADR-XXX: [Short Title]

**Status**: proposed | accepted | rejected | deprecated | superseded

**Context and Problem Statement**
[2-3 sentences describing the situation and what needs to be decided]

**Decision Outcome**
Chosen option: "[Option name]"

[1-2 sentences explaining why]

**Consequences**
- Good: [positive outcomes]
- Bad: [negative outcomes or trade-offs]

Standard ADR Template

For most architectural decisions:

### ADR-XXX: [Short Title]

**Status**: proposed | accepted | rejected | deprecated | superseded
**Date**: YYYY-MM-DD
**Decision-makers**: [names or roles]

**Context and Problem Statement**
[2-3 sentences describing the situation requiring a decision.
What is the issue? Why does it need to be addressed now?]

**Decision Drivers**
- [Driver 1: e.g., "Need to support 10x current load"]
- [Driver 2: e.g., "Team has no experience with technology X"]
- [Driver 3: e.g., "Budget constraint of $X/month"]

**Considered Options**
1. [Option 1 name]
2. [Option 2 name]
3. [Option 3 name]

**Decision Outcome**
Chosen option: "[Option N]" because [1-2 sentence rationale linking to drivers].

**Consequences**
- Good: [positive outcome 1]
- Good: [positive outcome 2]
- Bad: [trade-off or negative outcome]
- Neutral: [side effect that's neither good nor bad]

Full ADR Template

For critical decisions requiring traceability:

### ADR-XXX: [Short Title]

**Status**: proposed | accepted | rejected | deprecated | superseded
**Date**: YYYY-MM-DD
**Decision-makers**: [names or roles]

**Context and Problem Statement**
[Detailed context with background information.
Include relevant constraints and dependencies.]

**Decision Drivers**
- [Driver 1 with quantifiable metric if possible]
- [Driver 2]
- [Driver 3]

**Considered Options**
1. **[Option 1 name]**: [Brief description]
2. **[Option 2 name]**: [Brief description]
3. **[Option 3 name]**: [Brief description]

**Pros and Cons of Options**

#### Option 1: [Name]
- Good: [Pro 1]
- Good: [Pro 2]
- Bad: [Con 1]

#### Option 2: [Name]
- Good: [Pro 1]
- Bad: [Con 1]
- Bad: [Con 2]

#### Option 3: [Name]
- Good: [Pro 1]
- Neutral: [Neither good nor bad]
- Bad: [Con 1]

**Decision Outcome**
Chosen option: "[Option N]" because [rationale].

**Consequences**
- Good: [outcome 1]
- Bad: [outcome 2]

**Confirmation**
[How will we verify this decision was correct?]
- [Metric or checkpoint 1]
- [Metric or checkpoint 2]

**Traceability**
- Requirements: REQ-XXX, REQ-YYY
- Tasks: TASK-XXX, TASK-YYY
- Supersedes: ADR-ZZZ (if applicable)

Writing Effective ADRs

Context Section

Do:

• State the problem clearly in 2-3 sentences
• Include relevant constraints (time, budget, team skills)
• Mention what triggered this decision

Don't:

• Write a novel (save details for options analysis)
• Assume reader knows the background
• Include the solution in the context

Decision Drivers

Quantify when possible:

Vague	Specific
"Need better performance"	"Must handle 1000 req/sec"
"Team preference"	"3 of 4 developers have React experience"
"Cost concerns"	"Budget limit: $500/month"

Considered Options

Include at least 2 options. Always include:

• The chosen option
• The obvious alternative
• "Do nothing" if applicable

Consequences

Be honest about trade-offs:

**Consequences**
- Good: Reduces API latency by 40%
- Good: Team already knows this technology
- Bad: Adds operational complexity (new service to maintain)
- Bad: Vendor lock-in to AWS
- Neutral: Requires migration of existing data (one-time effort)

ADR Numbering

Use sequential numbering within the project:

ADR-001: Database Selection
ADR-002: Authentication Strategy
ADR-003: API Versioning Approach

For domain-specific ADRs in larger projects:

ADR-AUTH-001: OAuth Provider Selection
ADR-DATA-001: Cache Strategy
ADR-INFRA-001: Container Orchestration

When to Write an ADR

Situation	ADR Level
Choosing a database	Standard or Full
Selecting a framework	Standard
API design patterns	Standard
Deployment strategy	Standard or Full
Library selection	Lightweight
Code organization	Lightweight
Naming conventions	Lightweight (or skip)

Integration with SpecKit

ADRs created during /speckit.plan should:

1. Use consistent numbering - ADR-001, ADR-002, etc.
2. Reference requirements - Link to REQ-XXX from spec
3. Be validated - /speckit.analyze checks ADR completeness
4. Trace to tasks - Tasks reference implementing ADRs

Additional Resources

For detailed patterns and examples, see:

• references/madr-full-template.md - Complete MADR template with all fields
• references/adr-examples.md - Real-world ADR examples

Checklist Before Finalizing

• Status is set (proposed for new ADRs)
• Context explains WHY a decision is needed
• At least 2 options were considered
• Decision clearly states the chosen option
• Consequences include both good AND bad
• Date and decision-makers are recorded (Standard+)