12 第三篇 · 日常：每个变更任务

各档的流程走法

任务分档决定流程要多重，这一章给出每档的实际走法。需求已经按第 10 章分解成一个个 feature；这一章针对单个 feature，决定它走直接做、轻 spec 还是完整流程，以及每档具体怎么走。已经明确、批准且边界单一的任务可以直接判档。

直接做、轻 spec 和完整流程都要留下意图与验证证据，区别在于产物、质量门和审查强度。Bug、重构和交付后的 spec 维护另有专门纪律。

12.1 直接做

直接做省掉的是独立 spec 文件和多阶段流程，不是省掉意图和验证。开工前在任务描述或当前对话中写下三件事：

  1. 做完什么为真；
  2. 什么不能动；
  3. 怎样验证。

例如改登录页主按钮颜色，要指明具体页面和按钮、其他共用样式不能变化，并写下页面观察和视觉快照等验证方式。只说”把按钮改成蓝色”，无法判断改的是不是正确对象，也防不住共享样式被连带修改。

代码行为优先建立一个会失败的测试，再修改实现并看到它变绿。文案、配置、依赖等任务没有合适测试时，先运行能证明当前状态不满足目标的检查，再用快照、配置校验、构建结果或明确的人工观察验证改动。完成时报告实际证据，不用”已经改好”代替检查。

通过标准：预期结果、不可改范围和验证方式已经留下；改动没有超出边界；验证结果直接证明目标成立。

12.2 评估投入与定档

需求怎么分解成 feature、怎么判断纵切还是横切、feature 清不清楚要不要先 grill，都在第 10 章讲过。这一节只接手第 10 章之后、定档之前的两件事。

是否值得投入和把想法说清是两件事。仍需要判断值不值得做时，从 /speckit.assess.intake 开始，依次经过 intake、research、define、shape 和 decide。kill 到此结束；needs-clarification 回去补信息；go 只表示可以进入交付，不替代后面的任务分档。已经批准、只待实现的明确任务可以跳过 assess。

定档。拿到一个边界清楚、决定要做的 feature 后，按第 11 章的三问和反证信号判它走哪一档，再进入本章对应的流程走法。一次只处理一个 feature。

通过标准：当前只处理一个边界明确的 feature；是否投入已经决定；需要澄清的意图和术语没有留给实现阶段猜；该单元已经按任务分档规则定档。

12.3 轻 spec

轻 spec 是本手册定义的档位，不是 spec-kit 的原生模式。spec-kit 的 implement 需要已有规格、计划和任务，因此轻档仍运行：

specify → plan → tasks → implement

三条前置命令仍分别形成 spec.md、plan.md 和 tasks.md，不合并成一个文件。每份只保留当前改动必需的内容：

三份薄产物可以一次合并审查。轻档跳过 clarify、checklist 和 analyze；本手册还省略单独运行 converge，改为在实现后直接对照薄规格和任务清单验证。这是本手册对官方交付回路的额外裁剪，不是 spec-kit 自带的轻量模式。实现中出现未决边界、产物互相对不上或完成情况难以判断时，不继续压缩流程，升到完整档并补上相应质量门。

轻档是否还能保持”轻”，不按文件数、任务数或文档行数机械判断。材料开始承载多个边界、验证方式变得不稳定，或前面的硬下限和反证信号被触发时，重新判档。

通过标准：三份产物都存在且彼此一致；审查已经完成；实现结果满足薄规格；省略的质量门没有被当前任务的不确定性重新需要。

12.4 完整 Feature

完整档处理高风险、结构性或仍有重大不确定的 feature。意图需要澄清时，先走前面的 grill；意图已经清楚时，直接进入 spec-kit：

specify → clarify → plan → tasks → analyze → implement → converge

各阶段的产物和审查重点不同：

阶段产物或动作审查重点
specifyspec.md用户行为、边界、非目标和验收条件是否正确
clarify把未决答案写回规格关键歧义是否关闭；需要时增加 checklist 检查规格质量
planplan.md实现路径、架构边界和风险控制是否合理
taskstasks.md任务是否完整、有序、可验证，依赖关系是否清楚
analyze只读一致性报告规格、计划和任务是否冲突或遗漏
implement代码与测试是否按已批准任务实现，是否出现未经评估的偏离
converge完整性检查，必要时向 tasks.md 追加工作实现是否满足规格；新增任务是否需要继续实现和收敛

审查点不必都采用同一种人工门。高风险、不可逆或用户可见的关键决定必须由人批准；低风险阶段可以使用自动检查或合并审查。converge 追加任务后，重复 implement 和 converge，直到约定的 feature 完整交付。

通过标准：规格、计划和任务一致；要求人工批准的节点已有记录；测试和其他验收证据成立；converge 没有未处理的剩余任务。

12.5 Bug

spec-kit 的 bug 扩展提供三步流程，产物位于 .specify/bugs/<slug>/：

  1. /speckit.bug.assess 读取报告和代码，判断是否为真实 bug，定位疑似路径并提出修复方案；它不改源码，只写 assessment.md。
  2. /speckit.bug.fix 按 assessment 修复并写 fix.md。它是唯一修改源码的阶段；新证据要求扩大范围时，要在报告中记录偏离。
  3. /speckit.bug.test 重跑复现和相关测试并写 test.md。没有实际执行复现时，只能报告 partial 或 not-run，不能标 verified。

diagnose 不是 bug 扩展的第四步，而是根因复杂时插入的诊断方法。能够稳定复现、但 assessment 的根因仍不确定时，先留下失败测试或同等可重复的失败步骤，再用 diagnose 追踪根因；诊断结果改变修复方案时，先更新或重做 assessment，再进入 fix。根因清楚的普通 bug 不必额外运行 diagnose。

暂时无法复现的 bug 可以先用 assess 形成有证据和置信度的假设，但不能把假设当结论。fix 后仍无法实际复现，test 报告必须如实保留未验证状态。

通过标准：assessment、修复和验证能够互相追溯；修复范围的偏离有记录；只有真正执行过复现并证明问题消失，才能标 verified。

12.6 重构

重构不是独立档位。先按任务分档决定直接做、轻 spec 或完整流程，再增加”外部行为不变”的约束。轻档在薄规格中写明，完整档在 spec.md 中写明，并把建立行为基准列为实现前的第一个任务。

特征测试记录现有外部行为，因此它在未改代码上应该先通过。已有测试足以覆盖行为时可以直接复用；覆盖不足时，由 Agent 或人先起草特征测试，审查后冻结基准。为了证明测试真的守住行为，可以做一次受控的故障注入，看到测试变红后立即恢复到绿色，再开始重构。

实现阶段不得为了迁就新代码修改已经批准的基准。确实需要改变外部行为时，把它拆成单独的功能或 bug 任务，先修改意图和验收条件，不能混在”行为不变”的重构里。特征测试可能记录当前缺陷；已知缺陷要明确排除或另立 bug，不能不加判断地把它永久当成契约。

直接做的小重构如果已有充分测试，可以依靠现有安全网；没有覆盖时仍要先补最小特征测试。范围大的重构切成可以逐步验证的部分，每一步都保持基准为绿。

通过标准：基准在旧实现上通过，并证明能感知关键行为变化；实现期间基准没有随代码漂移；重构前后外部行为一致。

12.7 交付后维护 spec

spec-kit 提供三种持久化模型，没有默认选择：

三种模型共用 specify → plan → tasks → implement → converge 的交付回路。converge 只会向 tasks.md 追加剩余工作，不会修改规格去迁就代码；analyze 只报告不一致，也不会自动修正。核心命令没有自动调和三份产物的命令，需要团队直接修改，或使用行为明确的扩展。

模型要按团队需要选定并持续使用。混用时，同一份旧 spec 可能既被当作冻结记录，又被当作当前契约，后续任务无法判断哪份意图有效。

通过标准：团队已经写明采用哪一种模型；后续变更能确定应该新建还是更新 feature 目录；规格、计划、任务和代码没有保留互相冲突的口径。

本章小结

需求已按第 10 章分解成一个个 feature；本章针对单个 feature，投入未定时用 assess 评估，再按任务档位选择直接做、三份薄产物的轻 spec 或完整流程，Bug 和重构叠加各自的验证纪律。交付完成后固定一种 spec 持久化模型，避免历史记录和当前契约混在一起。

参考与出处