adr-backfill

adr-backfill

追溯记录过去已作出但从未记录的架构决策。候选项通常来自 /doc-audit 的 BACKFILL-ADR 行，或来自意识到过去某项变更本应记录为 ADR 的用户。与 adr-drafting 相比，本技能采用较宽松的门槛（决策者可能无法查明，备选方案也可能无法重建），但对诚实性的要求更严格：补录 ADR 必须明确标记为补录，避免未来读者误以为它是在决策同期撰写的记录。

何时使用此技能

• /doc-audit 发现了 BACKFILL-ADR 候选行，且用户想将其记录下来。
• 用户以过去时描述一项决策——“我们几年前就决定了，”、“当时，”、“在我加入之前，”、“我们从未把它写下来”——并且这项变更的影响如今仍能在代码库中看到。
• 代码考古过程中发现了一次迁移、供应商移除或子系统退役，却没有相应的决策记录。

何时不应使用此技能

• 决策正在进行中或尚未完成——改用 adr-drafting。
• 决策已通过任何形式记录——使用 adr-critique 完善现有记录。
• reconstruction-confidence 为 low（只能还原做了什么，无法还原为什么）——拒绝起草，并转至 open-questions.md。
• 变更不具备架构重要性——参见 _shared/adr-is-backfillable.md § 2。通过 doc-diagnostic 中的备选方案目录进行处理。

输入

• 必需： 至少两个独立的证据定位信息（参见 _shared/adr-is-backfillable.md § 3）。例如：提交 SHA + 迁移文件、迁移文件 + 已移除的清单条目、已移除的模块 + 退役功能标记提交。
• 必需： 受影响架构特性的可衡量信号（参见 _shared/adr-is-backfillable.md § 4）。
• 可选： 来自 /doc-audit 的 BACKFILL-ADR 行，其中包含拟定的 decision、evidence-locator、ASR-test-result、reconstruction-confidence 和 suggested-status 字段。若提供，则以此作为起始简报。

拒绝行为

在以下情况下，本技能拒绝起草：

• _shared/adr-is-backfillable.md 中的资格自检第 1 至 3 项或第 5 项未通过（没有证据、没有 ASR 重要性、证据仅来自单一定位信息，或已存在记录）。
• reconstruction-confidence 为 low——这会迫使我们编造为什么。转至 open-questions.md。
• 无法为受影响的架构特性指出可衡量的信号。
• 用户希望补录 ADR 看起来像是在决策同期撰写的记录（不包含诚实性声明）。该声明不可协商。

核心操作规则

每条消息中至多提出一个问题或给出一个步骤。 继承 adr-drafting 的每轮一个问题原则。补录至少与前瞻性起草一样容易塞入过多内容；因此应加强纪律，而非放宽。

四个阶段

阶段 1 — 资格与证据

依据 _shared/adr-is-backfillable.md 对候选项逐项执行七项资格自检。一次检查一项。若任何一项未通过，则停止：

• 第 1 至 3 项或第 5 项未通过 → 拒绝起草，并说明缺少哪些证据。
• 第 4 项未通过（没有可衡量的信号）→ 转至 open-questions.md。
• 第 6 项未通过（置信度为 low）→ 连同能提升置信度的证据一起转至 open-questions.md。
• 第 7 项未通过（无法指出决策者，且尚未标记为 unrecoverable）→ 只询问一次：是使用 unrecoverable 标记，还是继续查找。

在对话中确认两个定位信息所指的证据——将定位信息复述给用户，以便用户纠正错误的材料。在用户确认这些证据无误之前，不要进入阶段 2。

第 2 阶段 — 重建历史背景（尽力而为）

针对 ADR 的每个部分，尽可能重建信息，并明确标出缺失之处，而不是掩盖问题。

部分	重建方法
背景（各项推动因素）	阅读提交消息、PR 描述、工单链接、已删除的 README 内容和已废弃的运行手册。引用每个来源。如果无法根据现有证据重建各项推动因素，请写明 "无法根据现有证据重建决策当时的推动因素。" — 不要编造。
决策	具体内容 — 几乎总能从已发布的变更中重建。使用现在时主动语态表述，与前瞻性 ADR 相同。
备选方案	通常是最难恢复的部分。如果 PR 审查评论、提交历史或同期 RFC 中能看到原始备选方案，请引用。如果没有，诚实声明将涵盖这一缺口。
后果（好处 / 坏处）	根据当前代码库中可观察到的影响进行重建。"删除了 14k LOC" 是可观察到的；"提升了开发者士气" 则不是。
决策者	根据提交作者、PR 审阅者或明确署名填写具体人员姓名，或者使用字面标记 unrecoverable。绝不编造。

第 3 阶段 — 使用诚实声明起草（强制）

每个补录 ADR 都必须在正文靠前位置包含一段逐字不变的诚实声明（标题之后、背景之前）。声明的固定文本、必需字段、结尾标点和拒绝条件见 references/honesty-clause.md — 起草前请阅读。

这段声明能确保未来读者不会把补录内容误认为同时期记录。删除或弱化该声明属于批评标记（参见 adr-critique 审核清单）。

第 4 阶段 — 保存

保存规则与 adr-drafting 相同：

1. 优先使用 ADR Explorer 兼容的目录进行 Glob 查找（docs/adr/、docs/decisions/、docs/architecture/decisions/、**/adr/*.md）；也要检查旧目录 architecture/decisions/，但需提醒该目录可能需要自定义 ADR Explorer 根目录配置。使用第一个已存在的目录；如果都不存在，则创建 docs/adr/。
2. 自动编号：读取现有 ADR，取 max+1，并在前面补零至 4 位。**补录 ADR 使用下一个可用编号，而不是过去的编号。**编号反映创建顺序，而非决策顺序。原始决策日期写在文件内（见 frontmatter）；编号表示当前创建时间。
3. 文件名：NNNN-kebab-imperative-title.md。
4. 使用诚实声明和补录专用 frontmatter（见下方模板）编写文件。
5. 更新决策日志 README.md 索引，并在对应行标注 (backfilled YYYY-MM-DD)。

补录专用 frontmatter

---
title: "<imperative verb phrase>"
status: accepted                   # or deprecated if reversed; keep status ADR Explorer-compatible
date: <original decision date if known, else first-evidence date in ISO 8601>
backfilled-on: YYYY-MM-DD          # today
deciders:
  - <named human, or unrecoverable>
evidence:                          # at least two locators
  - <commit SHA / file path / manifest line>
  - <commit SHA / file path / manifest line>
reconstruction-confidence: high | medium
asr-characteristic: <latency | cost | availability | security | maintainability | operability | portability | ...>
asr-signal: "<measurable signal -- e.g., removed 14k LOC and one vendor dependency>"
tags: [backfill]
---

如果后续已发布的变更撤销了该决策，请将 status: deprecated，并在 evidence: 中引用撤销该决策的提交 / 迁移记录，同时在诚实声明或备注中说明。仍应记录该补录 ADR — 即使决策已被撤销，其历史仍然重要 — 但状态必须与 ADR Explorer 兼容。

状态约定

状态	使用条件…
accepted	该决策目前仍然有效。默认状态。
deprecated	后续已发布的变更撤销了原决策。请引用撤销该决策的证据。

补录 ADR 绝不使用 proposed 或 rfc — 补录按定义就是记录已经发布的决策。通过 tags: [backfill]、backfilled-on、证据字段和强制诚实声明来标明补录性质；不要在 status 中标明。

拒绝：用户想删除诚实条款时

诚实条款是补录 ADR 中唯一不可妥协的部分。如果用户要求删除它、弱化它，或把它藏进脚注，请拒绝。说明缺少该条款的补录记录看起来就像一份当时写下的记录，会悄无声息地污染决策日志——未来的读者无从判断其中的理由是事后重构出来的，而非当时记录的。该条款必须保留在正文中。

adr-critique 会独立执行此要求：对于带有 tags: [backfill] 或 backfilled-on、但正文缺少诚实条款的记录，审计检查清单会将其标记出来。

移交

adr-backfill 不会自动衔接其他技能。补录记录保存后，用户可以选择：

• 针对新记录运行 adr-critique，以完善措辞（尤其是在 reconstruction-confidence 为 medium 时）。
• 运行 c4-model，添加反映决策后系统形态的 Context / Container 视图（可选）。
• 更新 open-questions.md，关闭补录记录解决的任何已锁定问题。

这些都不是强制步骤。仅通过技能触发进行柔性移交。

参考资料

• references/honesty-clause.md — Phase 3 诚实条款的规范定义（形式、必填字段、句末标点、拒绝条件）。唯一事实来源；adr-critique 也会读取同一文件。
• ../_shared/adr-is-backfillable.md — 七项资格自检清单（用于 Phase 1）
• ../_shared/adr-is-not.md — 与前置 ADR 一样适用于补录 ADR（不是教程、不是实施指南、不是营销材料、不得含糊其辞、不得冗长填充）
• ../doc-diagnostic/references/audit-procedure.md — 定义为此技能提供依据的 BACKFILL-ADR 行模式
• adr-drafting 技能 — 针对当时决策的前置撰写对应技能
• adr-critique 技能 — 用于之后完善已保存的补录记录
• doc-diagnostic 技能 — 用于 ASR 定义和替代方案目录