Architecture Decision Record (ADR) Skill

This skill provides guidelines for creating Architecture Decision Records - structured documentation of significant architectural decisions.

Purpose

ADRs capture important architectural decisions along with their context, alternatives considered, and consequences. They create a historical record of why things are built the way they are.

User Need

"Why did we decide to do it this way?"

Characteristics

Target Directory

Place ADRs in: docs/architecture/ with naming convention ADR-NNN-short-title.md

Writing Guidelines

DO

• State the context and problem clearly
• Document all alternatives considered
• Explain why alternatives were rejected
• List both benefits and drawbacks
• Include implementation notes
• Use consistent status labels
• Number ADRs sequentially

DON'T

• Skip the context section
• Omit alternatives that were considered
• Hide drawbacks of the chosen approach
• Forget to update status when decisions change
• Write ADRs for trivial decisions

When to Write an ADR

• Choosing between competing technologies
• Establishing patterns that will be reused
• Making breaking changes to existing systems
• Decisions that are costly to reverse
• Decisions that affect multiple teams or components

Examples of Good ADRs

• "ADR-001: Use PostgreSQL for primary database"
• "ADR-002: Adopt microservices architecture"
• "ADR-003: Implement event sourcing for audit log"
• "ADR-004: Choose React for frontend framework"
• "ADR-005: Use JWT for API authentication"

ADR Status Values

Template

Use this template when creating an Architecture Decision Record:

# ADR-[Number]: [Short Title]

*Date: [YYYY-MM-DD]*
*Status: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]*
*Deciders: [List of people involved in the decision]*

## Context

[Describe the issue motivating this decision. What is the problem we're facing? What constraints exist? What forces are at play?]

[Include relevant technical, business, and organizational context.]

## Decision

[State the decision that was made. Use active voice: "We will..." or "The system will..."]

[Be specific about what changes will be made and what approach will be taken.]

## Consequences

### Benefits

- [Positive outcome 1]
- [Positive outcome 2]
- [Positive outcome 3]

### Drawbacks

- [Negative outcome or trade-off 1]
- [Negative outcome or trade-off 2]

### Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How to address] |

## Alternatives Considered

### Alternative 1: [Name]

[Description of this alternative]

**Pros:**
- [Advantage]

**Cons:**
- [Disadvantage]

**Why rejected:** [Reason this wasn't chosen]

### Alternative 2: [Name]

[Description]

**Pros:**
- [Advantage]

**Cons:**
- [Disadvantage]

**Why rejected:** [Reason]

## Implementation Notes

[Any notes relevant to implementing this decision]

- [Implementation detail 1]
- [Implementation detail 2]

## References

- [Link to relevant documentation]
- [Link to discussion/RFC]
- [Link to related ADRs]

---

## Change Log

| Date | Author | Change |
|------|--------|--------|
| [Date] | [Name] | Initial draft |

Quality Checklist

Apply this checklist before finalizing any ADR.

Context

• Problem is clearly stated
• Constraints are documented
• Business and technical context included
• Scope is defined

Decision

• Decision is explicitly stated
• Active voice used ("We will...")
• Specific about what changes
• Approach is clear

Consequences

• Benefits are documented
• Drawbacks are honestly stated
• Risks are identified with mitigations
• Both short and long-term impacts considered

Alternatives

• Multiple alternatives considered
• Each alternative fairly evaluated
• Rejection reasons are clear
• Pros and cons for each

Metadata

• Status is current
• Date is accurate
• Deciders are listed
• ADR number is sequential

ADR-Specific

• Appropriate for an ADR (not trivial)
• Self-contained and understandable
• Links to related ADRs if any
• Implementation notes if needed

Maintainability

• References are linked
• Change log started
• Easy to update status later
• No broken links

Formatting

• Consistent heading structure
• Tables properly formatted
• Lists are clear
• Readable and scannable