当规格成为对齐合同：Warp 团队 SDD 三 Skills 之辨（HTML 完整版）

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 资讯速递