Back to Details

document-decision

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Document a decision — write an ADR

记录决策——编写ADR

Create an ADR so future readers (including future you) understand why a technical choice was made. An ADR is immutable once accepted — it records the decision and its context at the moment of decision. New information gets a new ADR that references (and possibly supersedes) the old one.
This skill produces canonical MADR v4 (Markdown Architectural Decision Records, version 4.0.0, released 2024-09-17 — the current standard). Spec: https://adr.github.io/madr/ — template source: https://github.com/adr/madr/blob/develop/template/adr-template.md.
创建ADR是为了让未来的读者（包括未来的你）理解做出某项技术选择的原因。ADR一旦被接受便不可更改——它记录了决策做出时的内容和背景。新信息需要创建新的ADR，并引用（可能取代）旧的ADR。
此技能生成标准MADR v4（Markdown架构决策记录，4.0.0版本，发布于2024-09-17——当前标准）。规范地址：https://adr.github.io/madr/ —— 模板来源：https://github.com/adr/madr/blob/develop/template/adr-template.md。

Before You Start

开始之前

  • The project's existing ADR directory — common locations: 
    docs/adr/
    , 
    docs/decisions/
    , 
    docs/arc42/decisions/
    , 
    architecture/decisions/
    , or 
    adr/
    . Find it with 
    find . -type d -name 'adr*' -o -name 'decisions'
    .
  • Any template file in that directory — often 
    template.md
    or 
    0000-template.md
    . If a project template exists, follow it instead of the canonical MADR template — projects sometimes pin a specific subset of optional sections.
  • Existing ADRs — browse 2–3 well-written ones to match the project's voice and depth.
If the project has no ADR directory yet, ask the user where ADRs should live before creating the first one.
  • 项目现有ADR目录——常见位置：
    docs/adr/
    、
    docs/decisions/
    、
    docs/arc42/decisions/
    、
    architecture/decisions/
    或
    adr/
    。可通过命令
    find . -type d -name 'adr*' -o -name 'decisions'
    查找。
  • 该目录下的任何模板文件——通常为
    template.md
    或
    0000-template.md
    。如果项目已有模板，请遵循项目模板而非标准MADR模板——项目有时会固定使用特定的可选章节子集。
  • 现有ADR——浏览2-3篇撰写良好的ADR，匹配项目的语气和深度。
如果项目还没有ADR目录，请先询问用户ADR应存放在何处，再创建第一篇ADR。

Step 1: analyze the change

步骤1：分析变更

bash
git diff main...HEAD
git diff --stat main...HEAD
Identify:
  • What was chosen?
  • What were the alternatives considered?
  • What forces (constraints, quality attributes, risks) pulled toward each alternative?
  • What will change now, and what could change later as a result?
  • How will compliance be confirmed? (MADR v4 elevated this — see 
    ### Confirmation
    in Step 4.)
If you're writing the ADR before the code change, do the same analysis against the planned approach.
bash
git diff main...HEAD
git diff --stat main...HEAD
确定：
  • 选择了什么？
  • 考虑过哪些替代方案？
  • 哪些因素（约束、质量属性、风险）倾向于每个替代方案？
  • 现在会发生什么变化，以及未来可能因此发生什么变化？
  • 如何确认合规性？（MADR v4对此进行了强调——见步骤4中的
    ### Confirmation
    。）
如果在代码变更前编写ADR，请针对计划的方法进行同样的分析。

Step 2: check for existing ADRs on the topic

步骤2：检查是否存在相关主题的现有ADR

bash
undefined
bash
undefined

Find ADRs covering adjacent ground

查找涵盖相关领域的ADR

grep -rli "{topic-keyword}" <adr-dir>/ 2>/dev/null

If one exists:

- **Covers the same ground** — update it rather than creating a duplicate.
- **Covers related but different ground** — reference it in the new ADR's **Context and Problem Statement**.
- **Contradicts this decision** — mark the old one's frontmatter as `status: "superseded by ADR-NNNN"` and reference it in your new **Context and Problem Statement**.
grep -rli "{topic-keyword}" <adr-dir>/ 2>/dev/null

如果存在：

- **涵盖相同内容**——更新该ADR，而非创建重复内容。
- **涵盖相关但不同的内容**——在新ADR的**背景与问题陈述**中引用它。
- **与本次决策矛盾**——将旧ADR的前置元数据标记为`status: "superseded by ADR-NNNN"`，并在新ADR的**背景与问题陈述**中引用它。

Step 3: name the file

步骤3：命名文件

Two common conventions:
  • Numbered: 
    NNNN-short-slug.md
    (e.g., 
    0042-adopt-postgres-rls.md
    ). Number is monotonic; pad to 4 digits. This is MADR's default.
  • Dated: 
    YYYY_MM_DD_short_slug.md
    (e.g., 
    2026_04_20_adopt_postgres_rls.md
    ).
Follow whatever the project already uses. Look at the filenames of existing ADRs to copy the pattern.
两种常见约定：
  • 编号式： 
    NNNN-short-slug.md
    （例如：
    0042-adopt-postgres-rls.md
    ）。编号为递增序列；补零至4位。这是MADR的默认约定。
  • 日期式： 
    YYYY_MM_DD_short_slug.md
    （例如：
    2026_04_20_adopt_postgres_rls.md
    ）。
遵循项目已有的命名方式。查看现有ADR的文件名以复制其格式。

Step 4: write the ADR (canonical MADR v4)

步骤4：编写ADR（标准MADR v4）

Use the template below verbatim. Drop optional sections (marked with the HTML comment 
<!-- This is an optional element. Feel free to remove. -->
) only when they genuinely add no value — 
### Confirmation
in particular should almost always be kept (the MADR spec itself notes "although we classify this element as optional, it is included in many ADRs").
markdown
---
status: "{proposed | rejected | accepted | deprecated | superseded by ADR-0123}"
date: {YYYY-MM-DD}
decision-makers: {list everyone involved in the decision}
consulted: {subject-matter experts with two-way communication}
informed: {kept up-to-date with one-way communication}
---
严格使用以下模板。仅当确实没有价值时才删除可选章节（标记为HTML注释
<!-- This is an optional element. Feel free to remove. -->
）——尤其应保留
### Confirmation
（MADR规范本身指出“尽管我们将此元素归类为可选，但许多ADR中都包含它”）。
markdown
---
status: "{proposed | rejected | accepted | deprecated | superseded by ADR-0123}"
date: {YYYY-MM-DD}
decision-makers: {列出所有参与决策的人员}
consulted: {进行双向沟通的主题专家}
informed: {通过单向沟通保持知情的人员}
---

{short title, representative of solved problem and found solution}

{简短标题，能代表所解决的问题和找到的解决方案}

Context and Problem Statement

背景与问题陈述

{Describe the context and problem in two to three sentences, or as an illustrative story. You may articulate the problem as a question. Make the scope explicit by naming the structural architecture elements affected (components, connectors, modules). Link to issues, collaboration boards, prior ADRs.}
<!-- This is an optional element. Feel free to remove. -->
{用两到三句话或一个说明性故事描述背景和问题。你可以将问题表述为一个问句。通过指明受影响的结构架构元素（组件、连接器、模块）明确范围。链接到问题、协作看板、先前的ADR。}
<!-- This is an optional element. Feel free to remove. -->

Decision Drivers

决策驱动因素

  • {decision driver 1 — a desired quality, faced concern, constraint, or force}
  • {decision driver 2}
  • …
  • {决策驱动因素1——期望的质量、面临的问题、约束或因素}
  • {决策驱动因素2}
  • …

Considered Options

考虑的方案

  • {title of option 1}
  • {title of option 2}
  • {title of option 3}
  • …
  • {方案1标题}
  • {方案2标题}
  • {方案3标题}
  • …

Decision Outcome

决策结果

Chosen option: "{title of option 1}", because {justification — e.g., only option that meets a k.o. criterion, resolves a specific force, comes out best in the pros/cons analysis below}.
<!-- This is an optional element. Feel free to remove. -->
选择的方案："{方案1标题}"，因为{理由——例如，唯一满足淘汰标准的方案，解决了特定因素，在下面的优缺点分析中表现最佳}。
<!-- This is an optional element. Feel free to remove. -->

Consequences

影响

  • Good, because {positive consequence — improvement of one or more desired qualities}
  • Bad, because {negative consequence — compromising one or more desired qualities}
  • …
<!-- Strongly recommended even though MADR marks it optional. -->
  • 有利，因为{积极影响——提升一个或多个期望的质量}
  • 不利，因为{消极影响——损害一个或多个期望的质量}
  • …
<!-- 尽管MADR标记为可选，但强烈建议保留。 -->

Confirmation

Confirmation（合规确认）

{How will compliance with this ADR be confirmed? Is there an automated or manual fitness function? E.g., a code review, a test with ArchUnit, a CI check, a periodic audit. Name the mechanism and where it lives.}
<!-- This is an optional element. Feel free to remove. -->
{如何确认符合此ADR？是否有自动化或手动验证机制？例如，代码审查、使用ArchUnit的测试、CI检查、定期审计。指明机制及其所在位置。}
<!-- This is an optional element. Feel free to remove. -->

Pros and Cons of the Options

各方案的优缺点

{title of option 1}

{方案1标题}

{example | description | pointer to more information}
  • Good, because {argument a}
  • Good, because {argument b}
  • Neutral, because {argument c}
  • Bad, because {argument d}
{示例 | 描述 | 指向更多信息的链接}
  • 有利，因为{论点a}
  • 有利，因为{论点b}
  • 中性，因为{论点c}
  • 不利，因为{论点d}

{title of option 2}

{方案2标题}

  • Good, because {argument a}
  • Neutral, because {argument b}
  • Bad, because {argument c}
<!-- This is an optional element. Feel free to remove. -->
  • 有利，因为{论点a}
  • 中性，因为{论点b}
  • 不利，因为{论点c}
<!-- This is an optional element. Feel free to remove. -->

More Information

更多信息

{Additional evidence/confidence for the outcome; team agreement; when/how the decision should be realised; if/when it should be revisited; links to related decisions and resources.}
undefined
{决策结果的额外证据/信心；团队共识；决策应何时/如何实施；何时/应否重新审视；指向相关决策和资源的链接。}
undefined

Writing discipline

写作规范

  • Heading names are exact. 
    Context and Problem Statement
    , 
    Decision Drivers
    , 
    Considered Options
    , 
    Decision Outcome
    , 
    Consequences
    , 
    Confirmation
    , 
    Pros and Cons of the Options
    , 
    More Information
    . MADR-aware tooling parses on these names.
  • Heading levels are exact. 
    Consequences
    and 
    Confirmation
    are 
    ###
    under 
    ## Decision Outcome
    , not top-level.
  • Frontmatter field names are exact. 
    decision-makers
    (hyphenated, plural), not 
    deciders
    . 
    status
    value is a quoted string when it contains spaces (e.g., 
    status: "superseded by ADR-0123"
    ).
  • Bullet voice is "Good, because …" / "Bad, because …" / "Neutral, because …". Not "Pros:" / "Cons:".
  • Context is specific. "We need to scale" → "Request latency at the 95th percentile has exceeded 500ms as traffic doubled; adding more replicas of the current stack costs $X/month."
  • Drivers are verifiable. "Ease of use" is not a driver — "junior engineers onboard in under a week" is.
  • Decision names the trade-off. If there's no trade-off, the decision isn't worth an ADR.
  • Confirmation is concrete. Name the test file, the CI job, the review gate. "We will review this" is not confirmation.
  • 标题名称必须准确。
    Context and Problem Statement
    （背景与问题陈述）、
    Decision Drivers
    （决策驱动因素）、
    Considered Options
    （考虑的方案）、
    Decision Outcome
    （决策结果）、
    Consequences
    （影响）、
    Confirmation
    （合规确认）、
    Pros and Cons of the Options
    （各方案的优缺点）、
    More Information
    （更多信息）。识别MADR的工具会根据这些名称进行解析。
  • 标题层级必须准确。
    Consequences
    （影响）和
    Confirmation
    （合规确认）是
    ## Decision Outcome
    （决策结果）下的
    ###
    子标题，而非顶级标题。
  • 前置元数据字段名称必须准确。
    decision-makers
    （连字符连接，复数形式），而非
    deciders
    。当
    status
    值包含空格时，需用引号括起（例如：
    status: "superseded by ADR-0123"
    ）。
  • 项目符号语气为“有利，因为……”/“不利，因为……”/“中性，因为……”。不能是“优点：”/“缺点：”。
  • 背景需具体。“我们需要扩展” → “随着流量翻倍，95分位请求延迟已超过500ms；为当前栈添加更多副本每月需花费X美元。”
  • 驱动因素可验证。“易用性”不是驱动因素——“初级工程师可在一周内完成入职”才是。
  • 决策需说明权衡。如果没有权衡，该决策不值得记录为ADR。
  • 合规确认需具体。指明测试文件、CI任务、审查关卡。“我们将对此进行审查”不属于合规确认。

Step 5: update the ADR index

步骤5：更新ADR索引

Most ADR directories have an 
index.md
or 
README.md
listing every ADR. Add an entry:
markdown
| {Number/Date} | [{Title}]({filename}) | {Status} |
大多数ADR目录都有
index.md
或
README.md
列出所有ADR。添加一条记录：
markdown
| {编号/日期} | [{标题}]({文件名}) | {状态} |

Verify

验证

bash
undefined
bash
undefined

The file exists where expected

文件存在于预期位置

ls <adr-dir>/{NNNN-slug.md OR YYYY_MM_DD_slug.md}
ls <adr-dir>/{NNNN-slug.md 或 YYYY_MM_DD_slug.md}

Required MADR v4 sections are present (Context, Considered Options, Decision Outcome)

包含MADR v4必填章节（背景、考虑的方案、决策结果）

grep -E '^## (Context and Problem Statement|Considered Options|Decision Outcome)$' <adr-dir>/<filename> | wc -l
grep -E '^## (Context and Problem Statement|Considered Options|Decision Outcome)$' <adr-dir>/<filename> | wc -l

Expected: 3

预期结果：3

Confirmation sub-section is present (strongly recommended)

包含Confirmation子章节（强烈建议）

grep -q '^### Confirmation$' <adr-dir>/<filename> && echo "OK" || echo "MISSING — add unless intentionally omitted"
grep -q '^### Confirmation$' <adr-dir>/<filename> && echo "OK" || echo "缺失——除非有意省略否则请添加"

Frontmatter uses canonical field names

前置元数据使用标准字段名称

head -10 <adr-dir>/<filename> | grep -E '^(status|date|decision-makers|consulted|informed):'
head -10 <adr-dir>/<filename> | grep -E '^(status|date|decision-makers|consulted|informed):'

The index references it

索引中引用了该ADR

grep -q "{slug}" <adr-dir>/README.md <adr-dir>/index.md 2>/dev/null
undefined
grep -q "{slug}" <adr-dir>/README.md <adr-dir>/index.md 2>/dev/null
undefined

Common Mistakes

常见错误

MistakeCorrection
Using 
Context
instead of 
Context and Problem Statement
Heading name is exact in MADR v4.
Using 
Decision
instead of 
Decision Outcome
Same.
Promoting 
Consequences
and 
Confirmation
to 
##
level		They are 
###
sub-elements of 
## Decision Outcome
.
Frontmatter field 
deciders
Renamed to 
decision-makers
in MADR v4.
Listing pros/cons as 
Pros:
/ 
Cons:
Use 
* Good, because …
/ 
* Bad, because …
/ 
* Neutral, because …
bullets.
Omitting 
### Confirmation
MADR v4 elevated this; almost every meaningful ADR has a confirmation mechanism. State it.
Writing an ADR for a decision with no real trade-offSkip it. ADRs document choices with alternatives.
Context and Problem Statement
that restates the decision		Context is the situation. If context and decision sound the same, the context isn't concrete enough.
Consequences listed only as 
Good, because …
Every decision has trade-offs. If you can't name a 
Bad, because …
, you haven't thought hard enough.
Duplicating an existing ADR because you didn't searchStep 2 is mandatory. Duplicate ADRs fragment institutional memory.
错误修正方法
使用
Context
而非
Context and Problem Statement
MADR v4中的标题名称必须准确。
使用
Decision
而非
Decision Outcome
同上。
将
Consequences
和
Confirmation
提升为
##
层级		它们是
## Decision Outcome
下的
###
子元素。
前置元数据字段使用
deciders
MADR v4中已重命名为
decision-makers
。
用
Pros:
/ 
Cons:
列出优缺点		使用
* 有利，因为……
/ 
* 不利，因为……
/ 
* 中性，因为……
项目符号。
省略
### Confirmation
MADR v4对此进行了强调；几乎所有有意义的ADR都有合规确认机制。请明确说明。
为没有实际权衡的决策编写ADR跳过此类决策。ADR用于记录有替代方案的选择。
Context and Problem Statement
重复决策内容		背景是所处的情境。如果背景和决策听起来相同，说明背景不够具体。
仅列出
有利，因为……
的影响		每个决策都有权衡。如果无法列出
不利，因为……
，说明思考不够深入。
未搜索就创建重复的ADR步骤2是必填项。重复的ADR会分散组织记忆。