Add

Coding & Software

Write an Architecture Decision Record

Turns a technical decision and the options you weighed into an ADR with context, consequences and the conditions for revisiting it.

Designed for general-purpose AI assistantsPublished November 2026

Customize

Fill in the fields and the prompt updates. What you type stays in this page and is never saved or sent.

Preview

Help me write an Architecture Decision Record (ADR) for a decision my team has made or is about to make.

Decision in one sentence: {{decision}}
Project and system context: {{context}}
Options we considered: {{options considered}}
Constraints that mattered (budget, team skills, deadlines, compliance, existing systems): {{constraints}}
Why we lean toward the chosen option: {{reasons}}
Status: Proposed

Write the ADR with these sections:
- Title: a short noun phrase, numbered if I give you a number: 
- Status and date: 
- Context: the forces at play, in neutral language. A reader who joins in a year must understand why this was a real decision.
- Decision: what we will do, stated in the active voice.
- Options considered: each option with its honest strengths and weaknesses. Do not make rejected options look foolish.
- Consequences: what becomes easier, what becomes harder, and what new work or risk we accept. Separate positive, negative and neutral consequences.
- Revisit when: two or three concrete signals (scale, cost, a deadline, a new requirement) that would justify reopening the decision.

Rules: use only the facts I gave you. If a strength, weakness or number is not in my input, do not invent it. Write "unknown" or list it as a question to answer before the ADR is accepted. Keep the whole document under 500 words, and point out any place where my reasons do not actually support my decision.

5 required fields are empty and will stay as a {{placeholder}} in the copied text.

How to use it

  1. Write the options and constraints as messy bullet points. The prompt turns them into prose; you do not need to polish them first.
  2. Read the closing note about reasons that do not support the decision. If it points at a real gap, fix the reasoning before you share the ADR.
  3. Replace every 'unknown' with a fact or an owner and a date before the status changes from Proposed to Accepted.
  4. Store the ADR next to the code, for example in docs/adr/, so it is found by the people who will ask why.

Example output

Illustrative only. Real answers depend on your input and the assistant you use.

Title: ADR 007: Use a managed Postgres service instead of self-hosting

Status: Proposed, 2026-11-10

Context: The team has two engineers and no one on call for infrastructure. The database is the only stateful component. Backups are currently manual.

Decision: We will move the primary database to a managed Postgres service and stop operating our own server.

Options considered:
- Self-hosted Postgres on a VM: lowest monthly cost and full control; requires us to own backups, upgrades and failover.
- Managed Postgres: higher monthly cost and some configuration limits; backups and patching are handled for us.

Consequences:
- Positive: automated backups and point-in-time recovery; fewer pages at night.
- Negative: higher recurring cost; some extensions may be unavailable. Unknown: exact monthly cost at our size; to be filled in before acceptance.
- Neutral: connection strings and a migration window of about one evening.

Revisit when: monthly database cost exceeds the cost of a part-time infrastructure hire, or we need an unsupported extension.

Note: your reasons mention reliability, but the options do not say how often the current server has failed.

Tips

An ADR is valuable because it records what was true when the decision was made. Keep the context section factual and avoid hindsight.

Ask the assistant to argue the rejected options at their strongest before you finalize. A decision that survives a fair comparison is easier to defend later.

Short is fine. A one-page ADR that people read beats a long one that nobody opens.

Back to the Prompt Library

Related prompts

  • Working with AI Conversations

    Extract Decisions and Open Questions

    Pulls decisions, open questions and unstated assumptions out of a long conversation instead of summarizing all of it.

    Customizable fields
    2 fields

  • Coding & Software

    Write a Pull Request Description

    Turns a diff and a ticket into a pull request description with context, changes, risk and a test plan that reviewers can follow.

    Customizable fields
    6 fields

  • Learning & Research

    Compare Options in a Decision Matrix

    Builds a weighted decision matrix from your options and criteria, shows how sensitive the result is to your weights and flags missing facts.

    Customizable fields
    5 fields