Draft an Architecture Decision Record
Records the decision, the forces behind it and the costs it accepts — with a one-line reason each rejected option lost.
Last updated
Fill in the blanks
Assembled in your browser — nothing you type is stored or sent anywhere.
Your prompt
Model-agnostic — works in Claude, ChatGPT, Gemini or any AI chat.
Why this prompt works
- →Requiring costs alongside benefits in Consequences is the entire point of an ADR — a record that only lists upside reads as marketing copy and helps nobody revisit the decision later.
- →Asking for the one-line reason each rejected option lost preserves what future readers actually need: not just what was chosen, but what was ruled out and why, so it isn't re-litigated.
- →The prompt for missing context stops the model from backfilling a business rationale that sounds reasonable but wasn't the real reason, which would make the record historically inaccurate.
Part by part
- Context (the forces and constraints that made this decision necessary)
- The section that gives an ADR its value years later. A decision without its constraints reads as arbitrary once the constraints have changed.
- stated as one clear sentence
- Forces the decision itself to be unambiguous. A paragraph here usually means the decision was not actually made.
- never write a consequences section that is all upside
- The instruction that does the most work. An ADR listing only benefits is advocacy, and it fails the one job of telling a future reader what was traded away.
- For each rejected option, give the one-line reason it lost
- Preserves the alternatives. Most of an ADR's future value is stopping someone re-proposing an option that was already considered and rejected for a reason.
- inventing a plausible-sounding business justification
- Names the specific failure. Asked to write a Context section with no real context, a model will produce convincing reasoning that nobody in the room ever gave.
Common mistakes
Write an ADR for using Postgres.With no context and no rejected options, the model invents both — producing a document that looks like a record of a decision and records nothing that happened.
Document why we chose this architecture.Invites justification rather than record-keeping, so the output argues for the decision instead of describing its costs. An ADR that cannot be read against the decision is not doing its job.
Write an ADR with pros and cons.Pros and cons is a decision-making format; consequences is a record of what you now accept. The difference is tense and it matters — the decision is already made.
Questions
Why must consequences include costs?
Because that is the section a future reader needs most. Knowing what a decision traded away is what lets them judge whether the trade still holds, and an all-upside record gives them nothing to reassess.
Should an ADR be updated when things change?
No — supersede it with a new one that references the old. An ADR is a record of what was decided and why at a point in time, and editing it destroys the history it exists to preserve.
How much context is enough?
Enough that someone who was not in the room can tell why this was decided now rather than earlier or later. If the model has to invent that, the honest answer is that the decision has not been articulated yet.
Are the rejected options really necessary?
They are the most reread part. Without them the same alternative gets proposed every year, and each time the team relitigates a discussion it already had and cannot remember the outcome of.