recording-decisions

记录决策

必需背景： technical-writing 技能（硬性规则、真实性规则、风格）。

概述

按分量分为两种格式：对架构层面有影响的决策使用完整 ADR；持续记录较小选择的决策日志条目。两者都只追加：已接受的决策不可更改；新背景应作为一条新记录，用于取代旧记录。

何时调用，何时不调用

当有人已做出选择且需要记录时、有人要求“写下我们为什么这么做”时，或现有决策被取代时，调用本技能。对于仍在讨论的决策，不要调用本技能（此时应使用 writing-design-docs；其“Why & What”框在决策获接受后会成为 ADR）。

当出现未记录的决策正在流逝的信号时，也要调用本技能：“我们决定选 X 而不是 Y”、“就这么定吧”、在 PR 评论或聊天主题中解决的权衡，或某个理由已被解释过两次。每一种情况都表示有一项决策存在于非持久化位置；应主动提出记录下来。

引用决策之前，先记录该决策。聊天会话不是持久化来源。将带日期的实质内容写入日志，在措辞重要时引用决策者原话，提交该条目，然后再引用它。记录完整决策所需的最少内容，不要记录完整对话。

ADR

Nygard 格式。每份 ADR 只记录一项决策。

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

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

## 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]

必须记录负面影响，且内容不得为空。 每个备选方案都要包含其最有力的支持理由；没有说明理由就驳回某方案，是在树立稻草人论点。

已接受 ADR 唯一允许的编辑，是在其状态行添加“Superseded by ADR-XXX”。提出但始终未得到回应的异议，应作为负面影响完整记录，并指定负责人：撰写者不得自行编造反驳，也不得隐瞒负责人已宣布的决策。撰写时尚不清楚姓名的，应标记为提交前填写，因为已提交的记录涉及真实的人。

决策日志（轻量版）

持续记录的日志若采用完整 ADR，维护成本会过高。因此格式要足够简便：

## YYYY-MM-DD

### [Decision stated as an imperative sentence]
[One paragraph: the rule.]
Why:
- [reason]
- [reason]
Instead of: [rejected option] - [why not]

规则

• 只追加。错误条目应通过一条带日期的新记录来取代，绝不要编辑旧记录。将相对日期转换为绝对日期。
• 记录原因，而不只是结果。
• 当书面规则与已发布的实际情况不一致时，记录团队原本希望采用哪一种。每份规范文档都要说明其负责的内容，以及留给其他文档处理的内容。
• 如果可能与同类文档重叠，应在开头明确范围：“产品构想记录在 ROADMAP.md；本文件用于记录工程决策。”
• 明确记录负面结果和未知项：“四种理论均被证伪，尚未找到原因”就是一种结果。搜索无果也是一种结果。