OpenSpec：用 Markdown 规范约束 AI 编码助手，让变更可验证
OpenSpec 构建需求和变更建议，以便编码助理可以根据明确的规范实施和验证工作。
秒懂
- 它是什么？
- OpenSpec 是一个用 TypeScript 编写的开源 CLI，它把需求和变更提案组织成 Markdown 文件，让编码助手在写代码前先读规范、写完后对照验证。本文基于仓库文档分析它的机制、上手方式和适用边界。
- 适合谁用？
- OpenSpec 适合已经受困于 AI 编码助手频繁跑偏的个人开发者，以及需要跨仓库共享需求的中小型团队。它不适合那些需求完全清晰、变更极少、或者团队连 Markdown 工作流都不愿维护的场景。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题：AI 写代码不守承诺
使用 AI 编码助手的人都会遇到同一个问题：你让它加一个暗色模式，它给你改了一堆样式文件，结果主题切换逻辑根本不存在。OpenSpec 的出发点很直接：把需求和验收场景写成显式的 Markdown 文件，让 AI 在动手前先读这些文件，写完后对照场景验证。项目 README 里举了一个例子，用户说“我想要暗色模式但不确定怎么弄干净”，AI 先分析现有样式，提出用 CSS 变量加主题上下文的方案，然后才创建变更提案。这个流程把“想法”和“实现”之间插入了一道人工审查的关卡。它面向两类人：单打独斗的开发者需要约束自己的 AI，团队则需要让多个仓库共享同一份需求来源。
核心机制：提案目录与规范文件
OpenSpec 的工作方式不是靠魔法，而是靠一个固定的目录结构。运行 `/opsx:propose add-dark-mode` 之后，AI 会在 `openspec/changes/add-dark-mode/` 下生成四个文件：`proposal.md` 说明为什么做和做什么，`specs/` 放需求和场景，`design.md` 写技术方案，`tasks.md` 是实施清单。规格文件用纯 Markdown 书写，不需要学习特殊语法。README 展示了一个需求示例：一个以 `## ADDED Requirements` 开头的段落，下面用 `SHALL` 描述必须行为，再用 `WHEN...THEN...` 写出具体场景。这种格式的好处是任何人都能读懂，坏处是它依赖 AI 正确理解自然语言的约束，如果 AI 生成的场景写得含糊，验证环节就会形同虚设。
安装与启动：一条命令，但环境有门槛
安装过程很简单，前提是你的 Node.js 版本不低于 20.19.0。全局安装命令是 `npm install -g @fission-ai/openspec@latest`，然后进入项目目录执行 `openspec init`。初始化后，默认配置只包含两个命令：`/opsx:explore` 用于探索想法，`/opsx:propose` 用于直接创建提案。如果你想要更完整的流程，比如 `/opsx:verify` 验证实现、`/opsx:ff` 标记完成、`/opsx:bulk-archive` 批量归档，需要用 `openspec config profile` 切换配置，再运行 `openspec update` 应用。这里有一个值得注意的细节：命令的拼写随工具变化，在 Cursor 里是 `/opsx-propose`，在 Codex 里是 `$openspec-propose`。`openspec init` 会根据你选择的工具打印正确的形式。这意味着你不需要记不同工具的语法，但前提是 OpenSpec 确实支持你的编辑器。README 声称支持 30 多个工具，但具体列表在文档里，你需要自己确认。
Stores 模式：把规划搬进独立仓库
OpenSpec 不满足于单仓库的规划。它提出了一个叫 Stores 的 beta 功能，思路是把 `openspec/` 目录（specs 和 changes）放进一个独立的 Git 仓库，通过 `git push` 共享给整个团队和所有编码助手。这解决了一个真实的问题：一个功能横跨 API 服务、Web 应用和共享库，需求由平台团队维护，产品团队只是引用。在传统方式下，需求散落在多个仓库的 issue 和文档里，AI 助手读不到完整上下文。Stores 让平台团队拥有 specs，产品团队以只读方式引用，编码助手在各自的代码仓库里就能读到同一份需求。这个设计听起来合理，但它处于 beta 阶段，README 明确要求先读 [Stores User Guide](docs/stores-beta/user-guide.md)。如果你在评估是否采用，这个 beta 状态本身就是一个风险点。
局限性：规范是纸，验证是火
OpenSpec 最大的局限在于它无法保证 AI 真的遵守规范。它提供的是文件结构和命令流程，而不是一个执行引擎。`/opsx:verify` 命令存在，但 README 没有说明它具体如何验证实现，是检查代码中是否存在对应函数，还是运行测试，这从仓库材料里无法确认。另一个问题是流程的强制性。如果你跳过人工审查，直接让 AI 生成提案并开始写代码，那么 OpenSpec 就退化成了一堆 Markdown 模板，反而增加了维护负担。还有一点，它要求 Node.js 20.19.0 以上，这对某些使用旧版本 LTS 的企业环境是一个硬门槛。最后，OpenSpec 的设计哲学强调“fluid not rigid”，但规范文件本身需要维护，当需求频繁变化时，更新 specs 的成本可能超过它带来的收益。
替代方案：ADRs 和测试用例驱动
如果你不想引入一个新的 CLI 和目录结构，最接近的替代方案是架构决策记录（ADR）。ADR 把每个重要决策写成一个独立的 Markdown 文件，记录背景、决策和后果。它与 OpenSpec 的 `proposal.md` 类似，但 ADR 不包含可验证的场景，也不与编码助手集成。另一个方向是测试用例驱动开发：先把验收测试写成代码，再让 AI 实现功能直到测试通过。这种方式比 OpenSpec 更严格，因为测试是机器可执行的，但它的缺点是需求必须能被编码成测试，对于 UI 交互或产品决策这类模糊需求，测试用例难以覆盖。OpenSpec 的定位介于两者之间：它用自然语言场景保持灵活性，用目录结构强制流程，但放弃了机器可验证性。如果你的团队已经有成熟的测试文化，OpenSpec 可能显得多余；如果完全没有测试，它也不能替代测试。
维护成本与许可证
OpenSpec 采用 MIT 许可证，这意味着你可以自由使用、修改和分发，甚至集成到商业产品中。但许可证不附带任何保证，你需要在项目中自行决定是否引入。维护成本方面，OpenSpec 的发布节奏看起来很快，v1.9.0 到 v1.11.0 间隔不到两周，这带来两个影响：功能迭代快，但升级频率也高。你需要定期运行 `npm update -g @fission-ai/openspec` 来跟进变化，而每次升级都可能改变命令行为或配置文件格式。README 提到 v1.11.0 引入了“Spec Diffs & Batch Status”，v1.9.0 增加了“Command Code & safer specs”，说明项目仍在快速演进，API 稳定性尚未固化。如果你在一个长期维护的项目中使用它，需要把版本升级纳入常规维护计划。另外，项目自称“built with OpenSpec”，意味着它的内部开发也使用这套流程，这算是一个自举的证明，但并不能保证你的场景一定顺利。
编辑结论
OpenSpec 适合已经受困于 AI 编码助手频繁跑偏的个人开发者，以及需要跨仓库共享需求的中小型团队。它不适合那些需求完全清晰、变更极少、或者团队连 Markdown 工作流都不愿维护的场景。如果你决定尝试，先验证三点：你的 Node.js 版本是否高于 20.19.0，你的编码助手是否在支持的 30 多个工具列表中，以及你是否愿意接受每次提案都要人工审查 specs 目录下的文件。OpenSpec 的价值建立在“先写规范再写代码”的纪律上，没有这个纪律，它只是一个额外的目录结构。
社区笔记