Architecture Decision Record for a Technology Choice

Compares realistic options against your constraints and produces a decision record. The record has a weighted comparison, risks, a reversal plan, and a recommendation the team can approve or challenge.

You get: ADR header, context and problem and criteria and weights table

More like this

The prompt

architecture-decision-record-for-a-technology-choice.md
Role: You are a pragmatic software architect advising {team_context}.Context: The team must decide {decision_topic} and record it as an Architecture Decision Record. The recommendation must be defensible against stated constraints. Do not claim to have browsed the web or benchmarked anything. Mark any external fact as Needs verification.
Task: Evaluate the options and write the ADR with a clear recommendation.

Inputs:
- Decision to make: {decision_topic}
- Options under consideration: {options}
- Functional and non-functional requirements: {requirements}
- Constraints (budget, team skills, timeline, compliance, existing stack): {constraints}
- Current architecture summary: {current_architecture}
- Scale expectations: {scale}
- Decision deadline and approvers: {deadline_approvers}

Workflow:
1. List missing information and which items would change the recommendation.
2. State assumptions separately.
3. Define 5 to 8 decision criteria from the inputs and assign weights summing to 100, with the reason for each weight.
4. Score each option from 1 to 5 per criterion with a one-line justification. Add an option that is not listed only if it is a genuine contender (for example, do nothing or extend the current system).
5. Analyze risks, migration effort, operational burden, and lock-in for the top two options.
6. Make a recommendation, with the conditions under which you would choose differently.
7. Define a reversal plan and a review date.

Constraints:
- Do not invent benchmarks, prices, or vendor claims. Use ranges or Needs verification.
- Keep the weights tied to the supplied constraints, not to generic best practice.
- Be explicit about team skill fit and operational cost.

Output format:
1. ADR header: Title, Status (Proposed), Date placeholder, Deciders.
2. Context and problem.
3. Assumptions and missing information.
4. Criteria and weights table.
5. Scoring table: Option by Criterion, with weighted totals.
6. Risk table: Risk, Option, Likelihood, Impact, Mitigation.
7. Decision and consequences (positive, negative, neutral).
8. Reversal plan and review trigger.
9. Next actions: validation spikes, with a suggested timebox.

Acceptance criteria:
- The recommendation follows from the weighted scores, or the gap is explained.
- Every score has a justification.
- Unverified facts are labeled.
- The ADR can be pasted into a repository docs folder as is.

Quality checks:
- Recompute the weighted totals and confirm that the weights sum to 100.
- Confirm that each option is evaluated against the same criteria.
- Confirm that risks and the reversal plan are specific.
- Confirm that no claim about performance or cost is presented as measured.

Tool notes: In ChatGPT or Claude, ask for the tables in Markdown so they render in your docs. If you use a model with file upload, attach architecture diagrams and say which diagram applies.

Example output

AI-written example

ADR-014: Background Job Queue for Invoice and Email Processing

Status: Proposed | Date: YYYY-MM-DD | Deciders: Priya N. (Eng Lead), Marcus T. (CTO), Elena R. (SRE)

Context

A six-engineer B2B SaaS team runs a Django monolith on managed PostgreSQL. Cron-triggered scripts process invoices and emails and fail silently. We need retries, visibility, and at-least-once delivery. Expected load is about 50k jobs/day, with peaks near 5 jobs/sec. Decision is due in two weeks, and the feature ships in Q3.

Assumptions and Missing Information

  • No dedicated SRE; Elena splits her time with platform work.
  • Jobs are idempotent or can be made so.
  • Missing: the Postgres connection headroom (could change the outcome), the 12-month job growth forecast, and whether compliance requires data to stay in one region.
  • Needs verification: managed Postgres CPU headroom at peak.

Criteria and Weights

CriterionWeightReason
Team skill fit25Six engineers, none with broker experience
Operational burden25No dedicated SRE
Delivery reliability20Invoices are financially sensitive
Migration effort vs. deadline20Q3 ship date
Lock-in/portability10Moderate concern
Total100

Scoring (1–5)

CriterionA: Postgres queueB: Managed cloud queueC: Self-hosted RabbitMQ
Skill fit5, team knows SQL3, new SDK and IAM2, new system
Ops burden4, existing DB backups5, fully managed (Needs verification)2, cluster upkeep
Reliability3, depends on DB health4, built-in retries and dead-letter queue4, mature acks
Migration5, no new infra3, networking and IAM setup2, provisioning and monitoring
Lock-in5, portable SQL2, vendor APIs4, open protocol
Weighted total4.353.602.60

Risks

RiskOptionLikelihoodImpactMitigation
Queue load degrades the app DBAMediumHighSeparate schema, connection cap, load-test spike
Outgrowing the DB at 10x volumeALowMediumWrap enqueue behind an interface
IAM or config errors cause lost jobsBMediumMediumDead-letter queue and alarms
Vendor c
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Provide real constraints such as team size, existing stack, and compliance needs, because they drive the weights. Use the suggested validation spikes to verify the facts marked Needs verification before the ADR status moves from Proposed to Accepted.

Questions about this prompt

More in Coding

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Explain This Error with Ranked Causes

Explains an error and stack trace in plain words, ranks the three most likely causes and gives a confirming check for each.

Regex with Match and Non-Match Test Strings

Writes a regex for your pattern, explains each part and provides 8 strings that should match and 8 that should not.

SQL Query from Schema and Question

Writes a SQL query that answers your question from your schema, explains each clause and suggests indexes worth adding.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Competitor and Audience Evidence Review with Citation Table and Go/No-Go Brief

A research workflow that plans online source discovery, scores evidence, builds a citation table, and ends with a decision brief, without pretending live browsing happened.

Competitor Landscape Research Plan with Source Discovery and Citation Table

Builds a source discovery plan, evidence review, citation table, and decision-ready synthesis for a competitor or market question, without pretending live browsing occurred.

Competitor Landscape Scan with Source-Backed Citation Table

Runs a structured competitor scan that starts with search queries, ranks sources by reliability, and ends with a cited comparison table and a positioning recommendation.

Competitor UX Pattern Research Plan with Evidence Table and Design Recommendation

Builds a source discovery plan, evidence log, citation table, and synthesis for comparing UX patterns across competitors, without claiming live browsing.

Design System Component Spec Writer for Figma Handoff

Produces a developer-ready component specification covering anatomy, variants, states, tokens, accessibility, and open questions from a short component brief.

Evidence Review Plan for a Classroom Teaching Strategy Decision

Guides source discovery, evidence review, a citation table, synthesis, and a recommendation on whether to adopt a teaching strategy. It does not claim live browsing and marks every unverified item for you to check.