---
name: architecture-decision-record
title: Architecture Decision Record
description: "Structured framework for making and recording architecture decisions. Produces an ADR document with context, constraints, options analysis, decision rationale, and consequences. Prevents the \"why did we do it this way?\" problem months later. Works for any stack — from monolith to microservices, from database choice to API design."
category: coding
tags:
  - architektura
  - podejmowanie-decyzji
  - dokumentacja
  - projektowanie-systemów
  - planowanie
requires:
  - Claude
source: https://madejski.ai/skilloteka/architecture-decision-record
locale: en
license: MIT
---

# Architecture Decision Record (ADR)

## What This Skill Does

Guides you through making an architecture decision and produces a permanent record. The ADR answers the question that always comes up 6 months later: *"Why did we do it this way?"*

This is not documentation for documentation's sake. It's a decision-forcing function that:
1. Forces you to articulate the actual problem (not the symptom)
2. Maps constraints before jumping to solutions
3. Evaluates options against explicit criteria
4. Records the decision with full rationale
5. Lists consequences so future-you knows what trade-offs were accepted

## When to Use

- Choosing between technology stacks, frameworks, or databases
- Defining API contracts, data models, or service boundaries
- Deciding on deployment strategies, CI/CD patterns, or infrastructure
- Resolving competing architectural approaches on the team
- Any decision that would be expensive to reverse

## ADR Template

### 1. Title
`ADR-{number}: {Short decision title}`

### 2. Status
`Proposed | Accepted | Deprecated | Superseded by ADR-{n}`

### 3. Context
What is the issue? Why does this decision need to be made now? What forces are at play?

**Rules:**
- State facts, not opinions
- Include technical constraints (performance, scale, compatibility)
- Include organizational constraints (team size, skill set, timeline, budget)
- Reference any prior decisions this builds on

### 4. Decision Drivers
Ranked list of criteria that matter most:
- Performance requirements (latency, throughput, resource usage)
- Developer experience (learning curve, tooling, debugging)
- Operational cost (hosting, maintenance, monitoring)
- Security posture
- Time to implement
- Reversibility

### 5. Options Considered

For each option:
| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| Performance | ... | ... | ... |
| Dev Experience | ... | ... | ... |
| Cost | ... | ... | ... |

**Rules:**
- Minimum 2 options, maximum 5
- Always include "Do nothing / Status quo" as an option
- Pros AND cons for each — no option is all-good
- Be honest about unknowns: "We don't know X yet"

### 6. Decision
One clear sentence: "We will use [X] because [Y]."

### 7. Consequences

**Positive:**
- What gets better as a result of this decision

**Negative (trade-offs accepted):**
- What gets worse or harder
- What risks are introduced

**Neutral:**
- What changes but isn't clearly better or worse

### 8. Follow-up Actions
Concrete next steps to implement the decision.

## Process

1. **Gather context** — ask about the problem, constraints, team, timeline
2. **Identify options** — propose alternatives (research if needed)
3. **Build comparison matrix** — evaluate each against decision drivers
4. **Make recommendation** — with explicit rationale
5. **Document** — produce the ADR in markdown format
6. **Challenge** — play devil's advocate on the chosen option

## Anti-Patterns

- Documenting a decision already made just to check a box (the analysis must be genuine)
- Analysis paralysis — if options are close, say so and pick one
- Ignoring "do nothing" — it's often the right answer
- Hiding trade-offs — every option has downsides, list them
- Over-engineering the evaluation for trivial decisions