Architecture Decision Records

Create, evaluate, or manage Architecture Decision Records (ADRs) that document significant technical decisions with their context, trade-offs, and consequences.

Workflow

Step 1: Understand the Decision Context

Gather information about the decision:

• What problem are we solving? Understand the requirement or constraint driving the decision.
• What are the constraints? Budget, timeline, team skills, existing infrastructure, compliance.
• Who are the stakeholders? Teams affected by this decision.
• What existing decisions does this relate to? Check for prior ADRs in the project.

If the project has an docs/adr/ or docs/decisions/ directory, read existing ADRs to understand established patterns and numbering conventions.

Step 2: Identify and Research Options

For each viable option:

• Describe how it would work in this specific context.
• List concrete pros (benefits, strengths, alignment with constraints).
• List concrete cons (risks, costs, operational burden).
• Identify unknowns or assumptions that affect the evaluation.
• Note team experience and ecosystem maturity.

Research considerations:

• Check the project's tech stack for compatibility.
• Consider operational complexity (deployment, monitoring, debugging).
• Evaluate vendor lock-in and migration paths.
• Assess the total cost of ownership, not just initial implementation.

Step 3: Evaluate Trade-offs

Build a comparison matrix across dimensions:

Weight criteria based on the specific project context, not generic importance.

Step 4: Write the ADR

Use the output format below. If a numbering scheme exists in the project, follow it. Otherwise, use the date-based format.

Step 5: Place the File

• If docs/adr/ or docs/decisions/ exists, write there.
• Otherwise, suggest creating docs/adr/ and write the first ADR.
• Use the naming convention: NNNN-short-title.md (e.g., 0001-use-postgres-for-primary-store.md).

Output Format

# ADR-NNNN: <Title of Decision>

## Status

Proposed | Accepted | Deprecated | Superseded by ADR-XXXX

## Date

YYYY-MM-DD

## Context

<2-4 paragraphs describing the problem, constraints, and why a decision
is needed now. Include relevant technical context, business requirements,
and any forcing functions.>

## Decision Drivers

- <driver 1: e.g., "Must handle 10k events/second at peak">
- <driver 2: e.g., "Team has no Kafka operational experience">
- <driver 3: e.g., "Budget constraint of $500/month for messaging">

## Options Considered

### Option 1: <Name>

<Description of how this would work in our context.>

**Pros:**
- <concrete benefit>
- <concrete benefit>

**Cons:**
- <concrete drawback>
- <concrete drawback>

### Option 2: <Name>

<Same structure.>

### Option 3: <Name>

<Same structure.>

## Decision

We will use **<chosen option>** because <primary rationale>.

<1-2 paragraphs explaining the reasoning, how it aligns with decision
drivers, and why the trade-offs are acceptable.>

## Consequences

### Positive
- <expected benefit>

### Negative
- <accepted trade-off or new burden>

### Risks
- <risk and mitigation>

## Follow-up Actions

- [ ] <action item with owner>
- [ ] <action item with owner>

## References

- <link or citation>

Examples

User: "Should we use Kafka or SQS for our event pipeline?" Action: Research both options in context of the project, compare on throughput, cost, operational complexity, team experience, and write an ADR recommending one with clear reasoning.

User: "Document our decision to use a monorepo" Action: Write an ADR capturing the context, alternatives considered (polyrepo, hybrid), and the reasoning for choosing a monorepo.

User: "Evaluate this architecture proposal" (with a document or description) Action: Read the proposal, identify strengths, gaps, risks, and unstated assumptions, and produce a structured evaluation.

Best Practices

• ADRs capture the decision AND the context — future readers need to understand why, not just what.
• Include options that were rejected. Understanding what was NOT chosen is as valuable as what was.
• Be specific about consequences. "Increased complexity" is vague. "Requires the team to learn and operate Kubernetes, estimated 2-week ramp-up" is actionable.
• Keep ADRs immutable once accepted. If a decision changes, write a new ADR that supersedes the old one.
• Link related ADRs to each other to create a navigable decision history.
• Weight trade-offs by what matters for THIS project, not in the abstract. A startup prototype and a regulated financial system have very different priorities.
• When evaluating existing proposals, be constructive. Identify gaps and risks, but also acknowledge strengths.