fujian_water_biz_doc/docs/guides/SPECKIT_WORKFLOW_HUMAN_GUIDE.md

Speckit 工作流的人类友好教学文档

1. 先说结论

Speckit 的理论基础，不是“先写一堆文档”，而是先把一个需求拆成一连串可验证的小闭环，再让每个闭环都留下明确工件。

在这个工作区里，它本质上是在解决四个老问题：

1. 需求很容易一开始就说大了，最后越做越散。
2. 文档、代码、验证和台账经常各说各话。
3. 多仓协作时，大家都在干活，但没人能准确回答“现在到底做到哪了”。
4. 交付时只能靠口头解释，缺少稳定的追溯链。

所以 Speckit 不是“文档优先”这么简单，它更准确的说法是：

用规格驱动的方式，把需求澄清、方案收敛、任务拆解、实现验证、结论回写做成一个个可追溯闭环。

---

2. 它基于什么理论

结合本仓库的 constitution、模板和工作流说明，Speckit 的底层思想主要来自以下几类工程方法。

2.1 单一真源

核心思想是：正式结论必须有唯一归属，不能让多个版本并行竞争。

在本仓库里，这被明确成：

• 正式内容优先回写主文档
• specs/ 是过程工件和治理工件
• Archive 是来源，不是正式结论
• backend/frontend 负责实现，不负责定义正式规格

这对应的是经典的软件工程思想：single source of truth。

2.2 逐步求精

同一个需求，不在一开始就展开到代码细节，而是逐层收敛：

1. 先确认到底要解决什么问题
2. 再确认边界和约束
3. 再确认要怎么拆
4. 再进入实现和验证

这对应的是：stepwise refinement，也就是逐步求精。

2.3 需求到交付的可追溯性

每个阶段都要能回答两个问题：

• 你这个结论是从哪里来的？
• 你这个结果后来落到哪里去了？

所以它天然要求：

• spec 能追到 source of truth
• plan 能追到 spec
• tasks 能追到 user story / requirement
• implementation / evidence 能追到 tasks
• 最终结论能回写正式文档和台账

这对应的是：traceability。

2.4 小步闭环，而不是大步推进

很多团队的问题，不是不会做，而是喜欢一次推进太多内容，导致：

• 范围没锁住
• 任务没拆清
• 验证没前置
• 回写没人做

Speckit 的做法是把系统构建看成多个连续闭环，而不是一个大瀑布。

这更接近：iterative delivery 和 feedback loop。

---

3. 它到底怎么通过一个个闭环构建系统

可以把 Speckit 理解成 6 个连续闭环。

前一个闭环的输出，是后一个闭环的输入。

闭环 1：范围闭环

目标：先回答“这次到底做什么，不做什么”。

输入：

• 用户意图
• 主文档
• Archive 历史资料
• 当前代码现状

输出：

• spec.md
• 明确的纳入范围
• 明确的排除范围
• 明确的验收口径

闭环成功的标志：

• 评审者只看 spec.md 就能判断是否超范围
• 团队不会把“以后可能做”误当成“这轮必须做”

这一步解决的是“方向漂移”。

闭环 2：决策闭环

目标：把范围内仍然模糊的关键问题收敛成可执行决策。

输入：

• spec.md
• 现有设计文档
• 冲突来源
• 需要裁决的问题

输出：

• research.md
• 一组关键决策和理由

闭环成功的标志：

• 后续规划不再反复争论同一个问题
• 每个重要选择都能说清“为什么这样定”

这一步解决的是“大家都觉得自己理解对，但没有正式裁决”。

闭环 3：设计闭环

目标：把“需求”转成“可落地结构”。

输入：

• spec.md
• research.md

输出：

• plan.md
• data-model.md
• contracts/*
• quickstart.md

闭环成功的标志：

• 已经知道涉及哪些文档、哪些仓、哪些接口、哪些数据对象
• 已经知道最小验证动作是什么
• 已经知道正式主文档后续该怎么回写

这一步解决的是“知道要做什么，但还不知道怎么组织”。

闭环 4：任务闭环

目标：把设计转成可分配、可执行、可检查的任务。

输入：

• plan.md
• data-model.md
• contracts/*
• quickstart.md

输出：

• tasks.md

闭环成功的标志：

• 每个任务都能映射到具体文件、具体仓、具体验证动作
• 每个 user story 都可以独立评审
• 任务不是“继续完善一下”这种抽象话，而是明确动作

这一步解决的是“设计有了，但执行还是靠临场发挥”。

闭环 5：实现与验证闭环

目标：把任务变成实际改动，并证明改动有效。

输入：

• tasks.md
• docs/backend/frontend 各 lane 的执行结果

输出：

• 正式文档修改
• 代码改动
• 校验结果
• evidence / final verdict

闭环成功的标志：

• 改动完成后有对应验证
• 验证结果能追溯到具体基线
• 不是“我本地看起来可以”，而是有可复核证据

这一步解决的是“做了，但没人能确定真的完成了什么”。

闭环 6：治理回写闭环

目标：把阶段结果沉淀回正式体系，而不是停留在聊天记录或临时分支里。

输入：

• 已完成的文档和代码结果
• 验证结果
• feature 基线

输出：

• 主文档回写
• 01_Project_Progress.md
• 03_Task_Checklist.md
• 必要的 evidence 与最终结论

闭环成功的标志：

• 别人不看聊天记录，也能知道当前状态
• 后续 feature 可以直接站在当前结论上继续推进

这一步解决的是“这次做完了，但组织记忆没有留下来”。

---

4. 一个需求是怎么一步步长成系统的

可以把整个过程理解成下面这条链：

用户问题
-> spec 锁范围
-> research 锁关键决策
-> plan 锁实施结构
-> tasks 锁执行清单
-> implementation 锁实际改动
-> verification 锁完成证据
-> ledger/main docs 锁组织记忆

这条链最重要的地方在于：

每一步都不是为了“写文档”，而是为了减少下一步的不确定性。

举例：

• spec 不是为了写需求书，而是为了防止做着做着变成另一个项目
• plan 不是为了写方案书，而是为了让任务拆解有稳定骨架
• tasks 不是为了列清单，而是为了让 lane 执行可分配、可验收
• verification 不是为了走流程，而是为了把“我觉得好了”变成“证据表明好了”

---

5. 为什么它适合复杂系统，而不只是适合写文档

因为复杂系统最怕的不是工作量大，而是下面这四种失控：

1. 需求失控：边界不清，越做越大
2. 结构失控：模块、接口、数据口径互相冲突
3. 执行失控：任务拆不稳，协作互相阻塞
4. 认知失控：做完后没人说得清当前状态

Speckit 的价值，就在于它把这四种失控分别放进不同闭环里处理：

• spec 管需求失控
• plan / contracts / data-model 管结构失控
• tasks 管执行失控
• verification / ledger sync 管认知失控

所以它不是“文档流程”，而是一个 复杂系统治理流程。

---

6. 在这个仓库里，Speckit 的真实落地方式

在 water-workspace 里，Speckit 不是独立于实现的平行世界，而是正式治理层。

职责边界是：

• water-docs：负责正式 spec/plan/tasks/evidence 和主文档回写
• water-backend：负责后端实现与后端验证
• water-frontend：负责前端实现与前端验证
• tmux + worktree：负责并行执行现场

也就是说：

Speckit 定义“应该做什么、如何验收”
lane 执行“具体怎么做出来”
water-docs 负责“最终正式结论落到哪里”

这就是为什么仓库里一直强调：

• .specify/ 只保留在 water-docs
• backend/frontend 不复制第二套 spec-kit
• 正式工件统一回到 water-docs

---

7. 人最容易误解的几个点

误解 1：Speckit 就是先写文档再开发

不准确。

更准确的说法是：先把决策和验收条件固定，再进入开发。

如果一个需求很小，完全可以不走完整流程。

误解 2：有了 spec，就等于已经设计好了

不对。

spec 主要回答“做什么”和“做到什么算完成”。

真正回答“怎么组织、怎么拆、怎么验证”的，是 plan、data-model、contracts 和 tasks。

误解 3：tasks 只是项目管理清单

不对。

tasks 在这里是执行接口，作用是把规格层结论翻译成 lane 可以直接消费的动作。

误解 4：验证是收尾动作

不对。

在 Speckit 里，验证条件应该从 spec 和 plan 阶段就开始定义，而不是等实现完才临时想。

---

8. 对新人最实用的理解方式

如果你不想一上来记所有命令，可以只记下面四句话：

1. spec：先把边界锁住。
2. plan：再把结构和依赖锁住。
3. tasks：再把执行动作锁住。
4. verify + 回写：最后把结果锁进正式系统。

把它翻成更口语的话就是：

先确认做什么
再确认怎么做
再确认谁去做
最后确认做完没有，并把结论留下来

这就是 Speckit 最朴素、也最重要的本质。

---

9. 一张总图

用户需求
  ↓
specify / clarify
  产出：范围、边界、验收口径
  闭环：范围闭环
  ↓
plan
  产出：方案、决策、模型、合同、最小验证
  闭环：决策闭环 + 设计闭环
  ↓
tasks
  产出：可执行任务、lane 映射、独立验收切片
  闭环：任务闭环
  ↓
implement / verify
  产出：代码、文档、验证证据
  闭环：实现与验证闭环
  ↓
ledger sync / main docs update
  产出：正式结论、项目进度、任务状态、基线
  闭环：治理回写闭环

---

10. 推荐给团队的教学方式

如果你要拿这套流程教别人，建议不要从命令开始讲，而是按下面顺序讲：

1. 先讲为什么团队会失控：范围、结构、执行、认知四种失控。
2. 再讲 Speckit 用哪些闭环分别处理这四种失控。
3. 再讲 spec -> plan -> tasks -> verify -> 回写 的工件链。
4. 最后才讲仓库里具体怎么落地到 water-docs、water-backend、water-frontend。

这样新人先理解“为什么”，再理解“怎么做”，吸收速度会快很多。

---

11. 与本仓库口径对应的参考来源

本说明基于以下仓内材料整理：

• water-docs/.specify/memory/constitution.md
• water-docs/.specify/templates/spec-template.md
• water-docs/.specify/templates/plan-template.md
• water-docs/.specify/templates/tasks-template.md
• docs/TMUX_WORKTREE_TEAM_WORKFLOW.md
• water-docs/AGENTS.md
• 现有 water-docs/specs/* 工件样例

如果这些基础材料后续更新，本教学文档也应同步修订。

---

12. Speckit 与工程控制论的关系

如果从方法论上看，Speckit 和钱学森提出的工程控制论确实很接近。

但要说得准确一些，不是“完全一样”，而是：

Speckit 可以理解为一种面向软件研发治理的工程控制论实践。

12.1 相似之处

两者都关心同一件事：

怎样让一个复杂系统朝目标稳定演化，而不是边做边失控。

在 Speckit 里，这种相似性主要体现在下面几项。

1. 都先定义目标状态

工程控制论强调，控制之前必须先明确目标。

Speckit 里对应的是：

• spec 定义目标
• spec 定义边界
• spec 定义完成条件

也就是说，系统不是“先干起来再说”，而是先定义希望到达什么状态。

2. 都强调观测当前状态

控制不能脱离观测。

Speckit 在进入规划和实施前，都会先看：

• 主文档现状
• Archive 来源
• backend / frontend 当前实现
• 验证结果
• 台账状态

这相当于先观察系统当前状态，而不是只看目标。

3. 都依赖偏差分析

控制的核心不是“下命令”，而是发现偏差、修正偏差。

Speckit 实际上一直在比较：

• 目标和现状是否一致
• 文档和代码是否一致
• 接口、数据、设计之间是否一致
• 任务完成状态和验收标准是否一致

只要不一致，就说明存在偏差，需要继续修正。

4. 都通过反馈回路持续校正

这和传统“一路写到最后再看结果”的思路不同。

Speckit 的典型反馈方式是：

• 范围不清，回到 spec
• 关键决策冲突，回到 research 或 plan
• 设计与接口不一致，回到 contracts / data-model
• 验证不过，回到任务或实现
• 结论未沉淀，回到主文档和台账

这本质上就是反馈控制。

5. 都有分层控制结构

工程控制论往往不是单层控制，而是多层协同。

Speckit 也一样：

• spec 控目标层
• plan 控结构层
• tasks 控执行层
• verify 控结果层
• ledger sync 控组织记忆层

每一层控制的对象不同，但共同服务于整体稳定性。

12.2 不同之处

两者也有明显区别。

钱学森的工程控制论，更多研究的是：

• 物理工程系统
• 工业过程
• 技术系统运行中的控制规律

而 Speckit 控制的不是设备本身，而是：

• 需求如何收敛
• 设计如何对齐
• 任务如何拆解
• 实现如何验证
• 结论如何沉淀

所以它控制的是：

研发过程和交付过程。

不是狭义的设备控制，而是过程治理。

12.3 为什么这个类比有价值

把 Speckit 理解成“工程控制系统”，会比把它理解成“文档流程”更准确。

因为这样你会自然意识到：

1. spec 不是装饰品，而是目标设定器。
2. plan 不是空洞方案，而是结构控制器。
3. tasks 不是待办清单，而是执行调度器。
4. verify 不是收尾动作，而是反馈传感器。
5. ledger 不是行政记录，而是组织状态记忆。

这样一来，团队就不会把每个工件当成独立文件，而会把它们看成控制链上的不同节点。

12.4 一个更贴切的理解

可以把 Speckit 理解成下面这个模型：

目标设定
-> 状态观测
-> 偏差识别
-> 方案校正
-> 执行调节
-> 结果验证
-> 组织回写
-> 下一轮控制

这条链本身就是一个闭环控制系统。

而 Speckit 的价值，正是在于它把软件研发从“经验驱动、口头协调、事后补救”，变成了“目标明确、过程可观测、偏差可修正、结果可追溯”的受控过程。

12.5 教学时可以怎么讲

如果要对团队解释这层关系，建议直接用这句话：

Speckit 不是让大家多写文档，而是用工程控制论的思路，把复杂研发过程变成一个有目标、有反馈、有校正的闭环系统。

这句话通常比单纯讲命令和模板更容易让人真正理解它的价值。

---

13. 小闭环是怎么组织成大闭环的

这是理解 Speckit 最关键的一步。

很多人会以为：

• spec 是一个闭环
• plan 是一个闭环
• tasks 是一个闭环
• implement 是一个闭环

然后这些闭环只是顺序排开。

其实不是。

更准确的理解是：

小闭环是分层嵌套的，前一个闭环的输出会变成后一个闭环的控制输入；很多 feature 闭环继续累积，才会形成系统级大闭环。

13.1 先看四层结构

在这个工作区里，可以把闭环分成四层。

第一层：动作闭环

这是最小闭环，通常是一组非常具体的动作：

修改
-> 校验
-> 修正
-> 记录结果

例如：

• 改 12_REV_Detailed.md
• 执行 make validate-file
• 如有链接变更再跑 make check-links
• 结果写入 quickstart 或最终结论

这一层解决的是“这一个动作到底有没有做实”。

第二层：用户故事闭环

这是把多个动作闭环拼成一个可以独立评审的能力片段：

一个用户故事
-> 若干文档动作
-> 若干代码动作
-> 独立验证
-> 形成局部结论

这一层解决的是“这一个业务片段是否已经独立成立”。

第三层：feature 闭环

这是把多个用户故事闭环拼成一个 feature 的完成链：

spec
-> plan
-> tasks
-> implement
-> verify
-> ledger sync

这一层解决的是“这个 feature 是否已经成为系统中的稳定能力单元”。

第四层：系统交付闭环

这是最大的闭环：

需求池
-> feature 闭环 1
-> feature 闭环 2
-> feature 闭环 3
-> 主文档与台账持续更新
-> 系统能力版图逐步收敛

这一层解决的是“整个系统是否在有秩序地长出来”。

13.2 最重要的一句话

可以把这四层关系记成一句话：

动作闭环保证局部真实，故事闭环保证片段成立，feature 闭环保证能力落地，系统闭环保证整体演进。

---

14. 用你当前系统做案例讲解

下面直接用你仓库里的 REV-004 和 REV-005 来讲。

14.1 系统目标不是一次性实现，而是逐块实现

你现在这个营收系统，不是靠“一次大开发”完成的，而是靠多个 feature 闭环逐步长成。

从当前仓库可以看到几个典型能力块：

• REV-004：账务处理一期
• REV-005：发票业务流
• REV-006：催缴与通知
• REV-007：统计分析

这四个 feature 不是平行孤岛，而是在共同补齐营收系统的核心业务版图。

也就是说，系统级大闭环大致是：

营收系统目标
-> 一个个 feature 进入 Speckit
-> 每个 feature 形成可控闭环
-> 每轮闭环结果回写主文档和台账
-> 系统整体能力逐步成形

14.2 先看 REV-004：它在补什么系统能力

REV-004 的本质，不是“写一份账务说明”，而是在给系统补一块能力底座：

• 明确账务处理一期边界
• 统一 IF-REV-007
• 统一留痕、原始依据、结果状态
• 再按场景拆到账务调整、退款、冲正、坏账申请

这意味着 REV-004 的价值不是单一功能点，而是：

先把账务处理域里的共性控制骨架搭起来。

如果这块不闭合，后面的退款、冲正、坏账等就会各自长成不同口径。

所以 REV-004 这个 feature 闭环，本质上是在给系统建立：

• 账务场景边界
• 账务接口边界
• 账务留痕边界
• 账务状态边界

这是一块“平台型能力闭环”。

14.3 再看 REV-005：它在补什么系统能力

REV-005 的计划更接近实现闭环。

从 002-rev005-invoice-flow/plan.md 可以看出，它要补的是：

• 后台发票申请
• 后台单笔/批量开票
• SYS-008 异步申请与查询兜底
• 发票结果回写
• 账单与发票关联
• 客户侧查询/下载/推送

这说明 REV-005 不是一个接口修补，而是在补一个完整业务结果链：

收费账单
-> 发票申请
-> 外部发票服务协同
-> 查询补偿
-> 结果回写
-> 客户消费结果

这是一块“流程型能力闭环”。

14.4 为什么 REV-004 和 REV-005 能拼成更大的闭环

因为它们不是随机 feature，而是在系统业务链上前后衔接。

可以这样理解：

• REV-004 负责账务处理域中的调整、退款、冲正、坏账等控制逻辑
• REV-005 负责收费后发票结果的业务闭环

两者共同服务的是“营收处理全过程”的可控性。

举个直白例子：

如果系统里发生退款或冲正，账务状态一定会影响后续发票状态、发票可用性、结果展示和客户消费体验。

所以：

• 没有 REV-004，REV-005 可能会缺失上游账务一致性约束
• 没有 REV-005，REV-004 的结果又无法完整延伸到发票交付链

它们拼起来，才更接近真实的营收业务闭环。

14.5 从小闭环拼成大闭环的真实过程

下面用更接近执行的方式来描述。

第一步：先闭合 REV-004 内部的小闭环

例如先闭这些：

1. 范围闭环
2. IF-REV-007 统一合同闭环
3. 留痕与结果状态统一闭环
4. 退款/冲正原交易校验闭环
5. 正式文档与执行手册回写闭环

这些闭完后，REV-004 才算从“讨论账务”变成“系统已有一套稳定账务处理骨架”。

第二步：再闭合 REV-005 内部的小闭环

例如继续闭这些：

1. 发票申请闭环
2. SYS-008 查询兜底闭环
3. 发票结果回写闭环
4. 账单-发票关联闭环
5. 客户侧查询/下载/推送闭环
6. backend 编译与文档回写闭环

这些闭完后，REV-005 才算从“发票规划”变成“系统已有一条稳定发票结果链”。

第三步：再把 feature 闭环在系统层面接起来

这一步不是再写一份大而全的总方案，而是靠以下机制自然接起来：

• 主文档持续回写
• 接口设计持续统一
• 数据库承接口径持续统一
• 项目进度与任务台账持续记录
• 新 feature 继续站在前一轮闭环结论上推进

这就形成了系统级大闭环：

账务闭环稳定
-> 发票闭环接入
-> 通知闭环接入
-> 统计闭环接入
-> 各能力通过主文档、接口、数据、台账不断统一
-> 营收系统形成整体受控结构

14.6 为什么主文档和台账这么重要

很多团队的大闭环之所以拼不起来，不是因为他们没有做 feature，而是因为：

• 每个 feature 的结论只留在聊天记录里
• 代码改了但主文档没回写
• 台账不更新，没人知道当前真实状态
• 下一个 feature 启动时，又重新猜一遍现状

这样 feature 虽然一个个做了，但系统级大闭环拼不起来。

而你这个仓库里一直强调：

• 主文档单一真源
• 重要结果回写 01_Project_Progress.md
• 任务闭环更新 03_Task_Checklist.md

它的真正作用就是：

让上一个 feature 的输出，成为下一个 feature 的稳定输入。

这正是大闭环成立的关键条件。

---

15. 一个更贴近实现目标的系统级示意图

如果你的最终目标是“把营收系统真实实现出来”，可以把当前过程理解成下面这张图：

系统目标：形成可交付、可实现、可验证的营收系统
  ↓
Feature A：REV-004 账务处理一期
  - 闭合范围
  - 闭合接口
  - 闭合留痕与状态
  - 闭合账务场景控制骨架
  ↓
Feature B：REV-005 发票业务流
  - 闭合申请
  - 闭合查询兜底
  - 闭合结果回写
  - 闭合客户消费链路
  ↓
Feature C：REV-006 催缴与通知
  - 闭合任务生成
  - 闭合消息协同
  - 闭合结果回写
  ↓
Feature D：REV-007 统计分析
  - 闭合统计口径
  - 闭合指标来源
  - 闭合输出与追溯
  ↓
主文档 / 接口设计 / 数据库设计 / 台账 / evidence 持续统一
  ↓
系统级大闭环：各业务域能力逐步收敛成一个整体系统

这张图里最重要的是：

不是先有“大闭环设计”，再去硬塞小闭环。

而是每个 feature 先形成稳定能力块，再通过统一主文档、统一接口、统一数据库口径、统一台账回写，把这些能力块拼成系统级闭环。

---

16. 给当前实施目标的直接建议

如果你现在的目标是“以系统实现为目的继续推进”，那最实用的策略不是问“什么时候整个系统才算闭环”，而是每一轮都问下面三个问题：

1. 当前这个 feature，补的是系统里的哪一块能力？
2. 这块能力内部还有哪些小闭环没闭？
3. 这轮闭合后的结果，会通过哪些主文档、接口、数据和台账，变成下一个 feature 的输入？

只要这三个问题一直答得清楚，系统级大闭环就会自然长出来。

反过来说，如果这三个问题答不清楚，就算团队一直在干活，也很容易变成“局部热闹，整体失控”。