中文
devexamples
← Workflows

阅读中文版本

Architecture Decision Record Workflow

Record significant decisions with context, options, and consequences, review them, and supersede rather than delete when they change.

beginner~60 minarchitecturedocumentationprocess

Objective

Preserve the reasoning behind architecture decisions so future teams understand why.

Environment

  • A decision record location in the repository
  • A review process for decisions

Steps

1. Write the decision with context, options

Write the decision with context, options considered, and consequences.

Expected state: The reasoning is captured.

2. Review it with the people affected

Review it with the people affected before committing.

Expected state: Stakeholders had a voice.

3. Store it in the repository alongside

Store it in the repository alongside the code.

Expected state: It is versioned and discoverable.

4. Supersede rather than delete

Supersede rather than delete when the decision changes.

Expected state: The history of reasoning is preserved.

Decision points

Record every decision or significant ones?

  • Significant and hard to reverse
  • Every decision

Significant and hard-to-reverse decisions; recording everything dilutes the signal.

Delete or supersede an outdated record?

  • Supersede
  • Delete

Supersede; deleting erases why the original choice was made and invites repeating mistakes.

Expected outcome

Versioned decision records that explain context, options, and consequences, with superseded records preserved.

Verification

Confirm each significant recent decision has a record and that changed decisions link to their successor.

Cleanup

Index the records and link related decisions.

Overview

Preserve the reasoning behind architecture decisions so future teams understand why. Confirm each significant recent decision has a record and that changed decisions link to their successor.

Steps

  1. Write the decision with context, options considered, and consequences. Expected state: The reasoning is captured.
  2. Review it with the people affected before committing. Expected state: Stakeholders had a voice.
  3. Store it in the repository alongside the code. Expected state: It is versioned and discoverable.
  4. Supersede rather than delete when the decision changes. Expected state: The history of reasoning is preserved.
# ADR 0042: Use cursor pagination for list endpoints

## Context
Offset pagination degrades on deep pages.

## Decision
Adopt cursor pagination across list APIs.

## Consequences
Clients must handle cursors; no arbitrary page jumps.

Verification

  • Versioned decision records that explain context, options, and consequences, with superseded records preserved.

Decision points

  • Record every decision or significant ones? Options: Significant and hard to reverse; Every decision. Recommended: Significant and hard-to-reverse decisions; recording everything dilutes the signal.
  • Delete or supersede an outdated record? Options: Supersede; Delete. Recommended: Supersede; deleting erases why the original choice was made and invites repeating mistakes.