What this prompt does
This prompt writes an Architecture Decision Record for the decision to [decision_summary] in a [system_context], motivated by [motivation] and affecting [affected_components]. Following the [adr_format] template, it documents the decision so the same debate does not reopen months later — capturing context, real alternatives, and the trade-offs you accepted.
The structure works because it forces genuine evaluation rather than post-hoc justification. The title and status carry the [adr_number], [status], and [decision_makers]. The context section explains the problem and constraints clearly enough that someone reading in [context_timeframe] understands why it was a decision point. The Options Considered section evaluates at least [options_count] alternatives — including doing nothing — each with pros, cons, effort, and risk. The Decision section states the choice and why the alternatives were rejected, Consequences lists positives, negatives, and risks to monitor with mitigations, and Implementation Notes give next steps and the metrics you will check after [review_period].
When to use it
- You made an architecture call like a database or queue change and need it recorded.
- You want real alternatives documented so the decision is not re-litigated later.
- You need the trade-offs you accepted written down for
[affected_components]. - You want a record readable by someone joining in
[context_timeframe]. - You need to define metrics to revisit the decision after
[review_period]. - Your team standardizes on a format like
[adr_format].
Example output
Expect a structured ADR that follows the chosen template top to bottom. The title takes the form ADR-[adr_number] plus an action-oriented statement of the decision, and the status line records [status], the date, [decision_makers], and any superseded ADRs. A context section describes the technical and business problem along with the constraints — budget, timeline, team skills, infrastructure — in enough depth for a future reader. An Options Considered section evaluates at least [options_count] alternatives, including the option of doing nothing, each with a description, pros, cons, estimated effort, and risk. A Decision section states the chosen option and why the alternatives were rejected, a Consequences section lists positives, negatives, risks to monitor, and mitigations, and Implementation Notes give concrete next steps and the metrics you will check after [review_period].
Pro tips
- Evaluate at least
[options_count]real alternatives, including doing nothing; a record with one option reads as justification, not a decision. - Write the context for a future reader in
[context_timeframe]who lacks today's tribal knowledge about[motivation]. - Be explicit about the trade-offs accepted in the Decision section; the rejected-alternative reasoning is what stops the debate reopening.
- Pair every negative consequence with a mitigation so the record is actionable, not just a list of risks.
- Define concrete
[review_period]metrics up front so you can later confirm whether the decision was correct. - Keep
[status]current; mark the ADR superseded rather than deleting it when a later decision overrides it.
