Write records for decisions that need to survive

A useful decision record lets someone understand the choice without reconstructing a meeting. It does not need to preserve the meeting itself. Long transcripts and chronological notes bury the conclusion among suggestions that were never adopted.

Record the decision near the material it affects, using a format the team will actually maintain. A Markdown file in the repository works for technical choices tied to code. Product rules may belong in a shared specification. Operational decisions may need to sit beside runbooks. The storage location matters less than having one known route to find the current answer.

A compact record should include:

• a direct title that names the choice;
• status such as proposed, accepted, replaced or withdrawn;
• date and owner;
• the context that forced a decision;
• the chosen behaviour;
• material consequences and constraints;
• alternatives that remain likely to be suggested again;
• links to affected contracts, implementation and later revisions.

Context should be factual. State which systems, users or constraints are involved and what uncertainty existed. Avoid a broad essay about industry practice. The next reader needs to know why this product made this choice under these conditions.

The decision itself should use testable language. "Use robust error handling" is an aspiration. "Keep a failed delivery pending, store the external response, and require an explicit retry or cancellation" defines behaviour. Where the decision leaves freedom, say so. For example, teams may choose their internal retry library provided they emit the shared event fields and follow the same terminal states.

Alternatives need only enough detail to stop old discussion repeating without context. Record why a plausible option was not chosen at that time. Do not write a case against every imaginable approach. Circumstances can change, and the record should make reconsideration possible rather than presenting the decision as permanent doctrine.

Link replacement records in both directions. When a new decision supersedes an old one, the old page should point to the current record and the current record should explain what changed. Search results often surface older documents first, so marking only the new file leaves a trap.

Test the record with the people who will use it. A developer should be able to change the relevant code consistently, a reviewer should be able to identify a conflict, and a future owner should be able to see which assumption would justify reopening it.