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

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

"先跑起来再说" 的 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：
- 日志、指标或截图：
- 人工复核步骤：

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

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