如何在团队中推行 Spec-First（30 天计划）

在团队里推 Spec-First，本质上是个组织问题，不是技术问题。模板是最容易做的事，难的是养成习惯。如果你是那个想说服团队开始写规格的人，你大部分精力都会花在证明"它能省时间"上，而不是教大家怎么写。下面这套 30 天节奏，我已经跑通过三次，同时也讲清楚那些最容易让推广胎死腹中的失败模式。

发布于 2026-02-25 · ✓ 已更新 2026-05-06 · 阅读约 8 分钟 · 作者：Spec Coding 编辑团队 · 审校：编辑政策

现场笔记：真正跑起来的落地方式很窄

我见过最顺的一次落地，只从一个支付流程和每周一次 25 分钟评审开始。团队没有给流程改名，也没有成立新的审批小组。大家只约定：凡是碰到钱的工单，写代码前必须有非目标、失败路径和回滚证据。

试点规则：
- 适用：账单、退款、订阅变更
- 写代码前必须有：责任人、非目标、失败路径、回滚触发条件
- 评审时间：每周二 25 分钟
- 成功信号：PR 里追问“这到底该怎么做”的评论变少

从事故切入，而不是从流程切入

第一周还没开始之前，你得先有证据。挑一件最近发生的线上事故，或者错过的 deadline——越痛越好——然后回溯到"如果当初把这个决策提前做出来就不会踩坑"的那个节点。"要是 kickoff 的时候把退款那条边界情况写下来，我们就不会在 QA 阶段吵三天。"就这一句话，比任何关于流程的 PPT 都有说服力。

Spec-First 不能作为一种哲学去卖。它只能作为"解决团队已经公认的某个具体问题"的方案来卖。

第 1 周：一个志愿者，一个功能

不要宣布什么"全团队推行"。挑一个感兴趣的工程师，挑一个即将要做的功能。两个人一起写这份规格，结对完成。真正交付的不是这份规格本身，而是这一对人因为写了规格才做出的那些决策——把它们记下来。

第一周结束时你要产出的东西是：

• 一份 1 到 3 个小时写完的规格，不是磨了 3 天的那种。
• 3 到 5 条决策清单——这些决策如果不写规格，本来会拖到实现阶段才浮现。
• 另外一个工程师扫了一眼，说"哦，这东西确实有用"。

第三条才是真正的目标。一个不是你本人的信徒。没有这个人，推广活不过第三周。

第 2 周：公开写

那位志愿者把功能交付了。在 code review 或者复盘会上，他要走一遍——规格里的哪些具体条目在实现过程中挡住了坑。这不是事故复盘，是 show-and-tell。重点是可见性：让其他工程师亲眼看到这份规格到底在什么地方起了作用。

这时候你百分百会收到一条反对意见："但我做的功能，规格里写的东西我本来就已经知道了。"正确的反应不是跟他争辩。正确的反应是请他下一个功能也写一份，专门跟踪这份规格有没有逼出他原本还没做过的决策。

通常是会逼出来的。有时候确实没有——简单的功能不需要规格。两种情况都要诚实承认。

第 3 周：在一个品类里把它设为默认

挑一个品类，强制要求必须写规格——任何涉及钱、数据完整性，或者对外 API 契约的东西——然后用一段话把这个政策发出去。不要写"所有功能都要写规格"。太宽了，人人都会反抗。"涉及计费流程或结账流程的改动，实现之前必须先有规格"就足够窄，能落地。

写这个政策的时候留一个逃生口："经技术负责人批准可豁免。"这一点很关键。没有豁免的强制要求会被记恨。有豁免的强制要求反而会被遵守，因为没人真的会为了鸡毛蒜皮的事去用豁免权。

第 4 周：看数据

数两件事：

• 规格逼出了多少条原本要到后面才会发现、代价更高的决策？（每份规格 3 到 5 条为合格线。）
• 每份规格写了多久？（应该是 1 到 3 小时，而不是一整天。）

第一个数字高、第二个数字低，说明推广有势能。这时候可以扩大必须写规格的范围，但要慢慢来。如果第一个数字低——规格没能逼出决策——说明模板太浅。回过头重新审视规格里到底该放什么。

真正会被用起来的模板

模板要短。如果大纲超过一页，没人愿意动笔。我用的大致是这个：

## Goal
一句话。用户或系统层面的结果。

## Non-goals
3-6 条。别人可能以为我们要做、但我们不做的事。

## Acceptance criteria
按需写，Given/When/Then 格式。每条 happy path
至少配一条 failure path。

## Edge cases
按类别分：输入边界、状态转换、并发、
时间相关、错误。

## Rollout & rollback
怎么上线。回滚在物理层面意味着什么。
止损阈值用数字写清楚。

## Open questions
所有还没决定的事。每个问题都要有负责人
和一个决策 deadline。

就这六段。大多数规格能压进 2 到 4 页。忍住添加"背景"或"动机"这种章节的冲动，除非这个功能真的需要。

推广通常死在哪里

失败 1：太早把它设成 review 的强制关卡

如果团队还没看到价值，规格就已经成了 review 的必交物料，那它就会被当成合规剧本来写——用最短的文档满足流程要求。这比不写规格还糟。至少要先有 2 到 3 份"确实挡下了真实问题"的规格范本，再去加这个关卡。

失败 2：自己一份都不写

要想把 Spec-First 推给团队，你自己就得写规格，公开写，为你自己手上的活儿写。一个强制别人写规格、自己却一份都没有的 manager，是信任层面的问题。先写好两三份像样的，再去要求别人。

失败 3：模板假装每个功能都很复杂

12 段的模板会把简单功能吓跑，自己也退化成走流程。按复杂度分级做模板——一份给 CRUD 型功能，一份给涉及钱或身份的流程，一份给架构变更。让人自己挑。

失败 4：从不用复盘闭环

4 到 6 周之后，看最近 5 起事故：写规格能不能预防这件事？如果能，它在当时合理的条件下能不能真的做到（答案不总是"能"）？如果模式清晰，这就是你扩大政策范围的证据。如果模式不明显，反过来缩范围——Spec-First 没你以为的那么管用。

真正该看的指标

不要用"多少比例的功能写了规格"当指标。那衡量的是 paperwork。真正该看的指标是：实现过程中有多频繁要停下来问规格作者一个问题？这个数字随时间下降，规格就在起作用。一直居高不下，规格就是走仪式。

我见过团队从每个功能平均 5 到 10 次实现期澄清，用两个月降到一个功能不到一次。这才是真正的回报。其他好处——review 更快、交接更干净——都是顺带的。

什么时候该停

Spec-First 不是宗教。有些功能写规格只会增加摩擦、不增加清晰度——小的 UI 微调、文档更新、依赖升级。明确说清哪些地方不适用。强行把规格推到所有事情上的团队，最后都会因为开销配不上价值而把这套实践彻底丢掉。

目标不是全面覆盖。目标是：对于那些"模糊会带来时间成本"的功能，让模糊在纸面上被暴露出来，而不是在实现阶段才爆。其他情况都是可选的。

落地示例：用两个功能做试点

我见过最顺利的落地，不是从流程制度开始，而是从两个即将进入开发的功能开始：一个低风险 UI 改动，一个高风险账单改动。团队只要求账单功能使用完整规格模板，UI 改动只写一页轻量说明。

试点规则：
- 完整规格：资金流、权限、数据迁移、外部 API 契约。
- 轻量说明：文案、小布局、内部重构。
- 复盘问题：实现阶段的澄清问题是否减少？

这让团队没有把 Spec-First 误解成“所有事都要写大文档”。实践能扩大，是因为大家先看到了它在哪里减少风险。

第一轮试点不要选“最重要项目”

团队导入 Spec-First 时，最容易犯的错是拿年度大项目试点。压力太大，大家会把流程问题和项目风险混在一起。更好的选择是一个中等复杂、跨两三个角色、两周内能上线的功能。

Pilot scope:
- feature: refund reason capture
- roles: PM, backend, frontend, QA
- duration: 10 working days
- required artifacts: one-page spec, review notes, test evidence
- success metric: fewer clarification comments during implementation
- do not include: pricing policy rewrite, database ownership change

边界：不要把导入变成文档运动。试点只证明一件事：提前写清验收标准，是否减少了实现阶段的反复。

衡量采用效果，不衡量文档数量

我不会统计团队写了多少 spec。更有用的指标是：实现中途新增需求的次数、QA 打回率、PR 里澄清问题数量、生产事故里“需求理解错误”的占比。文档数量上去了但返工没降，流程就是空转。

试点结束时，我会回看三份证据：spec 修改历史、PR review 评论、QA 缺陷列表。看这些比听大家感觉更准。若澄清问题减少、测试用例更早出现、回滚 owner 更明确，就说明流程在工作。

推广时也要给团队一个“退出条件”。如果三轮试点后 spec 没减少澄清、QA 仍然拿不到测试证据、PR 没有链接规格、owner 也不更新模板，就先缩小范围。流程失败时先调设计，不要逼所有人写更多文档。

试点模板也要固定字段：feature owner、review owner、API owner、QA owner、测试证据、回滚路径、未决问题和上线状态。字段固定后，每轮试点才能横向比较，而不是靠大家会后感觉。

可复制产物：交付评审包

当文章要进入计划、设计评审或发布准备时使用。它让责任人、证据和停止条件保持可见。

交付评审包：如何在团队中推行 Spec-First（30 天计划）

本次要做的决策：
- 把责任人、门禁、证据和止损条件写到交付流程里。

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

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

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

流程边界：实现前必须写明责任人、决策记录、证据和止损阈值。

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

二次审阅记录：落地应该先显得无聊

这次把文章重点收回到渐进落地。团队不需要一次新的方法论发布会，只需要一个能先证明价值的规则。

落地检查：
- 先挑一个高风险流程，不要覆盖整张路线图。
- 衡量返工和评审追问，不要只数文档数量。
- 第一版模板控制在一页以内。
- 如果流程只增加审批，没有带来更好决策，就先停。

编辑复核记录

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