adr-format-alexandrian

Alexandrian ADR Format

The Alexandrian format is inspired by Christopher Alexander's pattern language. It emphasizes the forces influencing decisions and the resulting context after applying a solution.

About Alexandrian Format

The Alexandrian format is:

• Pattern-oriented - Follows pattern language structure
• Force-focused - Emphasizes competing forces
• Context-rich - Detailed before/after context
• Relationship-aware - Links to related patterns/decisions

Template Structure

# {NUMBER}. {TITLE}

Date: {DATE}

## Status

{STATUS}

## Context

{Background and current state}

## Problem

{Clear problem statement}

## Forces

* {Force 1}
* {Force 2}
* {Force 3}

## Solution

{Chosen solution}

## Resulting Context

### Benefits
* {Benefit 1}
* {Benefit 2}

### Drawbacks
* {Drawback 1}
* {Drawback 2}

### Related Patterns/Decisions
* {Related ADR or pattern}

Section Guide

Context

Describe the background:

• Project state
• Team composition
• Organizational factors
• Technical environment

Problem

State the problem clearly:

• What issue needs resolution?
• What question needs answering?
• Frame as a specific challenge

Forces

List forces influencing the decision:

• Technical requirements
• Business constraints
• Team factors
• Organizational pressures

Forces often pull in different directions, creating tension that the decision must resolve.

Example:

## Forces

* Need for high availability (99.99% uptime SLA)
* Limited budget ($5K/month infrastructure)
* Team expertise in Kubernetes
* Requirement for data residency in EU
* Desire to minimize operational overhead

Solution

Describe the chosen solution:

• What will be done
• How it addresses the forces
• Specific implementation approach

Resulting Context

Document the state after applying the solution:

Benefits - Positive outcomes achieved Drawbacks - Negative consequences accepted Related Patterns/Decisions - Connections to other ADRs or architectural patterns

When to Use Alexandrian Format

Best for:

• Decisions with complex, competing forces
• Pattern-oriented teams
• Decisions requiring detailed context
• Situations with many constraints

Consider other formats when:

• Quick documentation needed
• Forces are straightforward
• Team prefers simpler templates

Alexandrian Best Practices

Documenting Forces

• List 4-8 forces for most decisions
• Include both technical and non-technical forces
• Note which forces are in tension
• Prioritize or weight forces if helpful

Resulting Context

• Be honest about drawbacks
• Link to decisions that address drawbacks
• Note conditions that would trigger revisiting

Additional Resources

Templates

Template available at: ${CLAUDE_PLUGIN_ROOT}/templates/alexandrian/adr-template.md

External Resources

• "A Pattern Language" by Christopher Alexander
• Pattern-Oriented Software Architecture