AI Agent 团队的 Spec-First 工作流
为运行 AI 编码 agent 的团队设计的五阶段 spec-first 工作流：规格包、任务边界、写入范围、证据门禁和可扩展的 PR 评审。
Spec-First 文章库
Spec Coding 博客
面向工程落地的 Spec-First 系列长文。每篇都围绕“如何写出可测试、可评审、可交付的规格”，直接解决规格、联调、验收和上线中的真实问题。
编辑说明
第一次来建议先读《什么是 Spec-First 开发》——API 契约、验收标准和案例复盘都建立在它之上。我们只在文章通过自己的评审门禁后才发布，不为更新而更新。
全部文章
先按标签筛。优先打开和当前交付风险最接近的文章，每篇文末都有相关阅读路径。
写给 AI Agent 的 MCP Server API 契约
为 MCP server 编写 API 规格契约：输入 schema、输出结构、错误分类、幂等标记和版本策略，让 AI agent 客户端可以可靠调用。
OpenSpec vs Superpowers vs Spec Kit：SDD 实践模式
对比 OpenSpec vs Superpowers vs GitHub Spec Kit，总结 SDD 中可复用的规格、计划、任务、测试、评审和证据模式。
AI 编码前的规格包：先给边界，再让它写代码
围绕「AI 编码前的规格包：先给边界，再让它写代码」展开，说明可测试输入、预期结果、边界条件和评审标准，帮助 QA 与开发提前对齐，可直接用于规格评审、实现前对齐和测试计划补充。
Spec Skills 案例：从工单到规格的完整链路
围绕「Spec Skills 案例：从工单到规格的完整链路」展开，说明如何用规格约束 AI 编码、保留人工评审点，并用证据判断实现是否达标，可直接用于规格评审、实现前对齐和测试计划补充。
Spec Skills 与 Spec-First 交付：实际如何结合
大多数 AI 编码工具都在为一个目标做优化：让东西在未来十分钟内跑起来。Spec Skills 优化的是另一件事——确保生成出来的代码，就是你当初真正要的那个东西。
同一个退款功能，Vibe Coding 和 Spec Coding 的结局截然不同
同一个订单退款功能，分别用 vibe coding 和 spec coding 两种方式实现。前者 10 分钟出活却花两周修 bug，后者 90 分钟写 spec 后零线上事故。完整对比。
验收标准示例——20 个可直接复制的真实模板
网上大多数验收标准示例都太浅，没法直接用到实际项目中。本文给你 20 个生产级的真实示例，覆盖认证、电商、API、数据处理和通知五大领域——全部采用 Given/When/Then 格式，可以直接复制到你的规格文档里。
如何编写技术规格——模板、示例与免费生成器
技术规格（spec）是软件工程中最被低估的工具。这篇文章带你逐一拆解 spec 的每个部分，展示一份完整的真实案例，并给你一个可以直接复制使用的模板——还有一个免费的在线生成器。
Superpowers：一个用规格驱动 AI 编码智能体的开源技能框架
Superpowers 是一个开源框架，为 AI 编码智能体强制执行 Spec-First 纪律。了解其强制流水线——头脑风暴、规格、计划、TDD、验证——如何在 AI 辅助工程时代验证规格驱动开发的价值。
如何在编写迁移之前先规格化数据库模式
迁移文件是永久性的。一旦它在生产环境中运行，你无法撤销它，只能再写一个迁移来修正。然而大多数团队写迁移的方式和写应用代码一样：打开编辑器，开始敲列定义，约束条件边写边想。
如何编写遵守规格的 AI 编程提示词
为什么 AI 编程工具会加上你根本没要求的校验逻辑，把下游还有消费者的字段随手重命名，还生成一堆超出任务范围的辅助函数？因为你丢给它的是一个"要解决的问题"，而不是一份"要遵守的 spec"。
AI 编码治理：用规格驱动的 Prompt 设立边界
用 spec-driven prompts 治理 AI 辅助编程：提示词必须包含什么、AI 必须遵守哪些边界，以及让“这是 AI 写的”变成可核验声明的审计链。
AI 编码 PR 评审：用验收标准衡量通过与否
围绕「AI 编码 PR 评审：用验收标准衡量通过与否」展开，说明可测试输入、预期结果、边界条件和评审标准，帮助 QA 与开发提前对齐，可直接用于规格评审、实现前对齐和测试计划补充。
AI 编码合并前风险登记：merge 之前要追踪的条目
围绕「AI 编码合并前风险登记：merge 之前要追踪的条目」展开，说明如何用规格约束 AI 编码、保留人工评审点，并用证据判断实现是否达标，可直接用于规格评审、实现前对齐和测试计划补充。
AI 编码的测试证据门禁：为什么通过用例还不够
AI 写出的代码读起来都像能跑。有时候它甚至能通过自己写的那套测试。我现在的规矩是：不信代码，不信测试，只信"这些测试真的能抓住真实 bug"的证据。下面讲的，就是我在合并前如何把这份证据落成具体文件。
为 Agentic 客户端设计 API 规格
围绕「为 Agentic 客户端设计 API 规格」展开，说明契约字段、兼容边界、失败路径和评审检查点，帮助团队在上线前减少集成风险，可直接用于规格评审、实现前对齐和测试计划补充。
契约测试计划：从 OpenAPI 到 CI
围绕「契约测试计划：从 OpenAPI 到 CI」展开，说明契约字段、兼容边界、失败路径和评审检查点，帮助团队在上线前减少集成风险，可直接用于规格评审、实现前对齐和测试计划补充。
事件驱动系统的规格模式：契约与消费语义
事件驱动系统的规格范式：事件 schema 版本化、command 与 fact 事件的区分、choreography 与 orchestration 的取舍、幂等处理器，以及最终一致性边界的明确表达。
如何在技术规格中定义非目标
项目能否按时交付，最大的预测指标不是目标清单——而是非目标清单。写了明确非目标的团队，大致能按计划完成。没写的团队，往往在三周后还在争论某件事到底算不算在范围内。我见过的每一个延期的项目，非目标章节要么缺失，要么就只有孤零零一行字。
支付链路规格：失败场景与重试矩阵
我评审过的大多数支付规格，都用三页篇幅描写 happy path，再用一句话描写失败行为：“出错时重试”。生产环境里 80% 的事故，就是从这一句话里冒出来的。
高风险发布的上线与回滚设计
一个团队的工程成熟度，最能看出来的时刻不是 code review，而是他们怎么描述凌晨三点出事之后的应对流程。大多数上线计划死在"我们会密切监控"这句话上——这话从来没救过谁。
编写 QA 可以实际测试的边界条件
"合理处理边界情况。"我几乎每周都能在 spec 里看到这句话。它什么都没说。QA 没法测试"合理"——他们需要具体的输入、具体的触发条件、具体的预期结果。下面是我写边界情况的方式，让 QA 不用追问一句就能把它们变成测试用例。
软件规格中的 10 个常见错误
我评审过的每一个失败项目都有 spec。问题是 spec 里没写真正重要的那些事。下面这十个错误在我评审过的 spec 里反复出现——我自己写的也不例外。它们都不难修，但在截止日期的压力下，每一个都容易被漏掉。
如何在团队中推行 Spec-First（30 天计划）
在团队里推 Spec-First，本质上是个组织问题，不是技术问题。模板是最容易做的事，难的是养成习惯。如果你是那个想说服团队开始写规格的人，你大部分精力都会花在证明"它能省时间"上，而不是教大家怎么写。
如何编写可测试的软件规格
"可测试"的规格并不是用某种特殊语言写成的规格。它是一份每一条声明都能由未参与撰写的人来核验的规格。这个门槛听起来不高，其实不然。我审阅过的大多数规格在第一轮就过不了这关——包括我自己写的。
PRD 与技术规格的区别
把 PRD 和技术规格混为一谈的团队，最后写出来的文档两头不讨好。PRD 是一份给人看的产品文档，用来判断一件事 值不值得做 。技术规格是一份给人看的工程文档，用来决定 怎么做 以及 到底做成什么样 。
AI 辅助开发下的规格质量门禁
围绕「AI 辅助开发下的规格质量门禁」展开，说明如何用规格约束 AI 编码、保留人工评审点，并用证据判断实现是否达标，可直接用于规格评审、实现前对齐和测试计划补充。
编码前的规格评审清单
大多数规格评审只是走过场。三个人扫一眼文档，有人写一句"LGTM"，然后所有人带着同样的模糊地带继续往前走。真正的规格评审，会抓住那些一周之后会让你付出代价的东西。下面这份清单，是我在放任何规格通过评审之前都会过一遍的。
什么是 Spec-First 开发？（完整指南）
一个团队如果交付很快但不断返工，并不是在跑得更快——而是在烧跑道。问题几乎总是一样的：没人在编码之前写清楚"完成"是什么意思。Spec-First 开发解决这个问题——在实现之前定义验收标准，而不是之后。
静态分页 · 第 1/3 页 · 30 篇文章
什么是 Spec-First 开发？（完整指南）
如果你想先建立整体方法论，这篇会把定义、适用场景、优缺点和真实团队收益讲清楚。
阅读完整导览按学习路径进入
不要从完整列表里硬找。先选当前要解决的问题：理解方法、写出规格、保护接口与数据，或约束 AI 编码输出。
先理解方法，再改团队流程
从完整指南开始，再看 Spec-First 与敏捷的关系，最后用 30 天计划判断团队该怎么试点。
进入基础路径主题 Hub
如果你不想一篇篇扫文章，可以从主题 Hub 进入。每个 Hub 都提供决策表、可复制片段和下一步文章。
Spec-First 开发主题 Hub
从方法、关键决策、评审门禁和证据习惯开始。
打开 HubAPI 契约主题 Hub
用于 schema diff、兼容性、版本策略、Webhook 和废弃计划。
打开 Hub验收标准主题 Hub
把成功描述改成可测试标准，补上失败路径和证据。
打开 HubAI 编码治理主题 Hub
连接提示词、风险登记、验收映射和测试证据。
打开 Hub