Vibe Coding ADR 决策记录：保存约束、备选项与失效触发器

代码能显示系统现在怎么做，却很少保存当时为什么这样做。几个月后，编程 Agent 看见一个 adapter、两套存储或受限的包入口，可能把它判断为“多余复杂度”并主动简化；原作者则只记得模糊的兼容问题。没有决策证据，团队只能在每次重构时重新争论，或把偶然结构误当成永久原则。

Architecture Decision Record 的边界是记录一个具有架构影响的选择，不是生成漂亮的系统概览。ADR 社区与 Michael Nygard 的原始方法都强调上下文、决定和后果。Vibe Coding 可以帮助整理材料，但不能替代决策人，也不能把当前实现反推成一段从未发生过的历史。

只为真正的决策建立记录

适合 ADR 的事项会改变长期约束、跨模块依赖、数据所有权、部署形态、安全边界或退出成本，例如选择事件投递语义、确定租户隔离位置、采用某框架或规定模块公开入口。一次变量改名、普通缺陷修复和已由外部标准强制的细节通常不需要 ADR。记录过多会把重要选择淹没，记录过少则让关键限制只存在于聊天。

一个 ADR 只回答一个主要决策。标题使用“采用 X 以满足 Y”之类可辨识描述，不写“架构更新”。状态至少区分 proposed、accepted、rejected、deprecated 与 superseded，并包含稳定编号、日期和责任人。编号不因文件重命名重排，旧链接才能长期有效。

决策发生前先冻结 context：业务目标、硬约束、已知风险、截止条件、目标运行环境，以及明确未知。若依据某框架版本或托管能力，记录精确版本、文档链接和访问日期；官方文档版本锚定能避免 Agent 用今天的 API 为昨天的选择辩护。

让备选项在同一证据面上比较

ADR 至少保留维持现状和实际评估过的候选，不虚构三个陪衬选项制造客观感。每个候选按相同决策驱动因素说明：能否满足硬约束、需要哪些迁移、怎样失败、由谁维护、能否退出。未知保持 UNKNOWN，不能因为 Agent 找到一篇文章就自动变成支持证据。

证据链接到可复现样例、基准结果、威胁模型、兼容矩阵或用户约束，而不只链接供应商首页。例如框架选择可以沿用框架与模板垂直样例，记录候选精确版本与同题实验。分数表可以辅助讨论，却不能用任意权重掩盖某个 MUST 已失败。

Decision 段写清选择和适用范围；Consequences 同时写得到的能力、接受的代价、被推迟的问题及新增运营责任。“更易维护”不是后果，“所有跨模块调用必须从公开入口进入，因此需要新增边界 lint，动态插件暂列例外”才可被验证。垂直模块边界展示了这类决定如何落到依赖规则。

AI 起草必须保留来源与不确定性

给 Agent 的输入是冻结的 context、候选材料和仓库证据，输出只允许是草案。它可以发现遗漏的后果、把不同会议记录归并成问题、检查链接和术语一致性；不能补写没有证据的性能数字、用户偏好、合规结论或“团队一致同意”。每个事实标明来自仓库、实验、外部规范还是责任人判断。

草案审查时由真正承担后果的人确认：安全 owner 批准信任边界，数据 owner 批准迁移和保留，运维 owner 批准运行责任。批准记录身份、时间和对应摘要。聊天中的“看起来可以”不进入 accepted 状态；若关键 owner 缺席，ADR 保持 proposed。

还要防止 AI 用统一措辞抹掉分歧。没有采纳的候选保留拒绝理由和当时证据，但不把个人意见写成人身归因。敏感商业信息可以在受控附件，公开 ADR 保留可理解的约束类别与访问方式，不能删除关键理由后仍声称记录完整。

把决定连接到实现，但不伪装成自动证明

ADR 写入仓库后，关联具体代码入口、配置 schema、测试和检查命令。能机械验证的约束尽量自动化，例如禁止深层导入、要求加密配置、限制运行时版本；无法自动判断的后果进入评审清单。链接必须双向：ADR 指向实现，关键实现旁的简短注释或文档索引指回 ADR，而不是复制完整理由。

每次相关改动先问三件事：它是否违反 accepted 决策，它是否改变原 context，它是否触发复审条件。普通实现修正直接更新代码与证据；若选择本身改变，则新建 ADR 并将旧记录标为 superseded。不要重写旧文档让历史看起来一直正确，也不要删除 rejected 记录后重复做同一实验。

复审触发器要具体，例如支持的数据库版本退出维护、实测 p95 超过已批准预算、第二个独立消费者出现、法规要求改变，或退出演练失败。规格变化还应经过规格变更重新验收，因为 ADR 说明选择，不能单独证明用户行为仍被接受。

用反事实检查记录是否有用

验收 ADR 时，让未参与决定的人回答：若不读聊天，能否说出当时约束、为何没有选另一个候选、当前代码必须保持什么、出现何种新证据时应该重开决策？再做一次反事实评审：删除某项约束后结论是否可能改变；若永远不会，说明该约束只是装饰，或结论已经先于证据写定。

同时检查链接可访问、实验仍可定位、状态与 supersedes 链无环、实现检查指向当前命令。Agent 可以报告断链和代码漂移，但最终裁决仍由 owner 给出。批准后把 ADR 摘要纳入编程 Agent 改动验证门，防止后续大改只跑测试却绕过架构约束。

好的 ADR 不试图预测所有未来，而是诚实保存某一时刻的理由、代价和撤销条件。这样 Vibe Coding 生成的每次“简化”都会先面对已有决定，新的证据也能通过新记录推翻旧选择，知识演进而历史不被改写。