Architecture decision record (ADR) prompt

Paste this into a chat window and replace each {{variable}}, or open it in the prompt builder to fill them in a form. Sections are marked with XML tags, which every major model reads well.

You are a staff engineer who writes short, honest architecture decision records.

<context>
Notes, chat logs or meeting minutes from the discussion:
<discussion>
{{discussion}}
</discussion>
</context>

<constraints>
- Keep to what the discussion says. Where the notes don’t give a reason or a cost, write “Not recorded” rather than inventing one.
- List every option that was seriously considered, with the main reason it was or wasn’t chosen.
- Consequences must include the downsides the team accepted, not only the benefits.
- Plain language, no marketing tone. Aim for one page.
</constraints>

<output_format>
Markdown:
# ADR {{number}}: <short title>
Status: Accepted
## Context
## Options considered
## Decision
## Consequences
</output_format>

<task>
Write an architecture decision record for the decision: {{decision}}.
</task>

You are a staff engineer who writes short, honest architecture decision records.

<constraints>
- Keep to what the discussion says. Where the notes don’t give a reason or a cost, write “Not recorded” rather than inventing one.
- List every option that was seriously considered, with the main reason it was or wasn’t chosen.
- Consequences must include the downsides the team accepted, not only the benefits.
- Plain language, no marketing tone. Aim for one page.
</constraints>

<output_format>
Markdown:
# ADR {{number}}: <short title>
Status: Accepted
## Context
## Options considered
## Decision
## Consequences
</output_format>

<context>
Notes, chat logs or meeting minutes from the discussion:
<discussion>
{{discussion}}
</discussion>
</context>

<task>
Write an architecture decision record for the decision: {{decision}}.
</task>

{{discussion}}

The raw material: meeting notes, a Slack thread, a design doc’s comments. Messy is fine; the template is meant to distil it.

{{decision}}

The decision in one line, such as “use Postgres LISTEN/NOTIFY instead of adding Redis for job notifications”.

{{number}}

The ADR number in your log, such as 0017.

{{discussion}}

Backend lead: job workers poll the jobs table every second, ~2k queries/min at idle.
SRE: could add Redis pub/sub, but that's a new service to run and monitor.
Backend lead: Postgres LISTEN/NOTIFY does this; payload limit is 8000 bytes, we only need the job id.
SRE: what if a worker is down when NOTIFY fires? Backend lead: keep a slow poll (30s) as a fallback.
Agreed: go with LISTEN/NOTIFY + 30s poll. Revisit if we move off Postgres.

{{decision}}

Use Postgres LISTEN/NOTIFY with a 30-second fallback poll for job notifications instead of adding Redis

{{number}}

0017

What to look for. A faithful ADR lists Redis pub/sub as the rejected option (a new service to operate), records the 30-second fallback as a consequence (missed notifications are picked up late, not lost) and the tie to Postgres as an accepted downside. It shouldn’t add benchmarks nobody ran.

You are a staff engineer who writes short, honest architecture decision records.

<context>
Notes, chat logs or meeting minutes from the discussion:
<discussion>
Backend lead: job workers poll the jobs table every second, ~2k queries/min at idle.
SRE: could add Redis pub/sub, but that's a new service to run and monitor.
Backend lead: Postgres LISTEN/NOTIFY does this; payload limit is 8000 bytes, we only need the job id.
SRE: what if a worker is down when NOTIFY fires? Backend lead: keep a slow poll (30s) as a fallback.
Agreed: go with LISTEN/NOTIFY + 30s poll. Revisit if we move off Postgres.
</discussion>
</context>

<constraints>
- Keep to what the discussion says. Where the notes don’t give a reason or a cost, write “Not recorded” rather than inventing one.
- List every option that was seriously considered, with the main reason it was or wasn’t chosen.
- Consequences must include the downsides the team accepted, not only the benefits.
- Plain language, no marketing tone. Aim for one page.
</constraints>

<output_format>
Markdown:
# ADR 0017: <short title>
Status: Accepted
## Context
## Options considered
## Decision
## Consequences
</output_format>

<task>
Write an architecture decision record for the decision: Use Postgres LISTEN/NOTIFY with a 30-second fallback poll for job notifications instead of adding Redis.
</task>

• Claude

  For a long discussion, Anthropic suggests asking Claude to pull out the relevant quotes first and then work from them. Add “first list the quotes that support each section in <quotes> tags” if you want an audit trail.

• Gemini

  With a long pasted thread, Google suggests putting the material first and the request last, linked by a phrase such as “Based on the discussion above”. The builder already places the context before the task.

• All models

  Keep ADRs in the repository next to the code, so the prompt diff and normal code review work on them like any other file.

• API design reviewReview a proposed API for naming, errors, pagination, idempotency and backwards compatibility before it ships.
• Threat-model a changeMap assets, entry points and trust boundaries for a change, then list STRIDE threats with mitigations.
• Incident postmortemTurn a timeline and chat logs into a blameless postmortem: impact, causes, what went well and actions.

Edited the template? Compare your version with this one in the prompt diff, and count it for your model with the token counter. Browse all 29 prompt templates.