0.缘起与一个命名纠偏

邵猛于 6 月 12 日发推，介绍 Warp 团队提出的 Spec 驱动开发（SDD）三 Skills。其文风简练，却藏着 Warp 团队几年 Agent 协作的工程沉淀。然行文之中有一处需要订正——

仓库实际包含 10 个 Skills，分三类：规格工作流（4）、开发工作流（5）、技能编写（1）。我们今日所议，仅取其规格驱动核心之三。

一、三 Skill 速览

二、SDD 五步闭环

「Agent 出错往往是需求理解偏差，不是代码能力不够。」——邵猛

此言颇得三昧。Agent 推理虽强，理解常偏。规格者，人与 Agent 间之对齐合同也。

三、PRODUCT.md 之设计哲学

初读 write-product-spec 的 SKILL.md，便觉几处克制与精准值得细品——

3.1 「User」一词之广义

Skill 明文规定：「『User』不限于终端用户」——

• UI 特性：使用 Warp 的人
• 数据模型：读写该模型的代码
• API / 协议 / 库：调用方（其他服务、客户端、插件、Agent）
• CLI / 开发者面：调用它的开发者

此一界定，破解了「规格一定要以人为视角」的迷思。规格描述消费面的契约，不是实施细节的脚注。

3.2 Behavior 才是规格之本体

Behavior is the spec. Everything else is framing.

Skill 明确：Summary、Problem、Goals 等皆为框架，可有可无；Behavior 才是规格之骨。其写法亦有讲究：

• 以编号的、可测试的不变量（numbered, testable invariants）形式书写
• 长度由特性复杂度决定：trivial 无规格；small ~30-60 行；medium ~80-150 行；large 更长
• 刻意不写 Validation、Success criteria、Testing 章节——那是 TECH.md 的事

3.3 Figma：显式优于隐式

无 Figma 时，必须显式写 Figma: none provided，而非省略。看似小节，实为消除隐含假设的工程实践——规格里任何「没说」的地方，都会被 Agent 任意填充。

四、TECH.md 之 Agent 时代适配

TECH.md 的设计，处处透露出对 Agent 工作流的原生适配。三处最为精妙：

4.1 钉到 commit SHA 的代码引用

app/src/workspace/mod.rs:42 @ <commit-sha>

引用代码时，强制 git rev-parse HEAD 捕获 SHA，并在 Markdown 链接中嵌入此 SHA。读者点击，看到的是写规格那一刻的代码，而非 main 分支上可能已变动的版本。

4.2 强制 Parallelization 章节

若环境支持 run_agents，TECH.md 必须评估是否启用并行子 Agent，并给出：

• 每个子 Agent 的 role、subtask、execution mode（local / remote）
• 工作目录 / worktree 路径——避免并行 Agent 撞同一个 checkout
• 分支与 PR 策略——一 Agent 一 PR，还是合并 PR
• 协调边界——每个 Agent 拥有哪些文件，何时同步

这是传统软件规格文档不曾要求的章节。它承认了一个事实：现代 Agent 协作开发，从一开始就要按并行设计，否则后期串行化成本巨大。

4.3 引用编号不变量而非复述

TECH.md 在 Testing and validation 章节中，要求直接引用 PRODUCT.md 中的编号不变量，而非复述其内容。例：

Behavior §1.3「网络断开 5 秒内恢复，重试不丢失请求」应被集成测试 test_retry_under_network_blip 覆盖。

这种反向引用，让规格之间形成可追溯链——任何一项测试，向上可追到产品行为，向下可追到代码位置。

五、check-impl-against-spec 之克制

此 Skill 颇值一书者，乃其「懂得不说什么」：

5.1 只标 material mismatch

四种情况才标记：

• 产品规约中要求的行为缺失
• 实现与规约决策矛盾
• 引入大量未规划的范围
• 遗漏必要的验证、迁移、兼容步骤

「命名差异」「结构调整」「低级实现选择」不算 mismatch。这避免了一种常见病——规格评审变成无止境的细枝末节之争。

5.2 不写独立报告

Do not create a separate report file. Fold spec-alignment findings into review.json.

规约对齐的发现，直接合并到常规 PR 评审的 review.json。这意味着：

• 评审者只看一份输出，不在规格报告与代码评审之间来回切换
• 规约对齐是评审的子任务，不是独立流程
• 工具链更简单——不需要维护一份「规约报告」文档

5.3 不推测规格之外的内容

Do not speculate about spec details that are not actually present in spec_context.md.

只比对 spec_context.md 中白纸黑字写下的承诺，不擅自推断「规格本应如此」。这是对 Agent 幻觉问题的正面回应：宁可漏报，不可误报。

六、与同类方法论之横向比较

七、价值与局限

八、适用场景之判断

适合采用

• 跨模块、多文件、需要 Code Review 的中型以上特性
• 业务规则复杂、不变量繁多（金融、权限、合规）
• 团队需要把隐性工程经验沉淀下来，跨成员复用
• Agent 协作场景明确，PR 是核心协作单元

不必采用

• trivial 改动（修个 typo、单个 import）
• 探索性原型（先写代码验证可能性，再回头补规格成本太高）
• 纯一次性脚本（specs/ 目录反而成为负担）
• 团队对规格文化本身抵触——SDD 是流程改造，强行推行会反噬

九、可落地的三步起步

不必全套照搬。建议从以下三步渐进：

• 借鉴 PRODUCT.md 的「不变量编号」：即便不用 Warp，PR 描述里把所有验收点编号列出（如 - [ ] §1.3 离线 5 秒恢复后请求不丢失），让 Agent 实现时知道要满足哪些点。
• 借鉴 TECH.md 的「钉 SHA 引用」：在规格文档里引用代码时，把当前 commit SHA 写进链接。成本几乎为零，价值巨大。
• 借鉴 check-impl-against-spec 的「只标 material」：让 Agent 自检时，明确告诉它「命名/结构差异不算问题，只标记行为/范围/验证层面的偏差」。

十、结语：规格的本质是约束

读罢三 Skill 之设计，吾人所见者，非为「文档驱动开发」之老调重弹，而是在 Agent 时代对规格文化的重新校准——

• 规格不再是「开发完成后写给 PM 看的报告」，而是 PR 的内置部分
• 规格不再是「人对人的描述」，而是 人对 Agent 的对齐合同
• 规格不再是「写完即弃的工件」，而是 钉住 SHA、可被校验、可被追溯的活文档

若用一句话概括 Warp 团队这三 Skills 的精髓：

把规格当作 Agent 的合同，而非开发的脚注。

——是为记。