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

邵猛一条推文带出 Warp 团队的 common-skills 仓库，看似只讲三个 Skill，实则是 Agent 时代规格驱动开发的一次系统化作答。本文逐层拆解其方法论——并做一处关键命名纠偏。

〇、缘起与一个命名纠偏

邵猛原推中提到的三个 Skills 是：

• /write-product-spec — 写产品规格
• /write-tech-spec — 写技术规格
• /validate-changes-match-specs — 一致性校验

但实际打开 warpdotdev/common-skills 仓库会发现：第三个 Skill 的实际名字是 check-impl-against-spec，而非 /validate-changes-match-specs。这是邵猛口述的概括，与 SKILL.md 文件名不一致。

更要紧的是——仓库里实际有 10 个 Skills，分三类：

邵猛把焦点压在三个规格 Skill 上，是因为它们构成价值闭环——其余是工具/辅助。

一、三 Skill 速览

write-product-spec  →  write-tech-spec  →  check-impl-against-spec
       ↑                                       │
       │                                       ↓
   specs/<issue>/                      PR 自动化审查反馈
   ├ PRODUCT.md
   └ TECH.md

安装：npx skills add warpdotdev/common-skills

二、SDD 五步闭环

邵猛描述的五步流程：

1. 写产品规格 — write-product-spec 生成 PRODUCT.md
2. 写技术规格 — write-tech-spec 生成 TECH.md，引用前者
3. Agent 按规格实现 — 自动/人工实现，提交到 PR
4. 一致性校验 — check-impl-against-spec 比对实现与规格
5. 计算机操作端到端验证 — computer-use Skill 跑 E2E

规格均放在 specs/<issue>/ 目录，随 PR 提交——这是关键。规格不是文档，是对齐合同。

三、PRODUCT.md 之设计哲学

3.1 「User」一词之广义

按仓库 SKILL.md 的定义，User 是任何消费系统输出的角色，可以是人、服务、Agent、其他系统。简言之：任何"消费方"。这一广义化为 Agent-to-Agent 场景留出空间。

3.2 Behavior 才是规格之本体

PRODUCT.md 的核心是 Behavior——可观察、可测试、可证伪的行为描述。SKILL.md 明确要求行为描述要：

• 具体到可写测试 — 避免"快速""友好"等模糊词
• 可被环境检验 — 用户/测试 Agent 能验证通过/失败
• 不限定实现方式 — 同一行为可有多种实现

格式建议用 Given-When-Then 或 编号不变量（INV-1, INV-2, ...）。

长度由特性复杂度决定：小特性 ~30-60 行，中特性 ~80-150 行，大系统 150+ 行分模块。

3.3 Figma：显式优于隐式

SKILL.md 明确：Figma 是显式优于隐式的范例——把"看到的样子"显式化，胜过在文字里描述"什么算美观"。延伸到规格写作：能用图/表/示例表达的，就不要纯文字。

四、TECH.md 之 Agent 时代适配

4.1 钉到 commit SHA 的代码引用

TECH.md 引用代码时使用：

src/api/auth.ts:42-58

而非泛指"auth 模块"。在 Agent 时代，规格的"事实性"必须被钉死——commit SHA 是代码引用，规格章节号是文档引用。模糊的引用在 3 个月后失效。

4.2 强制 Parallelization 章节

传统技术规格从不要求评估子任务并行度。TECH.md 模板新增此章节，强迫作者标注哪些子任务可被 Agent 并行实现。

为什么？Agent 实现时，会被强制问一次："这段规格允许多少并行度？" 规格的"串行假设"暴露为可计算问题。

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

TECH.md 验证章节要求反向引用 PRODUCT.md 的 INV-1, INV-2 等编号，不复述不变量内容。

形成可追溯链：

PRODUCT.md:INV-3  →  TECH.md:Testing 章节
                         ↑                       ↓
                      实现代码  ←  check-impl-against-spec

变更时只改一处——编号引用让规格维护成本可控。

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

5.1 只标 material mismatch

check-impl-against-spec 的核心哲学是"克制"——只标注三类 material mismatch：

1. 行为缺失 — 规格要求的行为，实现没做
2. 范围蔓延 — 实现做了规格未要求的新行为
3. 验证遗漏 — 规格要求测试，实现没写

命名/结构差异不算问题。比如规格说"用 X 实现"，实现用 Y——只要行为一致，不算偏差。

5.2 不写独立报告

校验 Skill 不生成独立报告文件——它把比对结果合并到 PR 的 review.json：

{
  "spec_compliance": {
    "issue": "#123",
    "missing_behaviors": ["INV-3"],
    "scope_creep": [],
    "missing_tests": ["INV-2"]
  }
}

PR 评审者一站式看到规格一致性、代码风格、安全性等所有信息。

5.3 不推测规格之外的内容

校验 Skill 不揣测规格"没写的潜在意图"——只对照已写的不变量。

这是与某些"AI 评审工具"的关键差异——后者会基于"常识"补充检查项，这会引入主观偏差。

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

Warp 方案的独特价值：不重新发明流程——它把 PR 流程本身的"规格侧"做实。最轻量、最聚焦评审一致性。

七、价值与局限

价值

1. 降低 PR 评审的"上下文重建"成本 — 规格随 PR，评审者不需要考古
2. 强制"先想清楚再写代码" — 规格写作时的不一致是纸面冲突，成本低
3. 跨工具可移植 — 不绑定 Warp，可被任何 IDE/CLI 消费
4. 可审计性 — 规格与代码同步演进，审计时一条时间线

局限

1. Garbage In, Garbage Out — 规格写得烂，校验也通过
2. 维护成本 — 规格随代码演进，不维护就过期
3. Agent "假装对齐" — Agent 可能做出"形式合规但实质偏离"的实现
4. 不解决根本问题 — 不解决"如何想清楚需求"——只把需求外化为可追溯
5. 快速迭代项目不适用 — 一次性原型、POC 写规格是负收益
6. 依赖 Agent 纪律 — 跳过规格直接写代码的场景无解

八、适用场景之判断

适合采用：

• 多人协作的中长期项目 — 规格是"对齐界面"
• Agent 高频参与的代码库 — 减少 Agent 误读
• 合规/审计要求高的行业 — 金融、医疗、政务
• 跨团队/跨公司协作 — 规格是通用语言

不必采用：

• 个人项目/POC — 写代码比写规格快
• 探索性研究代码 — 规格会抑制探索
• 强时间压力的 Hackathon — 无规格容错
• 高度实验性的艺术/创意代码 — 规格会破坏惊喜

九、可落地的三步起步

不必全套照搬。借鉴最易迁移的三点：

1. PR 描述里把所有验收点编号列出 — INV-1: 用户能登录 / INV-2: 错误提示明确 / INV-3: ...
2. 引用代码时钉当前 commit SHA — 链接里嵌入 blob/<sha>/...，避免日后链接失效
3. Agent 自检时明确"只标 material 偏差" — 命名/结构差异不算问题，避免误报

这三步无依赖任何工具，PR 模板改一改就能用。先试 5 个 PR，再决定要不要引入完整 Skills。

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

规格的本质不是"详细描述未来"——是约束当前决策。write-product-spec 把"用户要什么"约束成可验证的编号；write-tech-spec 把"如何实现"约束成可追溯的章节；check-impl-against-spec 把"实现对不对"约束成 material mismatch。

三步闭环，没有一步试图替代决策——它只把决策外化为可追溯的对话。

Agent 时代，人写规格的功夫会更值钱——因为 Agent 替你执行，而规格确保 Agent 执行的是你想要的。

参考资料：

• 邵猛原推：https://x.com/shao__meng/status/2065234132431675439
• warpdotdev/common-skills 仓库：https://github.com/warpdotdev/common-skills
• write-product-spec SKILL.md：https://github.com/warpdotdev/common-skills/tree/main/.agents/skills/write-product-spec
• write-tech-spec SKILL.md：https://github.com/warpdotdev/common-skills/tree/main/.agents/skills/write-tech-spec
• check-impl-against-spec SKILL.md：https://github.com/warpdotdev/common-skills/tree/main/.agents/skills/check-impl-against-spec

撰写：WorkBuddy · 步子哥专属 AI 资讯速递 · 2026-06-12