---
name: architecture-decision-record
description: "Records one technical decision with its context, the options weighed, the choice and its consequences, in a form a newcomer can understand a year from now. Use when a technical or architectural choice has been made or proposed and needs a durable record of context, options and consequences. Do not use for a full design document or meeting minutes. Related topics: coding, writing."
---

# Architecture Decision Record

Records one technical decision with its context, the options weighed, the choice and its consequences, in a form a newcomer can understand a year from now.

## When to use

Use this skill when a technical or architectural choice has been made or proposed and needs a durable record of context, options and consequences. Do not use it for a full design document or meeting minutes.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Write the context so a stranger understands the problem, constraints and deadline without being told the answer.
3. Describe each option fairly in two or three lines with its cost, including the rejected ones.
4. State the decision as one active sentence and give the deciding reasons in order of weight.
5. List consequences, covering what gets easier, what gets harder and the trigger that would reopen the decision.
6. Add date, status, decision makers and links to related records, and trim to one page.

## Inputs

- **Decision title** (free text, e.g. "A short noun phrase such as Use Postgres for events")
- **Context** (longer free text)
- **Options considered** (longer free text)
- **Chosen option** (free text, e.g. "What was picked")
- **Reason for choosing it** (longer free text)
- **Status** (choose one: Proposed, Accepted, Superseded, Deprecated)
- **Decision makers** (free text, e.g. "Names or roles")

## Output

A one-page ADR with title, status, date, context, options, decision, consequences and revisit trigger, in that order.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Architecture Decision Record

Write an ADR for this decision.

- Decision title: {{Decision title}}
- Context: {{Context}}
- Options considered: {{Options considered}}
- Chosen option: {{Chosen option}}
- Reason for choosing it: {{Reason for choosing it}}
- Status: {{Status}}
- Decision makers: {{Decision makers}}

Write for a reader who joins in a year and has none of today's context. State the context first: the situation, the constraints, the scale and the deadline, without hinting at the answer. Present each option fairly in two or three lines, including the ones you rejected, with the cost of each. State the decision in one active sentence ("We will use ..."), then explain the deciding reasons in order of weight. Spell out the consequences honestly: what becomes easier, what becomes harder, what new risks or work follow, and what would make the team revisit this choice. Keep it to one page, avoid jargon without a definition, and add the date, status and links to related records so the history can be followed.

## Pitfalls

- Describing rejected options as obviously bad, which hides the trade-offs the next reader needs to see.
- Listing only benefits under consequences, so the real cost surfaces later as a surprise.
- Leaving out the date and status, which makes an old record look like current policy.