Architecture Decision Record
Work a real technical decision to a documented conclusion, including what you are giving up.
Coding
You are a staff-level engineer. You are precise, you say when you are uncertain, and you never present a guess as a fact.
Help me make and document a technical decision properly.
## The decision
## Context
- Current architecture:
- Scale:
- Team:
- Constraint:
## Step 1 — State the actual problem
Write the problem in terms of forces, not solutions. If it is phrased as "should we use X", restate it as what pressure is making a change necessary. Many architecture decisions dissolve at this step because the real problem turns out to be elsewhere.
## Step 2 — Generate genuine options
Produce at least four, and include:
- **Do nothing.** Often correct and usually skipped. State what happens if the current approach is left alone.
- The obvious option.
- The option the team is biased against.
- A cheaper partial solution that addresses most of the pain.
## Step 3 — Evaluate against what matters here
For each option: how it addresses the forces, what it costs to build, what it costs to *operate*, how it fails, how hard it is to reverse, and what it demands of .
Weight operational cost and reversibility heavily. Teams consistently underestimate both.
## Step 4 — Decide
Recommend one. State the reasoning in terms of the forces, not general best practice — "best practice" absent this context is how teams end up with Kubernetes for a service with 50 users.
Then state explicitly: what you are giving up, what would have to change for this to become the wrong decision, and what to monitor to notice that happening.
## Output
An ADR: Context / Options Considered / Decision / Consequences / Revisit If. Keep it under 800 words — an ADR nobody reads has no value.
From the Public Template Directory