Spec Skills 与 Spec-First 交付：真正契合的是什么

大多数 AI 编码工具都在为一个目标做优化：让东西在未来十分钟内跑起来。Spec Skills 优化的是另一件事——确保生成出来的代码，就是你当初真正要的那个东西。这篇文章讲它如何嵌入 Spec-First 工作流，也坦白说清楚它在哪里能帮上忙，在哪里不行。

发布于 2026-03-09 · ✓ 已更新 2026-05-06 · 阅读约 7 分钟 · 作者：Daniel Marsh · 审校：编辑政策

"先跑起来再说" 的 AI 有什么问题

我见过足够多团队上手 Cursor、Copilot 以及各种聊天式编码工具，前三周的剧本我基本能背出来。速度上来了。Bug 从 "忘了加空值判断" 变成了 "把错的东西实现得一丝不苟"。代码看起来很干净。Diff 很小。但这个功能不是产品想要的那个。

这不是工具本身的问题。问题在于，它们优化的是用户嘴上几乎从不说的那个目标：先让它跑起来，规格以后再补。规格含糊，模型就自由发挥；验收标准是隐式的，模型就自己编一套。输出看上去很合理——而这是最糟糕的失败模式，因为它什么警报都不会触发，你的评审直觉完全没有启动。

Spec Skills 的立场

Spec Skills 的起点不一样。提示不是对代码的请求。提示是一份契约。它承载了规格、边界和验收标准，并且在任何生成发生之前就把这三者摆出来。这三块里任何一块缺席，Spec Skills 都不会生成——它会先让你把缺的那段补上。

一句话说完：生成被门控在一份完整的、显式声明的规格之上。其他东西——钩子、CI 卡点、PR 模板——都是围绕这一条约束搭起来的脚手架。

受约束的提示循环

循环长这样：先规格，再边界，再提示，然后 AI 输出，然后按规格做校验，最后合并或拒绝。Spec Skills 最不一样的地方是 "边界" 这一步。你要声明这次改动允许动哪些文件、哪些对外契约可以变。如果模型回来的 diff 动了声明范围外的文件，Spec Skills 会标红，输出不会自动合并。你可以覆盖决策，但覆盖是一次被记录在案的选择，不是默认行为。

校验也是显式的。验收标准按 Given/When/Then 块被解析出来，映射到测试或运行时检查上。如果代码通过了 lint，但某条标准没有对应的检查，Spec Skills 会把这件事说出来。评审的问题于是从 "这看起来对不对" 变成了 "这是不是我们要的东西"。

一个具体例子：退款端点

我合作过的一个团队用 Spec Skills 交付了一个退款端点。规格很短：对一笔已扣款的订单做退款，基于客户提供的幂等键保持幂等，拒绝超过 90 天的退款请求，成功时发出 refund.created 事件。声明的文件集：支付处理器、退款服务、一个测试文件。对外契约：一个新增的 POST 路由。

验收标准，按 Spec Skills 期望的形状写出来：

Given a captured charge from within 90 days
  And an idempotency key not seen before
When POST /refunds is called
Then a refund is issued
  And refund.created is emitted exactly once
  And the response status is 201

Given the same idempotency key is replayed
When POST /refunds is called
Then the original refund is returned
  And no new event is emitted
  And the response status is 200

Given a charge older than 90 days
When POST /refunds is called
Then the response status is 422
  And no refund is created
  And no event is emitted

第一次生成三条过了两条。重放那条失败了，因为模型把幂等状态存在了事件发出之后，导致重复事件。Spec Skills 把这个不匹配标出来，工程师调整了顺序，PR 就合了。真正的价值不是速度——是没有人需要在 staging 里才发现这个重复事件的 bug。

Spec Skills 不会替你做什么

它救不了一份烂规格。如果你的验收标准写的是 "退款应该正确工作"，Spec Skills 会生成一份看起来也正确工作的东西。垃圾进，垃圾出——只不过这次的垃圾上带了公章。

它救不了一个一心想让 AI 发明优雅抽象的模式爱好者工程师。边界执行这件事本身就是在压制发明；如果你的团队奖励的是聪明而不是贴合需求，大家就会绕过这个工具。

它也救不了盖章式的评审文化。校验会把不匹配摆出来，但评审者还是得读。一个在一分钟内点过 PR 的团队，对 Spec Skills 的 PR 也会一分钟点过，任何结构都救不了他们。

谁该用，谁不该用

如果你的团队已经在写技术规格——哪怕很短、哪怕不太正式——Spec Skills 会把你本来在做的事情磨得更锋利。习惯已经存在，摩擦就小。你主要会注意到的一件事是：因为 "这不是我想说的意思" 而被打回的 PR 变少了。

如果你的团队不写规格，也没打算开始写，别上这个工具。它会让你觉得像在走流程，拖慢你。因为一个工具逼你才开始建立规格纪律，是一条注定输的路径；因为纪律终于需要工具来支撑而引入工具，才是对的顺序。

集成点

实操里 Spec Skills 住在三个地方。一个 pre-commit 的 SCM 钩子，拒绝那些生成 diff 落在声明文件集之外的提交。一个 CI 卡点，重新跑一遍验收标准映射，阻断那些存在未覆盖标准的合并。一个 PR 模板，把规格、边界、Given/When/Then 和 diff 一起渲染出来。这三个东西单拎出来都不新。新的地方是它们指向同一份规格文档，所以漂移会以 diff 的形式可见，而不是停留在某个人的模糊感觉里。

信任模型，以及为什么这不是 "写个好提示" 就能解决

规格是可信的。AI 输出不是。这份不对称就是全部的重点。一个好的自由式提示，可以在某一次、给写出它的那个工程师、在他写它的那个会话里，产生一份好结果。下一个工程师写一份不一样的提示，得到一份不一样的结果，几周下来团队的行为就悄悄漂移，却没人察觉。

Spec Skills 真正贡献的是持久性。提示结构跨会话、跨工程师、跨仓库留存下来，因为它被编码进规格格式里，并由钩子执行。"写个好提示" 是一项个人技能。"规格承载提示" 是一项团队属性。这两件事不是一回事，而且只有第二件事能挺过人员流动。

这在实践中意味着什么

采用 Spec Skills 是一个流程决策，附带一套工具。如果你本来就相信规格是真相的单位、AI 输出是评审的单位，这套工具用起来会觉得理所当然。如果不是，它会让你觉得是负担——我的诚实回答是：先等着，等你的失败模式亲口告诉你该换了。用自由式 AI 快速交付的团队从不缺；稀缺的是六个月后输出仍然和当初所说一致的团队。

评审时看什么

这篇文章适合用在把 Spec Skills 接进 Spec-First 流程时。别从“原则”聊起，直接拿一条真实改动来对照，看看规格里还缺什么。

• 先选一个固定任务，不要从全流程自动化开始。
• 让输出落到文件、PR 或 issue，而不是停在聊天里。
• 每次生成都要能追到原始规格。
• 失败案例要反过来修改模板。

Spec Skills 的价值不在“多快生成”，而在它能不能让规格、实现和评审之间少断一次线。

最小可用的 Spec Skills 工作产物

如果团队刚开始，不需要一次性搭完整流程。我会先要求每个 AI 辅助功能留下三份文件：原始 ticket、生成后的 spec、人工评审记录。只要这三份在仓库里，后续事故复盘就有材料可查。

docs/specs/refund-v2/
- source-ticket.md
- feature-spec.md
- review-notes.md
- ai-session-link.txt
- test-evidence.md

边界：Spec Skills 不应该替代工程判断。它负责把问题问出来、把结构搭起来；是否接受范围、是否推迟边界情况、是否允许上线，还是人来决定。

最小检查清单

• spec 是否包含目标、非目标、验收标准、失败路径和回滚 owner？
• AI 会话是否引用了同一版 spec，而不是复制过期文本？
• 测试证据是否覆盖 API 响应、数据状态和日志事件？

可复制产物：Spec Skills 工作流包

把这段用于真实的 Spec Skills 运行前。它会把输入、边界和人工评审点放在同一处，避免输出看起来完整但责任不清。

Spec Skills 工作流包：Spec Skills 与 Spec-First 交付：真正契合的是什么

本次要做的决策：
- 把这篇文章里的工作流应用到一个真实工单，并确认输入、边界、输出和人工评审点。

责任人检查：
- 产品责任人：
- 工程责任人：
- QA 或运维评审：

范围边界：
- 本次包含：
- 本次不包含：
- 仍需确认的假设：

验收证据：
- 测试或 fixture：
- 日志、指标或截图：
- 人工复核步骤：

工具边界：模型可以起草结构和问题，范围、契约行为、发布风险仍然必须由责任人确认。

评审追问：
- 没参加需求会的人还会误解哪里？
- 哪个证据能证明这次改动足够安全，可以发布？

编辑复核记录

复核日期：2026-04-28。本次补充了可复用产物，按相关主题 Hub 检查了文章定位，并收紧下一步链接，让页面更像可操作参考，而不是孤立长文。