Vibe Coding 规格变更日志：范围冻结与重新验收闭环

Vibe Coding 的需求变化常发生在一句对话里：“这个列表顺便支持批量删除”“错误时自动重试就好”“字段改成可选，先让测试过”。Agent 会立即更新实现，甚至同步修改测试；几轮之后，最初规格、当前代码和评审者理解已经是三个版本。旧测试仍然绿色，却只证明一份没人能指出的移动目标。

规格变更日志的目的不是阻止变化，而是给变化稳定身份：谁提出、为什么、改变了什么承诺、哪些证据失效、谁重新接受。它连接可验证的问题陈述、MVP 垂直切片和最终Definition of Done 与交付边界，让“快速迭代”不等于“无基线迭代”。

冻结的是基线，不是讨论

实现开始前生成不可变 spec baseline，至少包含问题与目标用户版本、主路径、验收条件、non-goals、UI 状态矩阵、数据不变量、API 合同和非功能预算的摘要或引用。对内容规范化后计算摘要，分配如 [email protected] 的版本，并记录批准人和时间。

语义化版本可借鉴 SemVer 的 major/minor/patch 思路，但要在项目内重新定义：例如 patch 只澄清措辞且不改变可观察行为；minor 增加向后兼容的验收或可选能力；major 删除、弱化或不兼容地改变承诺。它不是声称产品规格天然等同公共 API。若团队只需递增 revision，也可以用整数，关键是旧版本永远可取且分类一致。

RFC 2119 的 MUST、SHOULD、MAY 能减少规范性强弱的歧义，但只有在文档声明按该 RFC 解释时才使用。每个 MUST 应对应验收证据；SHOULD 若未实现要记录理由；不要把整篇需求都大写成 MUST，导致真正不可妥协的边界消失。

范围冻结后仍可提出想法，只是不能直接进入当前实现。普通建议进入 backlog；阻断当前验收的缺陷按既有规格修复；需要改变规格的内容创建 change request。Agent 在 plan 或实现中发现缺口时也只能提交候选变更，不能自行批准。

一条变更记录应能独立评审

最小记录包括：

changeId: CR-027
fromSpec: [email protected]
proposedSpec: [email protected]
request: 删除项目时同时删除其全部分析结果
reason: 用户需要满足已确认的数据删除请求
changedClaims: [AC-14, INV-08, API-DELETE-01]
risks: [不可逆删除, 并发任务迟到写入, 审计保留冲突]
alternatives: [先进入30天待删除状态, 仅匿名化个人数据]
evidenceInvalidated: [E2E-09, MIGRATION-03, RUNBOOK-DELETE]
decision: PENDING

理由不能是“Agent 已经改好了”。记录必须给出用户、风险、法规、故障或技术证据，以及不改变范围的替代方案。若只是修正文案错字，说明可观察语义不变；若把 required 字段改为 optional，即使代码差异一行，也会改变数据不变量、API 消费者和 UI 空值状态，不能归为 patch。

影响分析从稳定 claim 出发。变更主路径时检查MVP 垂直切片和完成事件；变更状态时检查UI 状态矩阵；变更字段时检查数据模型与业务不变量和API 合同与请求响应示例；变更质量阈值时检查非功能预算。工具可给候选依赖，owner 对最终影响负责。

设定真正的范围冻结窗口

进入交付候选阶段后开启 freeze：只接受阻断级缺陷、安全事件、数据损坏或明确法规要求；其他变更排入下一版本。例外申请写影响、回滚和额外验收时间，由产品与工程责任人共同批准。冻结不是禁止合并任何代码，而是禁止未经重新基线的可观察行为变化。

代码保护规则可要求评审和状态检查，GitHub protected branches 提供其中的执行机制；但分支绿色不代表规格未漂移。CI 还需校验实现 PR 引用的 specVersion 与当前批准版本一致，变更文件若触及合同区域却没有 change ID，则阻断或要求人工解释。测试和规格同时被同一 PR 改弱时，提高评审级别。

重新验收不是机械全量重跑

批准变更后先产生新 baseline，再将旧证据标为 valid、stale 或 unaffected-with-reason。差量重验从受影响 claim 向外扩展：新行为的正例和反例、相关回归、迁移、权限、UI 状态和预算必须重跑；共享基础设施或无法可靠建立依赖时，扩大到全量。不能仅因某条旧测试仍通过，就认定它支持新语义。

以“同步删除分析结果”为例，至少重验：无权限删除被拒绝；重复请求幂等；后台任务不能在删除后重新写回；审计按政策保留但不泄露已删正文；删除中 UI 不显示成功空状态；备份恢复和保留政策一致。验收结果绑定新规格摘要和当前 commit，由批准变更以外的人或独立门禁复核高风险项。

若重新验收失败，状态回到 CHANGES_REQUIRED，不能把阈值调低来适配实现。若业务撤回变更，创建显式 REJECTED/REVERTED 记录并恢复上一批准基线；已经产生的数据要有修复方案，不能只回滚代码。发布后发现规格本身错误，同样追加新 change，而非覆盖历史。

让 Agent 在每轮结束时对账

每轮要求 Agent 报告：实际改动对应哪个 spec 和 claim；发现了哪些未决歧义；是否新增可观察行为；哪些证据因最后一次编辑而过期。然后比较 baseline 与工作树，不允许用聊天摘要替代正式记录。会话切换时，新 Agent 只接收当前批准 baseline 和开放 change，不从历史闲聊猜现状。

规格日志最终应简短到能回答四个问题：当前承诺是什么；它为何改变；哪些部分重新验证过；谁接受了剩余风险。实现速度越快，这条闭环越重要。它保留变化的自由，同时阻止生成速度把范围、证据和责任一起冲走。