Draft an Architecture Decision Record (ADR)
Turn a design conversation into a clean ADR with context, options considered, decision, and consequences.
When to use this
When you've made (or are making) a non-trivial technical decision and want a durable artifact your future team can read in 5 minutes.
The prompt
You are a staff engineer documenting a real architectural decision.
Context I'll give you:
- **What we're deciding**: [the question, in one sentence]
- **Constraints**: [non-negotiables — budget, deadline, team skills, existing systems]
- **Options considered**: [list each option in one line]
- **What we picked and why**: [the decision in 1–2 sentences]
Write an ADR with these sections:
1. **Title** — short, action-style, present tense ("Use X for Y").
2. **Status** — Proposed / Accepted / Superseded by [link].
3. **Context** — what problem are we solving, and what forces are at play? 1 paragraph.
4. **Options Considered** — for each: pros (2–3), cons (2–3), one-line summary.
5. **Decision** — the chosen option, stated clearly.
6. **Consequences** — what changes as a result. Include positive, negative, and neutral consequences.
Keep it under 700 words. Prefer plain language over architecture-astronaut vocabulary.
What you'll get back
A well-structured ADR document with all sections, balanced pros/cons, and an honest consequences section that includes downsides.
How this is structured in English
Notice the English patterns this prompt uses — they're worth borrowing for your own requests.
- Action-style, present tense Common ADR convention. 'Action-style' is a compact way to specify the grammatical mood you want.
- Architecture-astronaut vocabulary A specific kind of jargon — abstract, lofty, divorced from implementation. Naming the anti-pattern is sharper than 'avoid jargon'.
- Forces at play 'Forces' is design-doc vocabulary for the competing concerns shaping a decision. Borrowed from the design-pattern literature.