需要记录已做出的工程决策时，用 ADR 或决策日志固化原因…

当某项选择已经做出、需要写下为什么选/不选或已被取代时，用追加式 ADR 或轻量决策日志把它变成可追溯的持久记录。

适用场景

解决思路

1. 先遵循 technical-writing 技能（硬性规则、真实规则、风格），再开始写决策记录。
2. 按决策重量选择格式：有架构级后果的完整决策用 ADR；持续出现的小选择用决策日志条目。
3. 两种格式都追加式：已接受的决策不可变；新上下文写成一个新条目来取代旧条目。
4. 在以下情况调用：某个选择已经做出且需要记录；有人要求“写下我们为什么这样做”；已有决策被取代。
5. 不要用于仍在争论中的决策；那属于 writing-design-docs，等其 Why & What 框被接受后再转成 ADR。
6. 留意未记录决策正在溜走的信号：有人说“我们决定用 X 而不是 Y”或“就先这么定”；权衡在 PR 评论或聊天线程中被解决；同一理由已被某人解释第二次；出现这些信号时主动提出记录。
7. 引用某决策之前先记录它；聊天会话不是持久来源。
8. 把带日期的实质内容放进日志；措辞重要时引用决策者原话；提交条目后再引用它。
9. 记录最小完整决策，而不是聊天转录。
10. ADR 使用 Nygard 格式，且一个 ADR 只记录一个决策。
11. ADR 标题写成：`# ADR-[number]: [short title of the decision]`。
12. ADR 元数据表包含：Status（Proposed / Accepted / Superseded by ADR-XXX）、Date（YYYY-MM-DD）、Deciders（参与人）。
13. ADR 的 Context 写清技术、组织、政治等作用力，以及必须解决什么；保持事实性，不要提前泄露决策。
14. ADR 的 Decision 写清决定了什么；使用主动语态，如 “We release on tags”，不要写 “it was decided that”。
15. ADR 的 Consequences 分为 Positive（什么变容易）、Negative（什么变难、接受哪个权衡）、Neutral（什么变化但无关好坏）。
16. Negative 必填且不能为空。
17. ADR 的 Alternatives considered 中，每个替代方案写成 `**[Alternative]** - For: [...] Against: [...] Why not chosen: [...]`；每个替代方案都要带上其最强支持理由；没有最强理由的拒绝是稻草人。
18. 已接受 ADR 唯一允许的编辑是 Status 行加上 “Superseded by ADR-XXX”。
19. 被提出但从未回答的反对意见，要原样、全力度地写进负面后果，并指定负责人；写作者绝不自己编造反驳，也绝不隐瞒决策负责人已声明的决策。
20. 撰写时未知的人名标记为 fill-before-filing，因为归档记录承载真实人员。
21. 轻量决策日志用于完整 ADR 会拖死的持续记录；格式要便宜到能维护。
22. 决策日志格式：`## YYYY-MM-DD`，`### [用祈使句陈述决策]`，一段规则说明；`Why:` 下列出原因；`Instead of: [被拒绝的方案] - [为什么不用]`。
23. 决策记录一律追加式：错误条目不编辑，而是新增带日期的条目来取代它。
24. 把相对日期转换为绝对日期。
25. 记录 why，而不只是 what。
26. 当成文规则与已发布现实发生分歧时，记录团队原本意图是哪一方。
27. 每个 doctrine 文档要声明它负责什么、把什么留给其他文档。
28. 当兄弟文档可能重叠时，在顶部加范围守卫，例如 “product ideas live in ROADMAP.md; this file is for engineering decisions.”。
29. 明确记录负面结果和未知项：“four theories, four disproved, cause not found” 是一个结果；搜索无结果也是一个结果。

适用边界 · 注意事项

• 决策仍在争论、尚未被接受时不要用它作正式记录；那应走 writing-design-docs，等接受后其 Why & What 框再转为 ADR。
• 不要记录聊天转录，也不要把聊天会话当作可引用的持久来源；只记录最小完整决策。
• 没有已做出的选择、只是仍在探索选项时，不适用。