Decision record template (ADR)

When to use it

• Architecture decision records (ADRs) kept in the repository next to the code
• Product and team decisions that keep getting reopened in meetings
• A decision log for a project: one record per decision, numbered in order
• Writing up a choice made in a meeting for the people who were not there

How to use this template

1. Write the context before the decision

   Start with the situation: what forces the choice, which constraints are fixed, and what happens if nobody decides. Write it for someone who joins in a year and needs to understand why this was hard. The context is the part people skip, and the part they will wish they had.

2. List the options you actually weighed

   Put every option that got serious consideration in the table, including "do nothing", and be fair to the ones you rejected. A record that only argues for the winner reads like a pitch, and the next person to propose the losing option will not trust it.

3. State the decision in one sentence

   "We will do X because Y." If it needs a paragraph, the decision is not clear yet. Then write the consequences, good and bad: what gets easier, what gets harder, and what work the decision creates.

4. Set the status and file it with the others

   A new record starts as Proposed and becomes Accepted when the deciders agree. Keep one file per decision, numbered, in a folder next to the work it concerns: a decisions folder in the repository for engineering, in the project folder for everything else. That folder is your decision log.

Why writing decisions down saves meetings

A decision that lives only in people's heads gets made again. Someone new asks why things work this way, someone senior half remembers, and the question turns into a meeting that reaches the same conclusion with less information than the first time. A decision record answers the question in two minutes of reading, with the context that was known at the time and the options that were already rejected.

Records also make change honest. When circumstances shift, you reread the context, see which assumptions no longer hold, and write a new record that supersedes the old one instead of quietly reversing it. The original stays, because the log is only useful when it is complete. In Strokes, version history saves versions of a record as it moves from Proposed to Accepted, and a reworded consequence or a changed status shows up as a diff against the version everyone agreed to.

Keep records short

• One page. The context is a paragraph, the decision is a sentence, the options table has two to four rows, and the consequences are a short list. If it runs longer, the discussion has leaked in.
• Record the decision, not the meeting. Who said what belongs in the meeting notes. Link to them from the record instead of copying them in.
• Name the deciders. A decision with nobody behind it is a suggestion. The deciders line says who agreed and who can be asked.
• Never delete a record. A decision that turned out wrong stays in the log with its status set to Superseded and a link to its replacement.