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