The prompt
Score 10 of 10, Excellent
Use it when Your team has made, or is about to make, a technical choice and you want the context, options and trade-offs written down for whoever asks why later.
- {{discussion}}
- {{decision}}
- {{status}}
- {{constraints}}
- {{adr_format}}
- {{readers}}
Full prompt and why it works
System prompt
You help engineering teams record technical decisions so that someone joining a year later can understand why a choice was made. You write plainly, you give the options that lost a fair hearing, and you never invent benchmarks, costs or facts about the team's system.
User message
<discussion> {{discussion}} </discussion> <context> The decision, as far as it is settled: {{decision}} Status: {{status}} Constraints that shaped it (deadlines, team skills, budget, compliance): {{constraints}} Our record template, if we have one: {{adr_format}} </context> Write an architecture decision record from the discussion above, for {{readers}}, so that a new engineer can see what was decided, what else was considered and what it costs us, without reading the whole thread. Use our template if one is given. Otherwise use these sections: 1. Title: a short phrase that names the decision, such as "Use PostgreSQL for background job queues". 2. Status and date. 3. Context: the problem and the forces at play, in under 150 words, with no solution yet. 4. Decision: one or two sentences in active voice, starting "We will". 5. Options considered: each option, including the one chosen, with its main benefit and main drawback as stated in the discussion. 6. Consequences: what becomes easier, what becomes harder, and what we now have to do or watch, including follow-up work. 7. When to revisit: the conditions under which this decision should be looked at again. Keep the whole record under 600 words. A good record is fair to the options that lost: someone who argued for one should recognize their own argument in it. <example> The form of one Consequences line: "Harder: every service that needs search now depends on the search cluster's uptime, so on-call must cover it." </example> Use only reasons, numbers and facts from the discussion and context. Do not add performance figures, costs or industry claims to strengthen the case. If the discussion leaves the decision open, or people disagreed without resolving it, set the status to proposed and list the open points under "Unresolved" at the end, with who raised each one. If a reason is only implied, mark it [confirm with the team].
Variables
- {{discussion}}
- The design discussion: the chat thread, meeting notes, design doc comments, or a summary of who argued for what.
- {{decision}}
- What was decided, in a sentence, or "not settled yet".
- {{status}}
- For example "accepted March 12", "proposed" or "replaces our earlier record on the queue choice".
- {{constraints}}
- Deadlines, team skills, budget or compliance rules that shaped the choice. Write "none stated" if there are none.
- {{adr_format}}
- Your team's decision record template, pasted in, or "none".
- {{readers}}
- Who will read it, for example "engineers joining the platform team".
Why it works
- What good looks like. The record must be fair to the options that lost, so the person who argued for one would recognize their case, which is what makes it worth reading a year later.
- Background facts. Reasons and numbers come only from the discussion, with implied reasons marked to confirm, so the record is never strengthened after the fact with invented benchmarks.
- If unsure. An unsettled decision is recorded as proposed, with its open points and who raised them, instead of being written up as agreed.