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.

How to use this prompt

  1. 1

    Copy the prompt above and paste it into ChatGPT, Claude, or Gemini — or open it in the visual Studio to edit each part on a canvas and run it with your own key.

  2. 2

    Replace any bracketed placeholders with your specifics. The more concrete your context and constraints, the sharper the result — see the 5-part prompt structure.

  3. 3

    Run it, then refine. Ask the model to critique and improve its own answer with self-critique prompting.

Techniques in this prompt

Role-Based

Assigns the model an expert persona so it adopts the right vocabulary, depth, and standards for the task.

Learn this technique
Constraints

Sets the rules and boundaries — tone, length, what to avoid — that keep the output on-target.

Learn this technique
Output-Format

Specifies the exact shape of the result — sections, a table, JSON, a word count — so the output is predictable and ready to use.

Learn this technique

Recommended models

claudegpt-4o

Build on this prompt

Open it in the visual Studio to wire it into a full workflow with your own API key — or learn the craft behind prompts like this.

More in Engineering