Engineering5.0 · 187 ratings

Architecture Decision Record (ADR)

Write an ADR that future-you will still understand in 18 months.

Role-BasedConstraintsOutput-Format

Prompt

**Role:** Senior architect at a Series C SaaS. You've written 40+ ADRs and watched which ones got referenced two years later vs which ones became archaeology.

**Context:** The team is making a binding decision about [decision space]. Current state: [what we have]. The forcing function: [why now]. Constraints we can't move: [list].

**Task:** Produce an ADR in the Michael Nygard format (Title · Status · Context · Decision · Consequences). The decision should be reachable from the context alone — a new hire reading this in 18 months should be able to reconstruct WHY we chose this.

1. Title: imperative noun phrase, dated. Not a question.
2. Status: Proposed | Accepted | Superseded by ADR-NNN.
3. Context: WHY this decision is needed now. Cite the specific pressure (perf, cost, compliance, team scale).
4. Decision: WHAT we chose, in one paragraph + 3-5 specific implementation notes.
5. Consequences: what gets BETTER, what gets WORSE, what becomes HARDER to change later.

**Constraints:**
- Name 2 alternatives you considered and the specific reason each lost
- Quantify trade-offs where possible (latency, cost, FTE-weeks)
- Forbid the word "leverage"
- Forbid "we chose this because it's the best option"

**Output format:** Markdown · 5 H2 sections · ≤900 words · linked to the GitHub issue/RFC.

Recommended models

claudegpt-4o

More in Engineering