Architecture Decision Records (ADRs)

Purpose

ADRs capture important architectural decisions along with their context and consequences. They serve as:

• Living documentation of why decisions were made
• Onboarding material for new team members
• Reference for future architectural discussions
• Audit trail of technical evolution

The Job

1. Receive a description from the user
2. Ask 3-5 essential clarifying questions (with lettered options)
3. Generate a structured ADR based on answers
4. Save ADR to adr/NNN-short-description.md

Important: Do NOT start implementing. Just create the ADR.

When to Ask Clarifying Questions

Ask only critical questions where the initial prompt is ambiguous. Focus on:

• Problem/Goal: What problem does this solve?
• Core Functionality: What are the key actions?
• Scope/Boundaries: What should it NOT do?
• Success Criteria: How do we know it's done?

When to Write an ADR

Create an ADR when:

• Adding a significant new feature
• Making architectural changes (new services, data models, integrations)
• Choosing between multiple technical approaches
• Introducing new dependencies or technologies
• Changing existing patterns or conventions

File Naming Convention

adr/NNN-short-description.md

• NNN: Sequential number (001, 002, 003...)
• short-description: Lowercase with hyphens, present-tense imperative
• Examples: 001-data-model.md, 002-authentication-strategy.md, 003-caching-layer.md

What ADRs Should NOT Include

ADRs document design decisions, NOT implementation details.

ADRs are about the what and the why, not the how. They capture architectural choices and their rationale, but leave implementation specifics to the code, tickets, or implementation plans.

Do NOT Include:

• ❌ Step-by-step implementation plans
• ❌ Specific file paths or code structure
• ❌ Detailed component interfaces or type definitions
• ❌ Lists of files to create or modify
• ❌ Database migration scripts
• ❌ Detailed UI mockups or wireframes
• ❌ Implementation timelines or task breakdowns

DO Include:

• ✅ What decision was made and why
• ✅ Architectural patterns and principles chosen
• ✅ High-level design approach
• ✅ Technology/library choices with rationale
• ✅ Trade-offs and alternatives considered
• ✅ Expected consequences (positive and negative)

Example of what NOT to do:

markdown
1## Implementation
2
3### New Files
4
5- src/components/Button.tsx
6- src/hooks/useButton.ts
7
8### Modified Files
9
10- src/app/page.tsx (add import)

Example of what to DO:

markdown
1## Decision
2
3### Component Architecture: Compound Pattern
4
5We will use a compound component pattern for complex UI elements,
6allowing flexible composition while maintaining consistent behavior.

ADR Template

markdown
1# ADR NNN: Title
2
3## Status
4
5Proposed | Accepted | Deprecated | Superseded by [ADR-XXX](./XXX-title.md)
6
7## Context
8
9[Describe the situation, business need, or technical challenge that motivates this decision]
10
11- What problem are we solving?
12- What are the requirements and constraints?
13- What forces are at play (technical, business, organizational)?
14
15## Decision
16
17### [Decision Area 1]
18
19[Describe the chosen approach with rationale]
20
21| Aspect | Choice | Rationale |
22| ------ | ------ | --------- |
23| ...    | ...    | ...       |
24
25### [Decision Area 2]
26
27[Continue for each major decision area]
28
29## Alternatives Considered
30
31### Alternative 1: [Name]
32
33[Describe the alternative approach]
34
35**Rejected because:**
36
37- Reason 1
38- Reason 2
39
40### Alternative 2: [Name]
41
42[Continue for each alternative considered]
43
44## Consequences
45
46### Positive
47
481. [Benefit 1]
492. [Benefit 2]
50
51### Negative
52
531. [Drawback 1]
542. [Drawback 2]
55
56### Mitigations
57
58- **[Drawback]:** [How we address it]
59
60## Verification (Optional)
61
62### Success Criteria
63
64- [What outcomes indicate this decision is working]
65- [How to measure success of this approach]
66
67### Edge Cases to Consider
68
69- [Unusual scenarios this decision should handle]
70- [Boundary conditions to be aware of]
71
72## References
73
74- [Related ADR](./NNN-related.md)
75- [External documentation](https://example.com)

Section Guidelines

Status

Use one of:

• Proposed - Under discussion, not yet approved
• Accepted - Approved and ready for implementation
• Deprecated - No longer recommended
• Superseded by [ADR-XXX] - Replaced by a newer decision

Context

The context section should:

• Explain the business or technical need driving this decision
• Describe current limitations or pain points
• List requirements and constraints
• Identify stakeholders and their concerns
• Be written so someone unfamiliar with the project can understand

Decision

Structure decisions as sub-sections when multiple related choices are made. Focus on what is being chosen and why, not implementation details.

Include tables for comparing options or summarizing architectural choices. Avoid implementation-level details like specific file paths or interfaces.

Alternatives Considered

Document rejected approaches to:

• Show due diligence in evaluation
• Prevent revisiting the same ideas later
• Help future readers understand trade-offs

Format as:

markdown
1### Alternative: [Name]
2
3[Brief description]
4
5**Rejected because:**
6
7- [Concrete reason tied to project constraints]

Consequences

Split into positive and negative, then add mitigations:

markdown
1### Positive
2
31. **Improved UX** - [Specific benefit]
42. **Performance** - [Specific benefit]
5
6### Negative
7
81. **Cost** - [Specific drawback]
92. **Complexity** - [Specific drawback]
10
11### Mitigations
12
13- **Cost:** [How we address it]
14- **Complexity:** [How we address it]

Focus on architectural trade-offs and long-term impacts, not implementation hurdles.

Verification (Optional)

When architectural decisions have testable outcomes, describe what should be verified, not how to implement tests.

Keep verification focused on architectural concerns, not test implementation details.

Leverage Existing Architecture

Before proposing new solutions, thoroughly explore the existing codebase and previous ADRs. Avoid reinventing the wheel by understanding and building on established architectural patterns, services, and design principles.

Principles

1. Understand before proposing - Learn how similar problems are currently solved
2. Extend, don't duplicate - Build on existing architectural patterns
3. Follow established patterns - Maintain architectural consistency
4. Reuse proven approaches - Leverage what already works
5. Leverage platform capabilities - Use existing framework/platform features before adding new ones

Before Writing an ADR, Investigate

Good Example: Building on Existing Patterns

markdown
1### Storage Strategy: Follow Existing Pattern
2
3The application already uses pattern X for similar data (see ADR 001).
4We will apply the same pattern here to maintain architectural
5consistency and avoid introducing new infrastructure.

Why this is good: References existing architectural decisions, shows understanding of current patterns, explains how new feature fits into established architecture.

Bad Example: Ignoring Existing Architecture

markdown
1### Storage Strategy: Custom New Service
2
3We will add a new microservice and a new datastore...

Why this is bad: Ignores existing platform capabilities, introduces new infrastructure and dependencies, creates architectural inconsistency.

Checklist Before Proposing New Approaches

• Have I reviewed how similar features work in this codebase?
• Does the existing platform/framework already provide this capability?
• Am I following the same architectural patterns used elsewhere?
• Have I checked previous ADRs for relevant decisions?
• Will this integrate with existing services and patterns?
• Am I adding unnecessary dependencies or complexity?

Style Guidelines

1. Use tables for structured comparisons (options evaluation, architectural aspects)
2. Use code blocks sparingly for illustrating architectural concepts or patterns, not for showing implementation code
3. Use ASCII diagrams for architectural concepts when helpful:

   ┌─────────────────────────────────┐
   │  High-Level Component Flow      │
   │  Client → API → Storage         │
   └─────────────────────────────────┘
   

4. Be specific about choices - Name the technology, pattern, or approach chosen
5. Be concise - Focus on decisions and rationale; avoid implementation prose
6. Link related ADRs - Reference previous decisions that inform this one
7. Avoid implementation specifics - No file paths, detailed code, or step-by-step instructions

References

• Michael Nygard's ADR article
• ADR GitHub Repository
• MADR Template