Published history

Every published version keeps its original contributor and change message.

1. Current version

   Initial publication

   Contributor 350ocLmT · 2026-11-06

   Read exact source · Restore by submitting this source as a new revision.

   Read this version

   Decision records that stay useful: a template and a complete example

   A decision record explains what a team chose, why the choice made sense at the time, and what would justify revisiting it. Use one when a future colleague is likely to ask, “Why did we do it this way?”

   Michael Nygard's architecture decision record proposal describes short records organised around context, decision, status, and consequences. The practical template below adds alternatives, evidence, and review triggers. It can work for product and operational choices as well as software architecture.

   When a record is worth writing

   Write one for a choice that constrains future work, crosses team boundaries, carries a meaningful migration cost, or repeatedly generates debate. A small local formatting choice rarely needs one. A policy for exporting customer data probably does.

   Keep one main decision per record. Separate related choices when they have different owners or could be reversed independently. Link records together so that a reader can follow the reasoning without one enormous document.

   A copyable template

   # D-000: [Decision stated as an action]
   Status: Proposed / Accepted / Superseded
   Date:
   Decision owner:
   Scope:
   
   ## Context
   What problem must be solved? What constraints are confirmed?
   Which assumptions remain untested?
   
   ## Options considered
   Include the current approach. Compare against the same criteria.
   
   ## Decision
   What will we do, and where does the decision apply?
   
   ## Reasons and evidence
   Which observations support the choice? Link dated evidence.
   Separate measured results from forecasts and preferences.
   
   ## Consequences
   Benefits, costs, limitations, and new responsibilities.
   
   ## Validation and review
   How will we check the outcome? Who owns that check?
   What specific change would trigger reconsideration?
   
   ## Related records
   Predecessors, replacements, and implementation work.
   

   Complete fictional example

   D-014: Generate large report exports in a background worker

   Status: Accepted. Date: 6 November 2026. Owner: Reporting team. Scope: Large report exports in the example application.

   Context. Users need downloadable reports that can take longer to generate than an ordinary page request. The application already operates a background worker. The product must show progress and allow a user to return later. For this fictional example, the team assumes that a report may take up to three minutes; this is a planning assumption, not a measured benchmark.

   Options considered.

   Option	Main benefit	Main cost or limitation
   Keep generation inside the web request	Simplest interaction and fewer moving parts	User remains attached to a long request; failure recovery is awkward
   Use the existing worker	Fits the existing operational model; allows status tracking	Requires a job state model, retries, and cleanup
   Add a new reporting service	Can scale independently	Adds a service and operational responsibilities before that need is demonstrated

   Decision. Generate large exports using the existing worker. The web request creates a job and returns its identifier. The UI reads job status and offers the download when ready. Small existing exports remain in their current path until measured behaviour justifies changing them.

   Reasons and evidence. The strongest reason is reuse of an operational capability the team already owns. The team has not demonstrated that a separate service improves this workload. Before rollout, it will measure representative report sizes, duration, memory use, and failures. The decision is provisional on those checks meeting an agreed rollout target.

   Consequences. Users can leave the page and return to the job. The team must implement explicit pending, running, succeeded, and failed states; a bounded retry policy; cancellation semantics; and cleanup of expired results. Job lookup and download must check the requesting user's access. Retries must avoid creating confusing duplicate outputs. A worker outage can delay exports even while the main application remains available.

   Validation and review. Before rollout, record test conditions and acceptance targets, then verify status transitions, recovery from interrupted work, access checks, and result expiry. During the first two weeks, the reporting team will review completion duration and failure rate. Reconsider the architecture if representative jobs consistently miss the agreed duration target, compete materially with other worker tasks, or require isolation the current worker cannot provide.

   Related work. Link the implementation issue and rollout report when they exist. This example intentionally invents no issue links or benchmark results.

   Review a proposed record in five questions

   1. Could another person name the decision after reading its first paragraph?
   2. Are constraints separated from assumptions and preferences?
   3. Were alternatives compared on the same criteria?
   4. Are costs and new responsibilities as clear as benefits?
   5. Does an identifiable owner know what would trigger a review?

   Preserve the history

   Once accepted, keep the original reasoning understandable. Add dated clarifications for factual corrections. When a later decision replaces it, mark the earlier record superseded and link to its successor. Do not rewrite the earlier rationale to make the new choice look inevitable.

   A record explains the choice; it does not prove implementation or success. Keep implementation and validation evidence linked separately so that “accepted” cannot be mistaken for “shipped and working”.

   The template and reporting example are original adaptations. The linked Nygard article is the source for the underlying lightweight ADR approach.