什么是 Spec-First 开发？（完整指南）
如果你想先建立整体方法论，这篇会把定义、适用场景、优缺点和真实团队收益讲清楚。
阅读完整导览
Spec-First 文章库
Spec Coding 博客
面向工程落地的 Spec-First 系列长文。每篇都围绕“如何写出可测试、可评审、可交付的规格”，直接解决规格、联调、验收和上线中的真实问题。
72 篇覆盖规格写作、API 契约、流程治理、案例复盘与模板资源
7 个主题按基础概念、写作、接口、流程、案例、资源和 AI 编程组织
4 篇 / 页分页阅读，避免长列表压迫感
按学习路径进入
不要从完整列表里硬找。先选当前要解决的问题：理解方法、写出规格、保护接口与数据，或约束 AI 编码输出。
先理解方法，再改团队流程
从完整指南开始，再看 Spec-First 与敏捷的关系，最后用 30 天计划判断团队该怎么试点。
进入基础路径主题 Hub
如果你不想一篇篇扫文章，可以从主题 Hub 进入。每个 Hub 都提供决策表、可复制片段和下一步文章。
Spec-First 开发主题 Hub
从方法、关键决策、评审门禁和证据习惯开始。
打开 HubAPI 契约主题 Hub
用于 schema diff、兼容性、版本策略、Webhook 和废弃计划。
打开 Hub验收标准主题 Hub
把成功描述改成可测试标准，补上失败路径和证据。
打开 HubAI 编码治理主题 Hub
连接提示词、风险登记、验收映射和测试证据。
打开 Hub全部文章
先按标签筛，再进入分页。这样比一次性扫完整个列表更容易找到适合当前项目阶段的内容。
1. AI 编码前的规格包：先给边界，再让它写代码
围绕「AI 编码前的规格包：先给边界，再让它写代码」展开，说明可测试输入、预期结果、边界条件和评审标准，帮助 QA 与开发提前对齐，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章2. 同一个退款功能，Vibe Coding 和 Spec Coding 的结局截然不同
同一个订单退款功能，分别用 vibe coding 和 spec coding 两种方式实现。前者 10 分钟出活却花两周修 bug，后者 90 分钟写 spec 后零线上事故。完整对比。
阅读文章3. 验收标准示例——20 个可直接复制的真实模板
网上大多数验收标准示例都太浅，没法直接用到实际项目中。本文给你 20 个生产级的真实示例，覆盖认证、电商、API、数据处理和通知五大领域——全部采用 Given/When/Then 格式，可以直接复制到你的规格文档里。
阅读文章4. 如何编写技术规格——模板、示例与免费生成器
技术规格（spec）是软件工程中最被低估的工具。这篇文章带你逐一拆解 spec 的每个部分，展示一份完整的真实案例，并给你一个可以直接复制使用的模板——还有一个免费的在线生成器。
阅读文章5. 为 API 服务搭建测试 Harness
写测试和搭建测试 Harness 是两种截然不同的工程工作。测试验证行为，而 Harness 是让这些测试在成百上千次运行、数十位工程师协作中保持确定性、快速且可维护的基础设施。
阅读文章6. Superpowers：一个用规格驱动 AI 编码智能体的开源技能框架
Superpowers 是一个开源框架，为 AI 编码智能体强制执行 Spec-First 纪律。了解其强制流水线——头脑风暴、规格、计划、TDD、验证——如何在 AI 辅助工程时代验证规格驱动开发的价值。
阅读文章7. 规格评审反模式：何时跳过规格、哪些内容不该写进规格
今年我观察了三个采用 Spec-First 开发的团队。其中两个在六周内就精疲力竭了。不是因为这个实践本身有问题，而是因为他们给所有改动都写了规格。改两行配置？写规格。一个已经定位到的 Bug？写规格。凌晨两点的紧急修复？
阅读文章8. Spec-First 功能开关：开关逻辑、金丝雀发布与暗发布
功能开关一开始是受控灰度发布的手段，最终却变成了没人敢删的永久性基础设施。这两个状态之间的鸿沟，几乎总是因为缺少规格。当一个开关在创建时没有记录谁能看到它、什么条件下全量发布、什么时候删除，这个开关就变成了一个从未真正完成的决策。
阅读文章9. 向后兼容规格：如何规划废弃路径与破坏性变更
你在周五下午发布了 API 的新版本。到周一早上，三个下游团队已经提交了故障工单，因为他们的集成全部崩溃了。他们依赖的字段被重命名了，一个枚举新增了一个值但他们的 switch 语句没有 default 分支，一个之前返回 null 的
阅读文章10. Harness Engineering 与 Spec-First 的区别
这两套实践都是为了让问题在进入生产环境之前被发现。Harness engineering 构建运行和验证代码的基础设施；spec-first 则在你动笔写代码之前就定义什么叫“正确”。
阅读文章11. 如何在编写迁移之前先规格化数据库模式
迁移文件是永久性的。一旦它在生产环境中运行，你无法撤销它，只能再写一个迁移来修正。然而大多数团队写迁移的方式和写应用代码一样：打开编辑器，开始敲列定义，约束条件边写边想。
阅读文章12. 如何编写遵守规格的 AI 编程提示词
为什么 AI 编程工具会加上你根本没要求的校验逻辑，把下游还有消费者的字段随手重命名，还生成一堆超出任务范围的辅助函数？因为你丢给它的是一个"要解决的问题"，而不是一份"要遵守的 spec"。
阅读文章13. AI 编码治理：用规格驱动的 Prompt 设立边界
用 spec-driven prompts 治理 AI 辅助编程：提示词必须包含什么、AI 必须遵守哪些边界，以及让“这是 AI 写的”变成可核验声明的审计链。
阅读文章14. AI 编码 PR 评审：用验收标准衡量通过与否
围绕「AI 编码 PR 评审：用验收标准衡量通过与否」展开，说明可测试输入、预期结果、边界条件和评审标准，帮助 QA 与开发提前对齐，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章15. AI 编码合并前风险登记：merge 之前要追踪的条目
围绕「AI 编码合并前风险登记：merge 之前要追踪的条目」展开，说明如何用规格约束 AI 编码、保留人工评审点，并用证据判断实现是否达标，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章16. AI 编码的测试证据门禁：为什么通过用例还不够
AI 写出的代码读起来都像能跑。有时候它甚至能通过自己写的那套测试。我现在的规矩是：不信代码，不信测试，只信"这些测试真的能抓住真实 bug"的证据。下面讲的，就是我在合并前如何把这份证据落成具体文件。
阅读文章17. AI 生成客户端下的 API 变更治理
上个季度打到我 API 上的集成，有一半是那种从来没读过我文档的人写出来的。开发者在 Cursor 里敲一句含糊的提示词，Claude 或 Copilot 给什么就接什么，接完就上线。
阅读文章18. AI 集成场景下的 API 错误分类体系
怎样设计一份 AI 生成的客户端真正用得上的 API 错误分类：稳定的 error code、机器可读的 category，以及区分可重试失败和永久失败的关键字段。
阅读文章19. API Schema Diff 上线前评审实战
上线前如何做 API schema diff 评审：自动化 diff 工具能抓到什么、漏掉什么，以及 OpenAPI 和 GraphQL 仍然需要人工检查的那些点。
阅读文章20. 契约优先的 SDK 生成与人工评审流程
围绕「契约优先的 SDK 生成与人工评审流程」展开，说明契约字段、兼容边界、失败路径和评审检查点，帮助团队在上线前减少集成风险，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章21. 为 Agentic 客户端设计 API 规格
围绕「为 Agentic 客户端设计 API 规格」展开，说明契约字段、兼容边界、失败路径和评审检查点，帮助团队在上线前减少集成风险，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章22. AI 编写迁移脚本的评审清单
每一份 AI 写出来的数据库迁移脚本合并前都必须过的评审清单：锁行为、回滚验证、批量大小是否合理、以及在生产级数据量上的 dry-run。我不会合并任何跳过这些关卡的迁移脚本，你也不应该合并。
阅读文章23. 用 Spec Skills 做 Bug 分流与事故记录
凌晨 3:04，PagerDuty 在嗡嗡作响。一条工单写着"登录很慢，客户在投诉"，没有别的任何信息。当晚 on-call 只有我一个人。
阅读文章24. Spec Skills 案例：从工单到规格的完整链路
围绕「Spec Skills 案例：从工单到规格的完整链路」展开，说明如何用规格约束 AI 编码、保留人工评审点，并用证据判断实现是否达标，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章25. Spec Skills 与 Spec-First 交付：实际如何结合
大多数 AI 编码工具都在为一个目标做优化：让东西在未来十分钟内跑起来。Spec Skills 优化的是另一件事——确保生成出来的代码，就是你当初真正要的那个东西。
阅读文章26. 用 Spec Skills 起草验收标准（AC）
围绕「用 Spec Skills 起草验收标准（AC）」展开，说明可测试输入、预期结果、边界条件和评审标准，帮助 QA 与开发提前对齐，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章27. 面向产品团队的 Spec Skills Prompt 库
我看过三个产品团队试图用 Slack、Notion 和一份勇气可嘉的 Google Doc 来管理 Spec Skills 的 prompt。没有一种撑过一个季度。prompt library 是基础设施，不是剪贴簿。下面是我自己的做法。
阅读文章28. Spec Skills Prompt 模式：规格工作流提示模板
一份 Spec Skills prompt 模式清单，覆盖规格草稿、AC 生成、评审辅助和风险登记簿挖掘这些常见规格工作流，以及我实际在用的 prompt 形态。
阅读文章29. Spec Skills 与通用 AI 编码工具的差异
在同一个季度里，我用过自动补全、对话式 IDE，也用过 Spec Skills 的 spec-first 工作流把代码交付上线。它们并不像大多数对比文章假装的那样彼此竞争。
阅读文章30. 开发团队的 Spec Skills 工作区搭建指南
我到现在已经给三个不同的开发团队搭过 Spec Skills 工作区，结论是：几乎每次落地的成败都卡在工作区布局上。工具本身没什么问题，真正的产品其实是文件系统。
阅读文章31. 结构化提示生成验收标准的实战方法
围绕「结构化提示生成验收标准的实战方法」展开，说明可测试输入、预期结果、边界条件和评审标准，帮助 QA 与开发提前对齐，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章32. 用 Spec Skills 做 API 契约评审
过去八个月我一直用 Spec Skills 做 API 契约评审，真正让我决定把它留在流程里的，是一个近乎让人脸红的案例。某个 diff 工具顺顺当当地批准了一份 PR，而那次变更里，一个错误码的语义已经被悄悄改掉了。
阅读文章33. API 废弃计划：写进契约里的兼容通知
如何从第一天起就把废弃计划写进 API 契约：Sunset 响应头、废弃时间线、客户沟通节奏，以及真正关键的用量上报步骤。如果一个接口上线时连"怎么死"都没写清楚，那它的设计就还没完成。
阅读文章34. 平台结算规格：对账与争议处理
我见过太多 marketplace 平台在结算系统里悄悄流血，根因永远是同一个：规格把 payout 当成报表问题，而不是会计问题。如果你的书面规格在第一页没有强制要求复式记账 ledger，那文档后面写的东西全都是装饰。
阅读文章35. 移动端推送偏好规格：类目模型与频控规则
推送偏好看上去只是一个设置页，实际却是一个分布式系统。我见过太多团队先上了一个"消息通知"总开关，然后在接下来两年里反复排查：为什么一条安全告警会和一条营销推送一起被静掉。这篇就是我希望那些团队在第 1 天就写下的规格。
阅读文章36. 合作方 API 接入规格清单
我见过的每一场翻车的合作方 API 接入，都有同一个前兆：平台团队只为 happy path 写了规格，其他情况全靠挥手糊弄。下面这份清单，是我现在要求第三方触碰生产流量之前必须先过的关，全部站在平台这一侧的契约视角来写。
阅读文章37. AI 辅助开发下的规格质量门禁
围绕「AI 辅助开发下的规格质量门禁」展开，说明如何用规格约束 AI 编码、保留人工评审点，并用证据判断实现是否达标，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章38. 实时协作规格：冲突解决策略
围绕「实时协作规格：冲突解决策略」展开，说明规格边界、评审问题、示例写法和落地检查，帮助团队在实现前统一行为预期，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章39. 规格驱动的前后端对齐
我排查过的每一起前后端不对齐事故,根源都指向同一件事:两拨人各自按对一次对话的不同理解去实现,而不是按同一份书面契约。Spec-first 就是用来终结这种模式的,它比任何紧急集成会都便宜。
阅读文章40. 订阅变更规格：分摊计费与续费边界条件
我上线过的每一个订阅 bug，都藏在"用户想换套餐"和"账单系统认账"这两件事中间的那道缝里。代码从来不是难点，规格才是。
阅读文章41. 向后兼容的 API 变更规格写法
我发布过自以为是加法、实际却破坏了兼容的 API 变更。规格看起来没问题，schema diff 看起来也很小，真正捅出篓子的是一条我从没写下来的规则。下面就是我现在要求每一份 API 变更规格都必须写清楚、否则不签字的清单。
阅读文章42. 计费对账规格：容差机制与异常升级
我上线过两套对账系统，又接手过四套。一句话总结：如果你的内部账本跟自己都对不上零，那就是 bug，不是四舍五入问题。容差是留给外部世界的，因为处理商和银行有自己的凑整节奏。规格存在的意义，就是把这条线划清楚，并且在审计压力下稳住。
阅读文章43. 契约测试计划：从 OpenAPI 到 CI
围绕「契约测试计划：从 OpenAPI 到 CI」展开，说明契约字段、兼容边界、失败路径和评审检查点，帮助团队在上线前减少集成风险，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章44. 跨服务数据同步规格：一致性设计与取舍
我见过的每一份失败的跨服务同步规格都长得一个样：它把 happy path 写完就算交差。真正出事的地方，永远是作者没想到要写下来的那些——顺序、迟到事件、部分失败，以及上线第二天需要回填时到底要怎么办。
阅读文章45. 数据库迁移规则写进技术规格：变更与回滚策略
我见过的大多数生产事故，都来自那种评审时看着挺合理、却在周二下午两点把数据库干崩的迁移。解决办法是一份技术规格，它强制你在写下第一条 ALTER TABLE 之前，就对扩展-收缩、回滚、部署顺序这些问题给出具体答案。
阅读文章46. 用规格设计幂等工作流
幂等性就是那种在规格里看起来只值一行字、一旦写错就能吞掉你一整周调试时间的特性。下面是我写"幂等性"章节的方式——让重试、崩溃、用户连点两下在生产环境里全都表现出同一种行为。
阅读文章47. 事件驱动系统的规格模式：契约与消费语义
事件驱动系统的规格范式：事件 schema 版本化、command 与 fact 事件的区分、choreography 与 orchestration 的取舍、幂等处理器，以及最终一致性边界的明确表达。
阅读文章48. 如何在技术规格中定义非目标
项目能否按时交付，最大的预测指标不是目标清单——而是非目标清单。写了明确非目标的团队，大致能按计划完成。没写的团队，往往在三周后还在争论某件事到底算不算在范围内。我见过的每一个延期的项目，非目标章节要么缺失，要么就只有孤零零一行字。
阅读文章49. 移动端离线模式 API 规格：同步与冲突解决
围绕「移动端离线模式 API 规格：同步与冲突解决」展开，说明契约字段、兼容边界、失败路径和评审检查点，帮助团队在上线前减少集成风险，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章50. 通知系统规格：送达语义与重试策略
围绕「通知系统规格：送达语义与重试策略」展开，说明规格边界、评审问题、示例写法和落地检查，帮助团队在实现前统一行为预期，可直接用于规格评审、实现前对齐和测试计划补充。
阅读文章51. 支付链路规格：失败场景与重试矩阵
我评审过的大多数支付规格，都用三页篇幅描写 happy path，再用一句话描写失败行为：“出错时重试”。生产环境里 80% 的事故，就是从这一句话里冒出来的。
阅读文章52. 队列处理规格：Exactly-Once 与 At-Least-Once 的取舍
只要团队里有人说出"exactly-once 队列"这几个字，我就会把话题叫停。这是一句营销话术，不是投递保证，按它写出来的规格一定会埋下那种凌晨三点才会炸的 Bug。
阅读文章53. 高风险发布的上线与回滚设计
一个团队的工程成熟度，最能看出来的时刻不是 code review，而是他们怎么描述凌晨三点出事之后的应对流程。大多数上线计划死在"我们会密切监控"这句话上——这话从来没救过谁。
阅读文章54. API 的 Spec-First 错误处理模式
错误处理是 API 规格里最容易被含糊带过的一块。所有人都同意它很重要，但没人把它写下来，然后到了联调那一周，团队就开始争论超时到底该是 500 还是 503、客户端该不该重试。
阅读文章55. API 契约版本控制策略
对比 URL 版本控制、请求头版本控制、基于日期的版本控制与 evolution-only。如何为 API 挑选合适的版本控制策略，以及规格文档必须就弃用时间线说清楚什么。
阅读文章56. Webhook 消费者规格：签名、重试与顺序
我评审过的绝大多数 webhook 消费端规格，覆盖的内容只有一个端点、几乎别无其他：URL、JSON 结构，再加一句含糊其辞的“校验签名”。那不是规格。
阅读文章57. 编写 QA 可以实际测试的边界条件
"合理处理边界情况。"我几乎每周都能在 spec 里看到这句话。它什么都没说。QA 没法测试"合理"——他们需要具体的输入、具体的触发条件、具体的预期结果。下面是我写边界情况的方式，让 QA 不用追问一句就能把它们变成测试用例。
阅读文章58. 事后复盘：用 Spec-First 预防计费事故
这是一次 postmortem 式的复盘：一个 bug 上线，不是因为代码写错了，而是因为我们的规格从头到尾没有交代 proration。下面是事故经过、那句本该被写下却没写下的描述，以及我们事后补上的章节。
阅读文章59. 软件规格中的 10 个常见错误
我评审过的每一个失败项目都有 spec。问题是 spec 里没写真正重要的那些事。下面这十个错误在我评审过的 spec 里反复出现——我自己写的也不例外。它们都不难修，但在截止日期的压力下，每一个都容易被漏掉。
阅读文章60. 如何在团队中推行 Spec-First（30 天计划）
在团队里推 Spec-First，本质上是个组织问题，不是技术问题。模板是最容易做的事，难的是养成习惯。如果你是那个想说服团队开始写规格的人，你大部分精力都会花在证明"它能省时间"上，而不是教大家怎么写。
阅读文章61. 如何编写可测试的软件规格
"可测试"的规格并不是用某种特殊语言写成的规格。它是一份每一条声明都能由未参与撰写的人来核验的规格。这个门槛听起来不高，其实不然。我审阅过的大多数规格在第一轮就过不了这关——包括我自己写的。
阅读文章62. PRD 与技术规格的区别
把 PRD 和技术规格混为一谈的团队，最后写出来的文档两头不讨好。PRD 是一份给人看的产品文档，用来判断一件事 值不值得做 。技术规格是一份给人看的工程文档，用来决定 怎么做 以及 到底做成什么样 。
阅读文章63. Spec-First 与敏捷：冲突还是互补？
几乎每次我向团队介绍 spec-first 时，都会听到这个问题：「这不就是套了连帽衫的瀑布模型吗？」简短答案是否定的——spec-first 和敏捷根本不在系统的同一层。
阅读文章64. 编码前的规格评审清单
大多数规格评审只是走过场。三个人扫一眼文档，有人写一句"LGTM"，然后所有人带着同样的模糊地带继续往前走。真正的规格评审，会抓住那些一周之后会让你付出代价的东西。下面这份清单，是我在放任何规格通过评审之前都会过一遍的。
阅读文章65. 什么是 Spec-First 开发？（完整指南）
一个团队如果交付很快但不断返工，并不是在跑得更快——而是在烧跑道。问题几乎总是一样的：没人在编码之前写清楚"完成"是什么意思。Spec-First 开发解决这个问题——在实现之前定义验收标准，而不是之后。
阅读文章66. 如何高效开展技术设计评审
设计评审是工程团队中杠杆效率最高的会议，但大多数都失败了。失败的原因是没有书面产物可供评审、参会人员不对、也没有人在发日历邀请之前定义成功的结果是什么。
阅读文章67. 架构决策记录：记录“为什么”，而不仅仅是“做了什么”
半年后，团队里某人会盯着代码库问："为什么我们选了 Kafka 而不是 SQS？"或者"为什么这是一个独立服务而不是一个模块？"如果答案只存在于当初做决定那个人的脑子里，而那个人已经换组甚至离职了，这个问题就变得无解。
阅读文章68. 如何写出真正能防止复发的事后复盘
12 年来，我写过或参与过大约 40 份事后复盘。大多数都失败了。不是那种轰轰烈烈的失败——只是没能防止下一次事故。行动项模糊，没人认领，六周之内大家就把它忘了。
阅读文章69. 技术债务：如何度量、排优先级并逐步偿还
每个团队都在谈技术债务，但几乎没有团队能说清楚自己到底欠了多少、每个迭代要为此付出多少代价、或者应该先还哪笔债。这个词已经变成了"我不喜欢的代码"的代名词——既无法排优先级，也很容易被管理层忽视。
阅读文章70. 真正提升代码质量的代码评审实践
大多数代码评审并不能提升代码质量。它们确认代码能编译，抓住一两个命名不一致，几分钟内就被批准了。我见过很多团队做了成百上千次这样的评审，然后疑惑为什么同类 bug 总是反复出现在生产环境中。
阅读文章71. 复盘：缺失契约测试如何让破坏性变更进入生产环境
Provider 团队在一次清理 PR 中重命名了一个 JSON 字段。OpenAPI 规格已同步更新。Provider 端所有测试均通过。两个服务之间不存在契约测试。
阅读文章72. 将规格与测试 Harness 连接起来：一套实用工作流
如何将 Spec-First 验收标准转化为测试 Harness 中可执行的测试用例。涵盖 Given/When/Then 到 fixture/action/assertion 的映射、QA 介入时机以及规格覆盖率追踪。
阅读文章静态分页 · 第 1/18 页 · 72 篇文章