recording-decisions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Recording decisions

记录决策

REQUIRED BACKGROUND: the

technical-writing

skill (hard rules, truth rules, style).

必备背景知识： the

technical-writing

skill（硬性规则、真实性规则、风格规范）。

Overview

概述

Two formats, by weight. A full ADR for a decision with architecture-level consequences; a decision log entry for the running stream of smaller choices. Both are append-only: an accepted decision is immutable, and new context is a new entry that supersedes the old one.

提供两种格式，按重要性区分。对于具有架构层面影响的决策，使用完整的ADR；对于日常的小型决策流，使用决策日志条目。两种格式均为追加式：已通过的决策不可修改，若有新情况需记录新条目并取代旧条目。

When to invoke, and not

适用与不适用场景

Invoke when a choice has been made and needs recording, when someone asks "write down why we did this", or when an existing decision is superseded. Do NOT invoke for a decision still being argued (that is

writing-design-docs

; the Why & What box becomes the ADR once accepted), and never edit an accepted ADR or an existing log entry: supersede it.

Also invoke on the phrases that signal an unrecorded decision passing by: "we decided X instead of Y", "let's just go with", a trade-off resolved in a PR comment or chat thread, or a rationale someone has now explained twice. Each of those is a decision living in a non-durable place; offer to record it.

Record the decision before citing it. A chat session is not a durable source: put the dated substance in the log, quote the decider where wording matters, and commit it first. Record the smallest complete decision, not a transcript.

当决策已确定需要记录、有人询问“写下我们这么做的原因”，或现有决策被取代时，可调用本技能。请勿在决策仍在讨论阶段时调用（此时应使用

writing-design-docs

技能；待决策通过后，其中的“原因与内容”模块可转为ADR），且绝不能编辑已通过的ADR或现有日志条目：如需更新，应添加新条目取代旧条目。

当出现以下表明未记录决策的表述时，也应调用本技能：“我们决定选X而非Y”、“就这么定了”、PR评论或聊天线程中解决的权衡问题，或有人已两次解释的决策依据。这些决策仅存在于非持久化渠道中，应主动提出记录它们。

引用决策前先记录。聊天会话并非持久化来源：将带日期的核心内容记录到日志中，若措辞重要则引用决策者的原话，先提交记录。记录最小的完整决策，而非对话转录。

ADR

Nygard format. One decision per ADR.

markdown

undefined

采用Nygard格式。每个ADR对应一项决策。

markdown

undefined

ADR-[number]: [short title of the decision]

ADR-[编号]: [决策简短标题]


Status	Proposed / Accepted / Superseded by ADR-XXX
Date	YYYY-MM-DD
Deciders	[who took part]


状态	提议中 / 已通过 / 被ADR-XXX取代
日期	YYYY-MM-DD
决策者	[参与决策的人员]

Context

背景

[The forces at play: technical, organizational, political. What must be solved. Factual, without giving away the decision.]

[当前面临的各种因素：技术、组织、政治层面。需要解决的问题。陈述事实，不提前透露决策结果。]

Decision

决策

[What was decided. Active voice: "We release on tags", not "it was decided that".]

[最终决定的内容。使用主动语态：“我们基于标签发布”，而非“决定将基于标签发布”。]

Consequences

影响

Positive: [what gets easier] Negative: [what gets harder, which trade we accept] Neutral: [what changes without being better or worse]

积极影响： [哪些事项变得更简单] 消极影响： [哪些事项变得更困难，我们接受的权衡] 中性影响： [哪些事项发生变化，但无好坏之分]

Alternatives considered

备选方案考量

[Alternative] - For: [...] Against: [...] Why not chosen: [...]

[备选方案名称] - 支持理由：[...] 反对理由：[...] 未被选择的原因：[...]

References

参考资料

[Evidence, related decisions, measurements]


**Negative is mandatory and may not be empty.** A decision without downsides is a decision that was not thought through. Each alternative carries its strongest argument for; a rejection without it is a strawman.

[相关证据、关联决策、衡量数据]


**消极影响为必填项，不可为空。** 没有弊端的决策说明未经过充分思考。每个备选方案都需列出其最有力的支持理由；若未列出就否定该方案，属于稻草人谬误。

Decision log (lightweight)

决策日志（轻量级）

For the running log a full ADR would kill. Cheap enough to actually maintain:

markdown

undefined

适用于日常决策流，完整ADR过于繁琐时使用。维护成本极低：

markdown

undefined

YYYY-MM-DD

[Decision stated as an imperative sentence]

[以祈使句表述的决策]

[One paragraph: the rule.] Why:

[reason]
[reason]


The decision-as-title reads in a table of contents. Recording the rejected option and the reason is what makes the entry worth revisiting.

[一段文字：规则内容。] 原因：

[理由1]
[理由2]


作为标题的决策内容在目录中清晰可读。记录被否决的选项及原因，是让日志具备参考价值的关键。

Rules

规则

Append-only. A wrong entry gets a new dated entry that supersedes it, never an edit. Convert relative dates to absolute.
Record the why, not only the what. Rationale is the part git history cannot reconstruct.
When a written rule and shipped reality have diverged, record which was intended; an unowned topic is how the wrong document gets cited as authority. Every doctrine document states what it owns and what it does not govern.
Scope guard at the top when a sibling could overlap: "product ideas live in ROADMAP.md; this file is for engineering decisions."
Capture negative results and unknowns explicitly: "four theories, four disproved, cause not found" is a result. A search returning nothing is a result.

仅可追加。错误的条目需添加新的带日期条目取代，绝不能编辑。将相对日期转换为绝对日期。
记录决策的原因，而非仅记录内容。决策依据是Git历史无法还原的部分。
当书面规则与实际执行情况不一致时，记录原本的意图；无人负责的主题会导致错误的文档被当作权威引用。每份准则文档需明确说明其管辖范围与非管辖范围。
当存在可能重叠的同类文档时，在顶部明确范围：“产品创意记录在ROADMAP.md中；本文件仅用于记录工程决策。”
明确记录负面结果与未知情况：“四种理论均被证伪，未找到原因”也是一种结果。搜索无结果同样是一种结果。