19 spec-driven 开发 把设计文档变成任务队列，用 git 当分布式锁

先记住这一句

这一章的状态徽章是部分落地，但含义与 第 08 章 不同：那里是「设计已写、代码未实现」；这里是协议本身完全没有代码——没有 bot、没有 workflow、没有校验器。它靠的是人和 agent 读文档、照做。

值得研究的原因也在这里：它是一套零实现成本的并发协议，而且真的在跑（git log 里有 8 次 reserve/unreserve 提交，文档里有 3 处活跃占用）。

协议全文

1. 与 main 同步。一个包可认领，当且仅当：复选框为空、依赖全部已勾选、
   且没有活跃 reservation 占用它或与之重叠的主文件。
2. 在包条目正上方加一行 `**Reserved: <id> by @<user>.**`，
   单独提交，消息为 `docs(agent): reserve <id>`。
   该提交进入 main 之后，认领才成立；若有冲突的 reservation 先落地，撤掉自己的重选。
3. 从 reservation 提交开始工作。读引用的设计与主文件。
4. 循环：实现 → 为每条自己拥有的不变量写可执行断言 → 迭代到全绿。
   设计不成立时停下，去 Discord 找 Mario 谈；达成一致后改设计再回到第 1 步。
5. 跑 `npm run check`。实现的 PR 顺手删掉自己的 reservation 并勾上复选框。
   放弃则只删 reservation，不勾。

四个设计细节

① 冲突解决用 git 的线性历史。「该提交进入 main 之后，认领才成立；若有冲突的 reservation 先落地，撤掉自己的重选。」——不需要任何服务、任何状态机。main 分支的顺序就是锁的仲裁顺序。

② 认领必须单独提交。「Land that change alone」。这样 reservation 与实现分离，认领可以在几分钟内进 main，而不必等实现写完——锁的持有窗口才不会因为 review 时间被拉长。

③ 依赖是显式的、可机读的。每个包写「Dependencies: none」或列出前置包，可认领条件包含「依赖全部已勾选」。41 个包因此构成一张 DAG，而不是一个待办列表。

④ 验收标准要求可执行断言，明确排斥冒烟测试。「Smoke tests and happy-path coverage alone are insufficient; each owned invariant must have an executable assertion.」harness-v2.md:3178

还有一张「谁拥有哪个公开方法」的表

This table is exhaustive. A package does not remove `HarnessNotImplemented` from a
method until it owns the listed semantics and tests.

| public surface | owning package |
|---|---|
| scaffold-safe `name`, `getLeafId`, record-free create, runtime settings | F0 |
| `AgentHarness.create()` restore and `suspended` inventory | R3 |

协议在 git 历史里的痕迹

4bf1bba20 docs(agent): reserve I2
102667952 docs(agent): unreserve R3
d406aa394 docs: reserve L1
9859eaa26 docs: reserve QA2
8ed232548 docs: reserve QA1
69bab864d docs(agent): reserve harness v2 R3
abac29f67 docs(agent): reserve harness R2 work package
290136253 docs(agent): reserve harness I0 and L1-L3 work packages
ea7bfdc08 docs(agent): unreserve R2 work package
afdf73661 docs(agent): reserve harness R1 work package
f909da2bf docs(agent): reserve harness R0 work package

快照时文档里有 3 处活跃占用，两处是标准格式，一处是历史特例——J 轨的所有权标记附了一段散文，解释这项工作在计划被拆成 J0–J6 之前就开始了。harness-v2.md:3260

范围也写死了

「工作限于 packages/agent、packages/session-backends/sqlite-node、packages/telemetry，以及 packages/ai 中的 telemetry 请求选项面。其它包的源码禁止触碰。」harness-v2.md:3169

在一个允许多个 agent 并行开工的仓库里，包级的文件所有权边界是防止互相踩踏的第一道防线——比 第 17 章 的 git 纪律更靠前。

为什么不用 GitHub Issues

Issues 天然就是任务队列，还自带认领（assignee）。pi 没用，原因推得出来但未见公开论述：

• 规格与任务在同一个文件里，同一次提交可以同时改两者。用 Issues 就得在两处维护，且必然漂移。
• 依赖关系在文档里是「上下文相邻」的。读 R3 的描述时，R0–R2 就在旁边。Issue 之间的依赖只能靠链接。
• agent 读一个文件比调 GitHub API 简单得多。这条对「让 agent 自己认领任务」这个用法是决定性的。

代价是把一个高频变更的看板塞进了一个应该稳定的规格文件——下面这条。

一份文件承担两种寿命

「系统应该长什么样」应该稳定；「谁在做哪一块」每天都在变。合在一起的直接后果是：一份 3437 行的文件成为高冲突热点，而且它的 git 历史里混杂着两类完全不同的变更——设计修订和进度更新。

「reservation 单独提交」缓解了冲突（改动小、进 main 快），但没有消除根因。J 轨那段解释历史的散文就是症状：当看板结构本身演化时（计划被拆成 J0–J6），你需要在规格文件里写一段散文解释历史。

「协议无实现」是优点还是缺陷

优点是显然的：零构建成本、零维护成本、任何能读 markdown 和用 git 的参与者（人或 agent）都能立刻加入。

缺点同样显然：没有任何东西阻止两个人同时勾同一个框，也没有任何东西检测「reservation 挂了三个月没人动」。整个机制的执行力等同于参与者的自觉——与 第 17 章 的 AGENTS.md 是同一种赌注。

在当前规模（3 处活跃占用、少数几个 track 同时开工）这个赌注赢面很大。它的失效条件不是「有人作弊」，而是「参与人数上升到没人能记住谁在做什么」。

这套东西真正新颖的地方

把设计文档当任务队列不新鲜（Kubernetes 的 KEP、Rust 的 RFC 都类似）。pi 这套的特别之处是它是为「参与者可能是 agent」设计的：

• 认领动作是一次文件编辑 + 一次提交——agent 最擅长的两件事；
• 可认领条件是可机读的谓词（复选框空 + 依赖全勾 + 无重叠 reservation），不需要判断力；
• 失败路径明确（冲突就撤掉重选），不需要谈判；
• 唯一需要人的地方被显式标出来了：「设计不成立时，去 Discord 找 Mario」。

最后一条最关键：协议把「什么时候必须找人」写进了流程，而不是指望 agent 自己意识到该求助。

• 无实现 = 无强制。没有 bot 检查 reservation 冲突、检查复选框与实际代码是否一致、或回收僵尸 reservation。全靠自觉。
• 「先进 main 者胜」在 PR 队列长时体验很差。你的 reservation 提交要排队 review，排队期间别人可能已经落地了冲突的认领。协议要求你「撤掉重选」——但工作可能已经开始了。
• 复选框与代码可能不一致。没有任何东西保证「F0 已勾选」对应「F0 的验收标准真的满足」。本书通过读代码交叉验证了 F0（22 个抛错方法确实存在），但这属于人工核对，没有自动化。
• 不可移植到没有单一权威的项目。「设计不成立就去 Discord 找 Mario」——这套协议的争议解决机制是一个具名的人。没有这样一个人的项目照抄不了。
• 规格文件的 git 历史被进度更新稀释。想追溯「这个设计决定是什么时候改的、为什么」，要在几十次 reserve/unreserve 提交里翻找。

检查过并确认：8 次 reserve/unreserve 提交中有 2 次是 unreserve，说明放弃路径被真实使用过；且 unreserve R2（ea7bfdc08）与后来的 reserve harness v2 R3（69bab864d）分属不同工作包，不构成同一包的反复占用。

• 用「单独提交一行认领标记 + 先进主干者胜」当分布式锁。零基础设施，git 已经提供了你需要的全部原子性与顺序性。 适用条件：主干合并是线性的、认领提交能快速合入。PR 队列以天计的项目会让这个锁失效。
• 把「什么时候必须停下来找人」写进流程本身。pi 写的是「设计不成立时，去 Discord 找 Mario」——具体到人和渠道。 适用条件：执行者是 agent 或新人。这是本章最该抄的一条：agent 不会自己意识到该求助。
• 可认领条件要写成机读谓词，不要写成判断题。「复选框为空 + 依赖全勾 + 无重叠 reservation」任何参与者都能自己判定，不需要问维护者。 适用条件：你希望参与者自助认领。需要维护者分派的项目不需要这一层。
• 但要考虑把「设计」和「进度」拆成两份文件。pi 没拆，代价是规格文件成了高冲突热点，且它的 git 历史里设计修订与进度更新混在一起。 拆开的代价是两处维护、必然漂移——这是个真实的两难，pi 选了一边并承担了它。