ADR — Architecture Decision Record Skill

Purpose

Produce clear, durable records of architecture decisions so future engineers understand not just what was decided, but why, and what was ruled out.

ADR Output Template

Always produce ADRs in this exact format:

ADR-[NUMBER]: [Short Title — max 8 words]

Date: YYYY-MM-DD
Status: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
Deciders: [roles or team names, not personal names]
Tags: [e.g., database, auth, messaging, infra]

Context

What is the situation that forces this decision? Describe:

• The problem or requirement driving the decision
• Current state of the system (if applicable)
• Constraints: technical, business, time, budget
• Any external factors (compliance, team skills, existing contracts)

Write this section so that someone with no prior context understands why a decision was needed.

Decision

State the decision in one clear sentence:

We will [do X] using [Y] because [core reason].

Then elaborate in 2–3 paragraphs if needed.

Alternatives Considered

For each rejected option:

Option: [Name]

• Description: brief explanation
• Pros: what it does well
• Cons: why it was ruled out
• Verdict: rejected because [specific reason]

(Include at least 2 alternatives. If no alternatives were seriously considered, state why.)

Consequences

Positive

• List concrete benefits this decision enables

Negative / Trade-offs

• List concrete costs, limitations, or risks introduced

Neutral / Follow-up Required

• What other decisions does this unlock or constrain?
• What needs to be revisited in [timeframe]?

Validation Criteria

How will we know this decision was correct? Define measurable signals:

• Criterion 1 (e.g., "p99 latency < 100ms under 10k RPS")
• Criterion 2

References

• Links to relevant docs, benchmarks, or prior ADRs

ADR Numbering & Lifecycle

• Number ADRs sequentially per project: ADR-001, ADR-002, etc.
• Never delete an ADR — mark it Deprecated or Superseded
• When superseding, link both ADRs to each other
• Store in /docs/adr/ in the project repository

Quality Checklist

Before finalizing an ADR, verify:

• Context explains the why, not just the what
• At least 2 real alternatives are documented
• Trade-offs are honest — no decision is purely positive
• Validation criteria are measurable
• Status is set correctly