# 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. 一个需求是怎么一步步长成系统的 可以把整个过程理解成下面这条链： ```text 用户问题 -> 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`：负责并行执行现场 也就是说： ```text 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 + 回写`：最后把结果锁进正式系统。 把它翻成更口语的话就是： ```text 先确认做什么 再确认怎么做 再确认谁去做 最后确认做完没有，并把结论留下来 ``` 这就是 `Speckit` 最朴素、也最重要的本质。 --- ## 9. 一张总图 ```text 用户需求 ↓ 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` 理解成下面这个模型： ```text 目标设定 -> 状态观测 -> 偏差识别 -> 方案校正 -> 执行调节 -> 结果验证 -> 组织回写 -> 下一轮控制 ``` 这条链本身就是一个闭环控制系统。 而 `Speckit` 的价值，正是在于它把软件研发从“经验驱动、口头协调、事后补救”，变成了“目标明确、过程可观测、偏差可修正、结果可追溯”的受控过程。 ### 12.5 教学时可以怎么讲 如果要对团队解释这层关系，建议直接用这句话： **`Speckit` 不是让大家多写文档，而是用工程控制论的思路，把复杂研发过程变成一个有目标、有反馈、有校正的闭环系统。** 这句话通常比单纯讲命令和模板更容易让人真正理解它的价值。 --- ## 13. 小闭环是怎么组织成大闭环的 这是理解 `Speckit` 最关键的一步。 很多人会以为： - `spec` 是一个闭环 - `plan` 是一个闭环 - `tasks` 是一个闭环 - `implement` 是一个闭环 然后这些闭环只是顺序排开。 其实不是。 更准确的理解是： **小闭环是分层嵌套的，前一个闭环的输出会变成后一个闭环的控制输入；很多 feature 闭环继续累积，才会形成系统级大闭环。** ### 13.1 先看四层结构 在这个工作区里，可以把闭环分成四层。 #### 第一层：动作闭环 这是最小闭环，通常是一组非常具体的动作： ```text 修改 -> 校验 -> 修正 -> 记录结果 ``` 例如： - 改 `12_REV_Detailed.md` - 执行 `make validate-file` - 如有链接变更再跑 `make check-links` - 结果写入 quickstart 或最终结论 这一层解决的是“这一个动作到底有没有做实”。 #### 第二层：用户故事闭环 这是把多个动作闭环拼成一个可以独立评审的能力片段： ```text 一个用户故事 -> 若干文档动作 -> 若干代码动作 -> 独立验证 -> 形成局部结论 ``` 这一层解决的是“这一个业务片段是否已经独立成立”。 #### 第三层：feature 闭环 这是把多个用户故事闭环拼成一个 feature 的完成链： ```text spec -> plan -> tasks -> implement -> verify -> ledger sync ``` 这一层解决的是“这个 feature 是否已经成为系统中的稳定能力单元”。 #### 第四层：系统交付闭环 这是最大的闭环： ```text 需求池 -> 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 不是平行孤岛，而是在共同补齐营收系统的核心业务版图。 也就是说，系统级大闭环大致是： ```text 营收系统目标 -> 一个个 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](/Volumes/Dpan/github/water-workspace/water-docs/specs/002-rev005-invoice-flow/plan.md) 可以看出，它要补的是： - 后台发票申请 - 后台单笔/批量开票 - `SYS-008` 异步申请与查询兜底 - 发票结果回写 - 账单与发票关联 - 客户侧查询/下载/推送 这说明 `REV-005` 不是一个接口修补，而是在补一个完整业务结果链： ```text 收费账单 -> 发票申请 -> 外部发票服务协同 -> 查询补偿 -> 结果回写 -> 客户消费结果 ``` 这是一块“流程型能力闭环”。 ### 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 继续站在前一轮闭环结论上推进 这就形成了系统级大闭环： ```text 账务闭环稳定 -> 发票闭环接入 -> 通知闭环接入 -> 统计闭环接入 -> 各能力通过主文档、接口、数据、台账不断统一 -> 营收系统形成整体受控结构 ``` ### 14.6 为什么主文档和台账这么重要 很多团队的大闭环之所以拼不起来，不是因为他们没有做 feature，而是因为： - 每个 feature 的结论只留在聊天记录里 - 代码改了但主文档没回写 - 台账不更新，没人知道当前真实状态 - 下一个 feature 启动时，又重新猜一遍现状 这样 feature 虽然一个个做了，但系统级大闭环拼不起来。 而你这个仓库里一直强调： - 主文档单一真源 - 重要结果回写 `01_Project_Progress.md` - 任务闭环更新 `03_Task_Checklist.md` 它的真正作用就是： **让上一个 feature 的输出，成为下一个 feature 的稳定输入。** 这正是大闭环成立的关键条件。 --- ## 15. 一个更贴近实现目标的系统级示意图 如果你的最终目标是“把营收系统真实实现出来”，可以把当前过程理解成下面这张图： ```text 系统目标：形成可交付、可实现、可验证的营收系统 ↓ Feature A：REV-004 账务处理一期 - 闭合范围 - 闭合接口 - 闭合留痕与状态 - 闭合账务场景控制骨架 ↓ Feature B：REV-005 发票业务流 - 闭合申请 - 闭合查询兜底 - 闭合结果回写 - 闭合客户消费链路 ↓ Feature C：REV-006 催缴与通知 - 闭合任务生成 - 闭合消息协同 - 闭合结果回写 ↓ Feature D：REV-007 统计分析 - 闭合统计口径 - 闭合指标来源 - 闭合输出与追溯 ↓ 主文档 / 接口设计 / 数据库设计 / 台账 / evidence 持续统一 ↓ 系统级大闭环：各业务域能力逐步收敛成一个整体系统 ``` 这张图里最重要的是： 不是先有“大闭环设计”，再去硬塞小闭环。 而是每个 feature 先形成稳定能力块，再通过统一主文档、统一接口、统一数据库口径、统一台账回写，把这些能力块拼成系统级闭环。 --- ## 16. 给当前实施目标的直接建议 如果你现在的目标是“以系统实现为目的继续推进”，那最实用的策略不是问“什么时候整个系统才算闭环”，而是每一轮都问下面三个问题： 1. 当前这个 feature，补的是系统里的哪一块能力？ 2. 这块能力内部还有哪些小闭环没闭？ 3. 这轮闭合后的结果，会通过哪些主文档、接口、数据和台账，变成下一个 feature 的输入？ 只要这三个问题一直答得清楚，系统级大闭环就会自然长出来。 反过来说，如果这三个问题答不清楚，就算团队一直在干活，也很容易变成“局部热闹，整体失控”。