speckit 实践：用 Patch 机制管理 Spec 变更（2）—— 约束与收敛

用 Patch 机制管理 Spec 变更（2）—— 约束与收敛

目录

• 用 Patch 机制管理 Spec 变更（2）—— 约束与收敛
  • 0. 背景：个人改造流程的演进
  • 1. 核心问题：spec 会逐步退化为变更日志
  • 2. 核心收敛原则
  • 3. 三步收敛流程
    • 3.1 拆分每条 Patch 的内容
    • 3.2 正向合并（spec.md）
    • 3.3 下沉实现 + 溯源归档
  • 4. 可复用的判断标准
  • 5. 真实案例：处理结果对照
  • 6. 小结

0. 背景：个人改造流程的演进

在上一篇《用 Patch 机制管理 Spec 变更》里，我把线性流程

spec → plan → 实施 → review

演化成带 Patch 回路的闭环：

spec → plan → 实施 → review ↻ (patch → review) → skill

核心约定是「已确认的 spec 不直接改，新增 / 遗漏 / review 问题以 Patch 追加」，并配套了「先上车后补票」的弹性——小改动代码先行，回头只在 spec 补录 WHAT（详见上一篇第 5 节）。

这套机制跑了一段时间后，新问题浮现：Patch 只进不出，spec 越来越长。每条 Patch 都带着组件名、宽度、函数签名这些实现细节，spec 慢慢从「需求契约」退化成了「变更日志」。这篇记录的就是为了应对这种膨胀而补上的收敛约束。

---

1. 核心问题：spec 会逐步退化为变更日志

「先上车后补票」解决的是「快速落代码、不丢 traceability」，但它有个副作用：

• Patch 段不断追加，从不收敛；
• 行为约束（WHAT）和实现细节（HOW）混在同一条 Patch 里；
• 后来者读 spec，看到的不是「系统该做什么」，而是一长串「这里改过什么」。

如果不主动整理，spec 会逐步退化为变更日志——可追溯性还在，但作为需求契约的可读性丢失了。

---

2. 核心收敛原则

一句话定调：

spec 讲 WHAT/WHY（业务行为），plan 讲 HOW（代码实现），Patch 段只做溯源索引。

衍生约束：

• 先代码后回填可以用作临时记录，但必须周期性把行为约束正向合并进 FR，把实现细节下沉到 plan.md。
• 整理时别直接删 Patch，保留一行引用（如 → 已合并至 FR-028），方便追溯需求来源。

---

3. 三步收敛流程

3.1 拆分每条 Patch 的内容

先做内容分流，区分两类：

• 行为约束：用户能感知的交互规则（如「三级联动筛选、单向写入三个查询字段、保留旧筛选器」）。
• 实现细节：组件名、宽度、类名、API 签名、样式值（如 el-cascader、!w-595px、getCascadeOptions()）。

分流标准见第 4 节。

3.2 正向合并（spec.md）

把行为约束「升级」进 spec 的正式结构：

• 行为约束 → 新的 FR-xxx（面向业务、可测试、不含技术细节）；
• 验收结果 → 新的 SC-xxx（可量化、技术无关）。

例如 PC-009 稳定后，把 !w-595px、el-cascader、getCascadeOptions() 这些留在 plan，只把「三级级联、单向写入三个查询字段、保留旧筛选器」抽象进一条新 FR（如 FR-031）。

3.3 下沉实现 + 溯源归档

• 实现细节 → 追加到 plan.md 对应 Patch 段（带 [DONE] 标记 + → FR-xxx 反向引用）；
• Patch 段 → 压缩为一张溯源索引表，列：Patch | 标题 | 合并去向(FR/SC) | 实现细节(plan 链接)。

整理后原 Patch 段可标注为「已合并」或归档，但不直接删——保留索引行即可。

---

4. 可复用的判断标准

分流时按这三个口径判断一条内容该进哪：

去向	判断标准	例子
进 FR	用户 / 业务能感知的行为规则、交互语义、范围边界	「管理视图 MUST 支持工序 / 类别 / 名称三级联动筛选，单向写入查询条件」
进 plan	框架组件名、CSS 类名、宽度值、函数签名、mock 抛错方式	el-cascader、!w-595px、getCascadeOptions()
进 SC	可量化、技术无关的验收指标（时间、百分比、可观察结果）	「筛选结果在交互后即时刷新」

---

5. 真实案例：处理结果对照

下面是 spec.md 的 ## Patch 段经过一轮收敛后的实际处理结果（以 PC-006 ~ PC-009 一组为例）：

位置	处理前	处理后
spec Patch 段	9 条详细描述（含实现细节）~114 行	1 张索引表（溯源用）
spec FR / SC	到 FR-027 / SC-011	新增 FR-028031、SC-012014
plan.md	到步骤 37	新增步骤 3846（PC-006009 实现）

收敛后 spec 的 Patch 段从 ~114 行压成一张索引表，行为约束全部进了 FR / SC，实现细节全部下沉到 plan——既保住了 traceability，又让 spec 重新回到「需求契约」的定位。

---

6. 小结

收敛约束是对上一篇 Patch 机制的补全：

• 上一篇解决「怎么加」——Patch 回路让变更可追溯；
• 本篇解决「怎么收」——周期性正向合并 + 下沉，防止 spec 退化。

两条原则合在一起才是完整的闭环：

顺序可以灵活（先上车后补票），但 traceability（可追溯性）不能丢；可追溯的同时，spec 必须始终反映「系统该做什么」而不是「曾经改过什么」。

落地动作：每个 Session 结束前，把当天的 Patch 过一遍，决定哪些转 FR、哪些只留在 plan——这样 spec 不会无限增长。