先收敛范围
在实现之前写清目标、非目标、责任人、依赖，以及什么行为才算“完成”。
阅读完整指南推荐路径
决策矩阵
| 位置 | 写法 | 评审意义 |
|---|---|---|
| 模糊工单 | “用户可以退款订单。” | 缺少幂等、时间限制、事件行为和回滚责任人 |
| 可评审规格 | “90 天内已捕获订单可退款，按客户端 key 幂等，只发一次事件。” | QA 能测试重放、超期订单、重复事件和审计日志 |
| 发布证据 | 测试编号、日志查询、放量阈值、回滚动作 | 值班同学知道看什么、什么时候停 |
可复制片段
# Spec-First 启动包 ## 目标 - 用户或系统行为需要发生什么变化？ ## 非目标 - 本次发布明确不改变什么？ ## 验收标准 - Given ... When ... Then ... ## 证据 - 测试： - 指标或日志： - 回滚信号：
如何在真实迭代里使用这个 Hub
当一个工单开始“不那么显然”时，就适合打开这个 Hub。常见信号包括：涉及钱、数据一致性、权限、API 行为，或者发布后很难回滚。目标不是写一份很长的文档，而是找出那些如果不提前决定，就会在实现阶段被临时发明出来的问题。
一个实用的迭代流程很简单：选一个工单，打开启动块，先填非目标，再写会改变实现方式的验收标准。如果一条标准不会影响工程设计或测试方式，它很可能只是装饰。删掉它，把时间花在失败路径、回滚动作和决策责任人上。
评审时，不同角色应该提出不同类型的反对意见。产品可以拒绝不清楚的范围，工程可以拒绝隐藏依赖，QA 可以拒绝没有 fixture 或可观察结果的标准，运维可以拒绝没有停止信号的上线计划。每个角色都能拒绝具体内容时，规格才真正有用。
评审量表
| 检查项 | 通过标准 |
|---|---|
| 范围 | 目标、非目标、责任人和排除项都写清楚。 |
| 行为 | 主流程和至少一个失败路径可以测试。 |
| 证据 | 发布前有测试、日志、指标或人工检查。 |
| 交接 | 新评审者不用追问会议背景也能理解决策。 |
| 更新规则 | 评审后的规格变化记录日期和责任人。 |
常见失败模式
- 规格只描述功能，没有做出任何决定。
- 非目标太宽，无法阻止范围外需求。
- 验收标准只写 happy path，漏掉重复、超时、权限和回滚。
- 把评审通过当作证据，但没有运行时验证。
交接说明
交接产物应该短到能放进工单里，又完整到新工程师中途加入时也能接住上下文。最终规格要从 issue、PR 和 release note 里能找到，后续变更才知道当初为什么这么决定。
真实迭代示例
一个常见例子是退款流程，最初只在计划工单里写成一句话。Spec-First 不应该先讨论框架或数据库表，而应该先决定退款窗口、幂等行为、事件发送、客服 override、审计日志，以及支付网关超时时怎么回滚。决策写出来以后，实现反而会变小，因为团队不再一边看 diff 一边争论业务政策。
作者还应该记录一个被拒绝的方案。例如“90 天以上退款允许经理批准”。写清为什么拒绝，能避免未来评审者反复打开同一场争论。发布说明再链接规格、验收测试和指标，例如放量期间重复退款尝试是否保持为零。
真实场景拆解：退款流程
退款流程很适合作为 Spec-First 例子，因为一个小功能里同时有产品政策、API 行为、客服操作、事件投递和回滚边界。
| 决策 | 糟糕默认值 | 可评审规格选择 |
|---|---|---|
| 退款窗口 | 让客服按情况判断 | 已捕获款项 90 天内可退；例外需主管 override |
| 重复请求 | 重试调用，希望支付渠道去重 | 客户端幂等 key replay 时返回同一个 refund_id |
| 支付渠道超时 | 立即标记为失败 | 进入 pending_provider_confirmation，并阻止第二笔退款 |
| 发布止损信号 | 人工盯客服队列 | 重复退款尝试 15 分钟超过 0.5% 就停止放量 |
快速审核清单
把这个 Hub 用到真实团队之前，先做一个短审核。第一，读者离开页面时是否能复制一个产物到自己的流程里。第二，关联文章是否分别回答不同问题，而不是重复同一个定义。第三，页面是否点出了生产环境里真的会造成损失的失败模式，而不只是停留在计划阶段。
有用的 Hub 更像工作台。读者应该能打开页面，选择路径，复制片段，并知道评审前要附什么证据。如果页面只是解释主题，它只是另一篇文章；如果它能帮助读者决定下一步怎么做，它才是资源。
发布前复核问题
最后再问三个问题：这页是否让读者知道第一步该做什么；是否给了可以直接复制的文本；是否说明了什么情况下应该暂停而不是继续推进。只要其中一个答案是否定的，就不要把它当作完成。主题页的价值不是把文章重新包装一遍，而是把分散内容整理成一条能执行的路线。
这也是给审核员看的质量信号：页面有明确主题，有原创组织方式，有表格、流程、示例和行动项，并且能把读者带到下一步资源。它不是为了凑字数存在，而是帮助用户更快判断自己需要哪类规格、哪类证据和哪类评审。
核心与进阶文章
什么是 Spec-First 开发？
从方法、边界、验收标准和证据开始，建立团队共同使用的规格语言。
阅读文章如何在团队中推行 Spec-First
用 30 天节奏把团队从口头需求带到可评审的书面规格。
阅读文章编码前的规格评审清单
在实现前检查范围、边界情况、依赖和发布证据。
阅读文章同一个退款功能：Vibe Coding vs Spec Coding
用同一功能对比两种做法，展示规格如何提前暴露边界和回滚问题。
阅读文章Harness Engineering 与 Spec-First 的区别
区分“定义正确性”和“构建验证基础设施”这两件事。
阅读文章如何在编写迁移之前先规格化数据库模式
把表结构、约束、索引、迁移顺序和 API 对齐写进规格。
阅读文章常见问题
只适合大团队吗？
不是。最小可用版本就是一页：目标、非目标、验收标准和发布证据。小团队反而更需要，因为上下文更容易丢。
写多少才算够？
够到实现、测试和发布评审时不再临场发明行为。规格长度应该匹配风险，而不是匹配流程仪式。
需要直接落地时，先打开模板，再回到这页补齐评审和证据。