Architecture Decision Record (ADR)

A lightweight document that records a specific technical decision — the context that forced it, what was decided, alternatives considered, and the consequences. ADRs create a permanent, searchable record of why the system is built the way it is.

Syntax

claude-documentation

Title: [Short decision description]
Status: Proposed | Accepted | Deprecated | Superseded
Date: [YYYY-MM-DD]

Context:
[Situation or problem that forced this decision]

Decision:
[What was decided]

Alternatives Considered:
- Option A: [description, pros, cons]
- Option B: [description, pros, cons]

Consequences:
Positive: [What this makes easier]
Negative: [What this makes harder]
Neutral: [Trade-offs with no clear winner]

Example

claude-documentation

// ADR prompt
Write an ADR for the decision to use PostgreSQL instead of MongoDB.
Context: B2B SaaS with complex relational data, schema mostly known upfront.
Include: decision, 3 alternatives (MongoDB, DynamoDB, CockroachDB),
trade-off analysis, consequences on scalability and team skills.