OpenSpec-用规格文档重新定义 AI 编程的工作流

Spec-driven Development（SDD，规格驱动开发）是一个被提出很久但一直没能普及的概念。它的核心思路是：先写规格，规格通过工具自动生成测试用例和部分代码框架，开发者在约束好的规格范围内填充实现。这样从一开始，代码和规格就是同源的，不存在对不上的问题。

Fission-AI 开源的 OpenSpec 就在做这件事——专门为 AI Coding Assistant 打造的规格驱动开发框架。GitHub 69,306 颗星，4,748 个 fork，今天新增 298 星，生态相当活跃。它不只是给人用的文档工具，更是一套让 AI Agent 能够理解和遵守项目规格的工作流协议。

OpenSpec 的工作流分为三个核心阶段：

1. 编写 SPEC.md：项目开始前，开发者（或 AI）编写一份结构化的 `SPEC.md` 文档。这份文档不是自由格式的说明文，而是有明确 schema 的规格描述，包括：功能模块列表、每个模块的输入输出、边界条件、错误处理要求、依赖约束等。OpenSpec 提供了一套 TypeScript 类型定义来约束格式，确保规格文档的完整性和可解析性。

2. 自动生成测试套件和脚手架：OpenSpec CLI 读取 `SPEC.md`，根据规格自动生成对应的测试用例（Vitest/Jest 格式）和代码脚手架。这些生成的测试不是空壳，它们覆盖了规格中声明的所有功能点和边界条件。开发者拿到的不只是"可以跑的代码"，而是"已经通过了规格验证的代码"。

3. AI Agent 在规格约束下开发：开发阶段，AI Agent 被要求严格遵守 `SPEC.md` 的约束。所有变更在正式提交前，会被自动对照规格进行检查——如果代码行为和规格不符，CI 会拒绝合并。这从根本上解决了"AI 随意发挥导致行为偏离预期"的问题。

目前大多数 AI Coding Agent 的工作模式是"你说要什么，我就写什么"——缺乏结构化的需求输入环节。你给 Agent 一个模糊的指令，它就按自己的理解去实现，理解错了你就得返工。这是一个不对等的协作关系：人模糊地表达，AI 模糊地执行。

OpenSpec 强制在人和 AI 之间加了一个"对齐"环节：先把需求写成结构化的规格，AI 再基于规格实现，做完以后对照规格自动验证。如果 AI 理解了规格中的某个约束但在实现时忽略了，测试会把它抓出来。

这个模式特别适合几个人协作的场景：产品经理写规格、工程师review规格、AI 基于规格开发，每个人和 AI 都工作在同一个事实来源上。没有规格，大家对"这个功能到底要做什么"可能有十个理解；有了一份规格，理解统一成一个。

OpenSpec 提供了官方 GitHub Actions 集成，`apps/openspec-release-bot` 可以自动监控 PR 中的规格变更，在合并前运行规格验证。对于 Monorepo 项目，OpenSpec 支持多层级规格：顶层有全局架构规格，每个包有自己独立的功能规格，CI 会自动追踪规格之间的依赖关系。

`OpenSpec` 的 Release Bot 还会根据 `SPEC.md` 的变更自动生成 changelog，确保每次发布的变更说明和实际代码行为严格对应。这个功能对于需要频繁发版的开源项目或者需要严格合规的企业项目，节省了大量人工维护 changelog 的成本。

OpenSpec 是 TypeScript 写的，通过 npm 安装：

初始化项目规格：

这会在当前目录生成 `SPEC.md` 模板，开发者根据模板填写规格内容。生成测试和脚手架：

在 GitHub Actions 中集成验证：

对于已经在用 TypeScript 的团队，OpenSpec 的迁移成本很低。它的规格 schema 是渐进式的——你可以先写核心模块的规格，然后再逐步覆盖更多模块——不需要一开始就全面覆盖。

OpenSpec 最大的价值在于"规格和代码的一致性保障"，但它本身不能帮你写出高质量的规格。如果规格本身写错了或者遗漏了重要场景，OpenSpec 会忠实地按规格生成测试，然后生成的测试会忠实地验证错误的实现——garbage in, garbage out 的问题依然存在。所以用 OpenSpec 的前提是团队愿意投入时间写好规格。

对于需求稳定、变更可预期、项目周期长的产品开发，OpenSpec 能带来显著的质量提升。对于探索性很强、需求变化极快的早期项目，规格维护的成本可能超过收益。

AI Coding Agent 时代，OpenSpec 提供了一个有价值的思路：与其让 AI 自由发挥，不如先给它一个精确的约束框架。它不是银弹，但对于愿意在规格上投入的团队，它确实是目前最完整的开源 SDD 方案。