什么是 Spec-First 开发？（完整指南）

一个团队如果交付很快但不断返工，并不是在跑得更快——而是在烧跑道。问题几乎总是一样的：没人在编码之前写清楚"完成"是什么意思。Spec-First 开发解决这个问题——在实现之前定义验收标准，而不是之后。

发布于 2025-11-20 · ✓ 已更新 2026-05-11 · 阅读约 8 分钟 · 作者：Daniel Marsh · 审校：编辑政策

1. 核心理念：先写规格文档，再写代码

Spec-First 开发的前提很简单：用文字做出的决策改起来便宜，嵌入代码里的决策改起来贵。Spec-First 要求团队在写任何实现代码之前，先写一份技术规格文档——覆盖系统应该做什么、不应该做什么，以及如何判断成功。这不是设计文档，也不是 Jira 工单，而是工程、产品和 QA 都能在第一行生产代码出现之前阅读和评审的书面契约。

承诺的时刻提前了。团队争论措辞，而不是重写服务。

2. 先编码的模式实际是怎么运转的

先编码的工作流里，开发者收到一张工单，根据会议记录或口头对话理解需求，然后开始构建。规格文档如果存在，也是事后补写的——描述已经构建的东西，而非计划构建的东西。边界情况在代码评审或 QA 时才暴露。非目标从未被声明，范围自然膨胀。等到问题出现，改方向的成本已经很高了。

这不是某个工程师的失职，而是结构性问题。规格缺失时，每一个歧义都被私下消化——在代码里，由当时握着键盘的人决定。这些决策悄悄积累，直到系统在生产环境里做出令人意外的事情。

3. 规格文档实际上包含什么

一份有用的技术规格文档不是大段散文。它在实现开始之前回答一组具体问题：

• 目标：这解决了什么用户问题或业务成果？
• 非目标：这次变更明确不在范围内的是什么？
• 验收标准：什么样的可观测行为证明功能正确工作？
• 边界情况：哪些输入或状态需要特殊处理？
• 错误路径：当事情失败时，系统做什么？
• 回滚：如果出现问题，团队如何撤销变更？

注意，这些问题没有一个询问系统是如何实现的。规格文档描述行为，而非架构。工程团队对实现选择保留完全的决定权。

Spec-First 示例：用户密码重置

以下是 Spec-First 团队在构建密码重置功能之前会撰写的验收标准：

Feature: Password Reset via Email

Goal: Allow users who have forgotten their password to regain account access
Non-goals: Social login recovery, admin-initiated resets, SMS-based verification

Acceptance Criteria:
- Given a registered email address
  When the user submits the reset form
  Then a reset link is sent within 30 seconds and expires after 1 hour

- Given an email address not in the system
  When the user submits the reset form
  Then the same success message is displayed (no account enumeration)

- Given a valid reset link
  When the user sets a new password under 8 characters
  Then the form rejects the input with a specific validation message

- Given a reset link that was already used
  When the user clicks it again
  Then a clear "link expired" message is shown with a link to request a new one

Rollback: Feature flag `password_reset_v2` — set to false to revert to legacy flow

QA 工程师可以直接从这份文档推导出测试用例。工程师清楚地知道要实现什么行为。产品经理可以确认这符合用户意图。这一切都不可能通过一张写着"添加密码重置"的工单来实现。

规格文档与 AI 辅助编码的关系

Spec-First 开发一个被低估的好处是它与 AI 编码工具的完美配合。当你给 AI 助手提供一份清晰、结构化的规格——目标、非目标、验收标准、边界情况——与给它一个模糊的自然语言描述相比，输出质量会显著提升。

AI 工具擅长将精确的规格翻译成代码。当规格是隐式的时，它们就会挣扎。那些在编码前投入时间撰写清晰规格的团队发现，AI 辅助开发变得更加可靠，因为模型有明确的行为目标，而不必去推断意图。

Spec-First 减少返工，而非降低速度

对撰写规格文档最常见的反对意见是它会拖慢团队。在实践中，在项目的完整生命周期内，情况恰恰相反。在大多数团队中消耗最多工程时间的工作不是全新开发——而是重新审视那些从未被明确的决策、修复由未记录假设引起的错误，以及在实现过程中处理范围争议。

一份写得好的规格文档，对于中等复杂度的功能，需要一到三个小时来完成。这项投入在第一次评审者在实现开始之前（而不是之后）发现被误解的需求时，就得到了回报。规格文档不会拖慢团队；它将歧义的代价集中在最便宜的时刻。

7. 对齐的团队以更少摩擦交付

规格文档创造了会议无法产生的对齐。会议在那个时刻产生房间内的共同理解。规格文档产生书面记录，团队中任何人在任何时候都可以参考，包括不在会议中的人和后来加入项目的工程师。

当产品、工程和 QA 在工作开始前都审阅同一份规格文档时，每个角色都可以从自己的角度标记关注点，而此时变更仍然代价低廉。产品可以发现缺失的需求。工程可以标记技术限制。QA 可以识别不可测试的标准。这种异步评审比任何同步会议发现更多问题，并留下决定了什么以及为什么的记录。

Spec-First 不是什么

Spec-First 不是瀑布模型。它不需要在任何代码编写之前进行六个月的规格阶段。它不意味着每个功能都需要一份 20 页的文档。对于简单功能，规格可以是半页；对于复杂功能，可以是五页。纪律是相同的：在开始构建之前写下成功是什么样的。

它也不是一个官僚式的审批流程。规格文档是团队的工具，而不是合规文物。如果规格文档放在一个没人阅读的文件夹里，它就没有发挥作用。规格文档的价值体现在它所创造的评审对话中——实现之前的异步协作，防止了后来在代码中出现的昂贵发现。

Spec-First 入门

最快的上手方式：选路线图上的下一个功能，在碰代码之前写一页文档。目标、两三个非目标、四到六条 Given/When/Then 格式的验收标准。实现开始前发给评审者，看看他们发现了什么。

大多数团队试过一次之后都会保留这个做法。价值是立竿见影的——体现在实现讨论的质量和 QA 测试的清晰度上。这就是 Spec-First 在实践中的基础。

现场笔记：重写规格后，设计真的变了

我见过一个账单退款需求，原始工单只有一句“支持部分退款”。如果直接进入实现，支付超时后的重试行为会被交给后台 worker 自己猜，结果很容易出现重复退款。把它重写成规格后，团队讨论的重点从“按钮怎么做”变成了“状态如何证明安全”。

重写前：
- 用户可以退款。

重写后：
- Given 退款请求带有 idempotency_key=abc
  When 支付渠道返回超时
  Then worker 记录 status="pending_provider_confirmation"
  And 使用相同 key 重试时返回同一个 refund_id
  And 支持人员不能在第一笔退款待确认时创建第二笔退款

真正有价值的不是文档本身，而是它迫使团队在第一个生产超时发生前，就把重试、幂等和人工支持路径说清楚。

第一小时怎么写，不要想太大

很多团队卡在“我们是不是要建立完整流程”。先别。拿下一个功能，用一小时写一页：目标、非目标、四条验收标准、两个失败路径、一个回滚方法。写完发给会参与实现的人。

One-hour spec:
- Goal: let users retry failed invoice payment
- Non-goals: no new payment provider, no subscription plan changes
- Acceptance: expired card returns card_declined and keeps invoice unpaid
- Edge case: double click creates one payment attempt
- Evidence: API test, ledger assertion, UI banner screenshot
- Rollback: disable retry_payment_v2 flag

边界：Spec-First 不是每件事都写长文。越是高风险、多人协作、AI 参与或用户难以恢复的变更，越值得提前写清楚。

可复制产物：交付评审包

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

交付评审包：什么是 Spec-First 开发？（完整指南）

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

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

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

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

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

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

旗舰使用路径

这是 Spec Coding 用来承接「Spec-First 落地」主题的核心参考页之一。建议把它放到真实工单、PR 或发布评审里使用，而不是只当背景文章阅读。

• 适合从这里开始：团队准备调整计划或 PR 流程，需要先统一 Spec-First 的工作定义。
• 建议复制：交付评审包和退款幂等示例。
• 需要附上的证据：一张真实工单，包含目标、非目标、验收证据和止损责任人。
• 搭配使用：Spec-First 开发 Hub 与 功能规格模板。

旗舰页使用路径：
- 在计划或评审时打开本文。
- 把对应产物复制到工单或 PR。
- 用自己的系统、责任人和失败模式替换示例值。
- 如果证据行仍为空，就不要进入实现。

二次审阅记录：规格要小到能被争论

这次复看时，我重点检查文章有没有把 Spec-First 写成一种可执行习惯，而不是口号。最有价值的例子，是那些会改变实现方式的书面决策：退款幂等、回滚责任、QA 不用追问就能验证的行为。

审阅记录：
- 保留：退款和表单提交示例，因为它们会逼出实现选择。
- 加强：小规格只要暴露一个昂贵歧义，就已经有价值。
- 后续注意：不要把 Spec-First 写成所有小改动都必须走的流程。
- 读者动作：复制一条验收标准到真实工单里，然后问哪位工程师能明确拒绝它。

编辑复核记录

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