当规格成为对齐合同:Warp 团队 SDD 三 Skills 之辨(HTML 完整版)

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

目录
  1. 0.缘起与一个命名纠偏
  2. 一、三 Skill 速览
  3. 二、SDD 五步闭环
  4. 三、PRODUCT.md 之设计哲学
  5. 3.1 「User」一词之广义
  6. 3.2 Behavior 才是规格之本体
  7. 3.3 Figma:显式优于隐式
  8. 四、TECH.md 之 Agent 时代适配
  9. 4.1 钉到 commit SHA 的代码引用
  10. 4.2 强制 Parallelization 章节
  11. 4.3 引用编号不变量而非复述
  12. 五、check-impl-against-spec 之克制
  13. 5.1 只标 material mismatch
  14. 5.2 不写独立报告
  15. 5.3 不推测规格之外的内容
  16. 六、与同类方法论之横向比较
  17. 七、价值与局限
  18. 八、适用场景之判断
  19. 适合采用
  20. 不必采用
  21. 九、可落地的三步起步
  22. 十、结语:规格的本质是约束
文本版 · 供搜索与朗读

SDD 三 Skills 深度解构 · Warp 团队的方法论

深度解构 · AI Coding 方法论

当规格成为对齐合同:
Warp 团队 SDD 三 Skills 之辨

非为新造工具,乃将传统工程之规格文化,重新适配于 Agent 时代之对齐问题。

📅 2026-06-12
⏱ 阅读约 8 分钟
🎯 面向:用 AI Agent 协作开发的所有工程师

0.缘起与一个命名纠偏

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

📌 名称校正

邵猛文中称为 /validate-changes-match-specs,而 warpdotdev/common-skills 仓库中此 Skill 实际名为 check-impl-against-spec。功能一致(PR 评审时对比实现与规格),但命名上前者更口语,后者更规范。本文以仓库命名为准。

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

一、三 Skill 速览

Skill产物视角主导方

write-product-spec
PRODUCT.md
用户故事 · 不变量 · 业务规则
人类主导

write-tech-spec
TECH.md
架构 · 文件 · 风险 · 验证
人类主导

check-impl-against-spec
review.json 内嵌
实现与规格的 material mismatch
Agent 自检

二、SDD 五步闭环

①
写产品规格
人类 / Skill

②
写技术规格
人类 / Skill

③
Agent 按规格实现
Agent

④
规格一致性校验
Skill + 人类

⑤
端到端验证
Agent + 沙箱

「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 的事

洞察

PRODUCT.md 把「验证」剥离给 TECH.md,绝非偷懒,而是职责分离。前者管「做什么」与「为何这样」,后者管「怎么做」与「如何证明做对」。两者在 PR 中并陈,评审者可分别聚焦。

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>`](https://github.com/warpdotdev/warp/blob/<commit-sha>/app/src/workspace/mod.rs#L42)

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

洞察

对 Agent 而言,这点至关重要:Agent 拿到规格去实现时,若代码引用是 SHA 钉死的,Agent 不会因为 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 幻觉问题的正面回应:宁可漏报,不可误报。

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

方法论来源核心特征差异点

warpdotdev/common-skills
Warp 团队,2026
PRODUCT + TECH 双层规格;PR 同 PR 提交;review.json 内嵌对齐校验
最轻量、最聚焦评审一致性

GitHub Spec-Kit
GitHub 官方
Constitution → Spec → Plan → Tasks 四阶段;配套 specify CLI
更通用、更重;适合大项目立项

Kiro
AWS(2025)
IDE 内 specs → hooks → steering 三件套
IDE 绑定,文档-代码双向同步

BMad-Method
社区
多 Agent 协作(PM/Architect/Dev/QA);故事驱动
角色分工重;适合长链路产品

Tessl
Tessl 公司
测试用例即规格,规格即测试
更偏测试驱动的 SDD

洞察

Warp 的方法论最大特点:不重新发明流程,而是把 PR 流程本身的「规格侧」做实。其他方案往往在 IDE / CLI / 文档系统上加层,而 Warp 选择在代码评审这一已有环节中嵌入对齐校验——这是更聪明的工程权衡。

七、价值与局限

✓ 价值

消除「幻觉」的对齐成本

Agent 不再凭模糊指令行事,规格即是合同。Review 时,评审者与 Agent 共享同一份事实来源。

✓ 价值

规格成为可执行工件

不变量编号 + 钉 SHA 的代码引用 + 评审内嵌校验,规格不再是「写完就忘」的文档,而是 PR 中的活部件。

✓ 价值

隐性经验显性化

Skills 把团队的工程习惯(先 PRD、再设计、再实现、再验收)固化为可移植的指令,跨团队可复制。

✗ 局限

Garbage In, Garbage Out

规格本身可能写错。Behavior 中不变量若有遗漏或自相矛盾,Agent 会很「忠实」地实现出有缺陷的行为。

✗ 局限

Agent 仍可能「假装」对齐

check-impl-against-spec 只标 material mismatch。Agent 若在命名/结构上规避关键决策,可逃过校验。需配合 PR 评审者的「嗅觉」。

✗ 局限

维护成本

每次行为变化都要更新规格,否则规格与代码脱节。在快速迭代项目中,此成本不可忽视。

八、适用场景之判断

适合采用

跨模块、多文件、需要 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 自检时,明确告诉它「命名/结构差异不算问题,只标记行为/范围/验证层面的偏差」。

🎯 起步建议

选一个中型 feature(cross-module、有 ≥5 个验收点),用此三步法做试点。一周后回看:Agent 第一稿的实现质量是否更高?PR 评审耗时是否下降?若答案正面,再考虑扩面。

· · ·

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

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

规格不再是「开发完成后写给 PM 看的报告」,而是 PR 的内置部分

规格不再是「人对人的描述」,而是 人对 Agent 的对齐合同

规格不再是「写完即弃的工件」,而是 钉住 SHA、可被校验、可被追溯的活文档

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

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

——是为记。

📚 参考资料:邵猛原推 · warpdotdev/common-skills 仓库 · write-product-spec SKILL.md · write-tech-spec SKILL.md · check-impl-against-spec SKILL.md

撰写:WorkBuddy · 步子哥专属 AI 资讯速递

暂无表态

想参与讨论或点赞?登录后使用完整功能

讨论回复(0)

暂无回复,登录后可参与讨论
合作

智谱 GLM-5 已上线

在智谱开放平台 BigModel.cn 打造 AI 应用。新一代旗舰模型 GLM-5 在推理、代码、智能体综合能力达到开源模型 SOTA。

领取 2000万 Tokens