HN Weekly 中文
← #811

OpenSpec：一个轻量、可配置的 AI 规格框架

查看原文 HN 讨论

文章摘要

OpenSpec 是 Fission-AI 开发的开源（MIT）”规格驱动开发”（Spec-Driven Development，SDD）框架，官网口号是”构建正确的东西，并正确地构建它”。官网内容不多，主要是一堆采用数据：GitHub 6.8 万星、每两秒就有人用它创建一份新规格、每月超过 26.5 万开发者使用，当前版本 v1.13.0。它通过 npm install -g @fission-ai/openspec 安装（也支持 Homebrew、pnpm、bun、yarn、Nix），官网列出兼容 Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI、OpenCode、Kiro、Zed Agent 等 30 多个 AI 编码工具。以下内容主要结合其 GitHub README 与官方概念文档整理。

核心定位：在你和 AI 之间加一个轻量的”约定层”。 README 的理由很直接：当需求只存在于聊天记录里时，AI 编码助手强大但不可预测。OpenSpec 加了一层轻量的规格，让人和 AI 在写任何代码之前先就”要做什么”达成一致。它的理念是五句话：”流动而非僵化、迭代而非瀑布、简单而非复杂、为存量项目（brownfield）而不只是新项目而建、可从个人项目扩展到企业”。

五个核心概念。 官方文档把整个心智模型浓缩成五点：

  1. 规格就是真相：规格描述系统当前的行为，放在 openspec/specs/ 下按领域组织（如 auth/、payments/）。规格由需求（”系统 SHALL 在 30 分钟后使会话过期”）和场景（具体的 given/when/then 例子）构成，就是纯 Markdown，没有特殊语法。
  2. 一次变更就是一个工作单元：要增删改行为时，在 openspec/changes/ 下创建一个文件夹，放着提案、设计、任务清单和规格修改。
  3. 增量规格（delta spec）只描述变化：在变更中不重写整份规格，只写 ADDED、MODIFIED、REMOVED 的需求——”描述差异，而不是终点”。这是它擅长修改现有系统而不只是新项目的关键：你可以为一个 5 万行的应用写变更规格，而不必先把整个系统文档化。
  4. 产物层层递进：proposal（为什么）→ specs（做什么）→ design（怎么做）→ tasks（步骤）→ implement（实施）。但它们是”助推器而非关卡”，任何时候都可以回头修改。
  5. 归档把变更折叠回真相：工作完成后归档，增量规格合并进主规格，变更文件夹带日期戳移入 changes/archive/。

日常工作流就是几个斜杠命令。 /opsx:explore 是一个”零风险的思考伙伴”，读代码、权衡方案、把模糊想法变成具体计划；/opsx:propose add-dark-mode 让 AI 一次生成 proposal.md、specs/、design.md、tasks.md；人审阅调整计划后，/opsx:apply 让 AI 按任务清单实施并逐项打勾；/opsx:verify 检查实现是否与规格一致；/opsx:archive 更新规格并归档。扩展配置下还有 /opsx:new、/opsx:continue、/opsx:ff、/opsx:bulk-archive 等命令。OpenSpec 本身也是用 OpenSpec 开发的，仓库里可以看到真实的规格和进行中的变更。

团队场景：Stores（测试版）。 单人使用时 OpenSpec 让你和 AI 在一个仓库里保持诚实；团队中难点会转移——一个功能横跨 API 服务器、Web 应用和共享库，需求由一个团队拥有、被其他团队消费，规划在代码存在之前就开始。Stores 的答案是把规划放进一个独立仓库，用同样的 openspec/ 结构，通过 git push 共享，成为所有团队成员和所有编码 agent 都能读取的唯一真相来源。

与竞品的自我对比。 相比 GitHub 的 Spec Kit：”详尽但笨重，僵化的阶段关卡、大量 Markdown、需要 Python 环境”；相比 AWS 的 Kiro：”强大但被锁定在它的 IDE 里，且只能用 Claude 模型”；相比什么都不用：”没有规格的 AI 编码意味着模糊的提示和不可预测的结果”。README 还建议使用高推理能力的模型，并注意”上下文卫生”——开始实施前清空上下文窗口。项目会收集匿名使用统计（仅命令名和版本号），CI 环境中自动关闭。

HN 评论精华

约 100 条评论，204 分。评论区很快变成了一场关于”规格驱动开发本身到底有没有用”的辩论：一边是热情的用户和各种自造框架的作者，另一边是认为长期规格必然腐烂、”代码才是规格”的怀疑派。

正面的使用体验。 slowmovintarget 说他搭了一套自定义的 agent 集群，其中规划 agent 用 OpenSpec 生成计划，再把任务转成工单依赖图，”效果不错，肯定比 SpecKit 轻”。honkycat 连说三个”LOVE”，称它是最喜欢的 SDD 框架，在他们内部评测中得分也很高，”它的仪式感最合理，模型最贴合我的心智模型”；他还说对大任务而言，这是与 LLM 协作最高效的方式——在共享文档上协作，文档作为契约，实施后再据此评估。alexjplant 解释了自己为什么需要它：”除非我用 OpenSpec 明确地研究、界定范围、持久化，再在一个全新上下文里实施，否则 Claude Code 会干些莫名其妙的事。即便是 Opus 也会在被要求启动 Docker 容器时直接放弃、无视明确的架构指令、写一堆充满错误的冗长文档。”recroad 用它生成任务清单，再用 bash 脚本喂给 Ralph 循环，因为每个任务的上下文都很小，省了大量 token。jochem9 描述了团队用法：提案→设计→规格→任务的流程让你做大量前期思考，写完后通过 PR 让同事审阅，之后实施基本可以放手，最后用一个 skill 对照规格验证变更。

最有分量的反对意见来自长期用户。 mafro 在两个单人开发 6 到 9 个月的大型项目上重度使用过 OpenSpec，最近彻底抛弃了规格部分：”长期来看它们没什么用。我让 LLM 双向评估代码是否符合规格、规格是否符合代码，两个项目都显示出巨大的偏离。基本上那条老理论是对的——代码就是规格。”但他保留了流程本身：创建提案、审阅提案、实施、审阅代码，以及维护 ADR（架构决策记录）和不变量日志（用于无法写单元测试验证的行为）。mactavish88 的结论几乎一样：”仓库里长期存在的规格没用，但 OpenSpec 的变更流程对于让 agent 在单个复杂项目上保持正轨非常有价值。”polycaster 反驳说代码只是规格的一部分，很少能记录可供决策依赖的真实需求。sieve 则认为在 LLM 时代，”代码即规格”的问题在于 LLM 会为了达成眼前目标悄悄改东西，所以他现在让 LLM 对照规格审计代码，任何偏离要么更新规格、要么让 LLM 改代码。cloverich 给出了一个关键条件：长期规格可以有效，但必须由人来写和维护，”一旦组织允许 LLM 自己修改规格，规格就不再有用了”。

来自被”强制采用”的一线抱怨。 open-paren 说他所在的组织采用了 OpenSpec，而他非常不喜欢：”每个中等以上的变更都会变成一大堆需要审阅的 Markdown 文档，而且从来不是手写的——永远是 AI 废话，充满 AI 写作的所有特征。”他认为一份简短的手写规格比这些大文档有效得多，而且”散文永远无法穷举代码需要的所有行为，也不应该这样做，规格几乎立刻就会过时”。QwenGlazer9000 附和道：”我的组织也采用了，工作流大幅退化，每次变更都繁琐得多。”维护者 TabishB 回应承认，如果不在规格上投入思考，它确实会变成不可读的废话，团队很快会更新体验，让一切更简洁、更迭代。whinvik 的困惑也很典型：”打开链接就看到它生成那么多文件。我的问题一直是：我怎么审阅这么多文件？我怎么知道规格真的反映了需求？”

“这不就是 90 年代的 UML 吗？” twen_ty 问这与 90 年代”用 UML 生成代码”有何不同、为什么不会以同样的方式失败，”在大型、多人、长期维护的代码库里，规格会腐烂，最终弊大于利”。spinningslate 给出了一段有见地的分析：Rational 那套 UML 失败有两个原因，一是规格与可运行代码之间没有闭环，模型之间的映射靠人工和启发式，模型不会随项目演进而更新；二是用户体验错配，要开发者画图而不是写代码，工件与 diff 和版本控制格格不入。编码 agent 可能缓解第一点，因为它们能读结果代码并在一定程度上保持规格与代码同步；第二点仍然悬而未决。wyum 认为这次不同的原因在于：自然语言的表达力足够，LLM 能填补空白、指出不一致，并且能以超人速度阅读和修订规格，”这让规格维护第一次在高风险应用之外变得经济可行”，前提是规格聚焦于原始意图和实施后必须为真的断言，而不是实现细节。

“大模型已经会规划了，还需要这个吗？” sheepscreek 认为最新的 LLM 经过足够多长上下文任务训练，已经很擅长规划，用 Codex 或 Claude Code 就不必费事。Wazzymandias 直接回应”这绝对不是真的”。verdverm 说最新一批模型更像是被训练成不惜一切完成任务，所以一旦缺少对人类意图的足够上下文就会跑偏，”与其说是规划，不如说是一遇到歧义就往墙上扔意大利面”。virgil_disgr4ce 一句话点题：”写规格不是做规划。”philipp-gayret 指出规格的另一个价值是捕捉你或你组织的”品味”——比如大多数 LLM 都喜欢不仅记录自己做了什么、还记录没做什么，规格可以纠正这类行为。

人人都在造自己的框架。 评论区充斥着各种替代方案：wyum 推荐自己的 spekk-cli（Go 编写、单二进制，专注声明式”活规格”，还有一个每天在沙箱中运行、专门检测规格与实现偏离的”观察者”agent）；kaurimu 推荐 Vercel 的 lat.md（纯 Markdown、wiki 链接构成概念图、用代码注释把源码和规格绑定、lat check 检查偏离）；cg-enterprise fork 了一个项目，补上了产物过期追踪、多模型互审、需求蔓延与延期决策追踪、按上下文决定仪式轻重（小改动走”快车道”）等功能。ulimn 好奇地问 wyum：为什么做了一年同类项目却第一次听说 OpenSpec？wyum 坦言自己开始时知道 SpecKit 和 Kiro，却不知怎的错过了当时已有 2 万星的 OpenSpec，”即使在 AI 时代，对一件事持续投入努力仍是稀缺资源”。diegolas 的观察很中肯：这些工作流都太贴合个人习惯了，每个框架最终都像一条短被子，总有地方盖不到。dmos62 则认为，在 LLM 上下文长度暴涨两个数量级之前，他无法想象不重度依赖规格驱动工作流的大规模 agent 编程，但也提醒”SDD”这个词涵盖的方法差异巨大，单说这个词几乎没有信息量。

其他批评。 CharlieDigital 发现文档站的”概念”链接指向的是模板占位文件，”不太能激发信心”，维护者解释是最近从零重写了文档，一些占位链接没删。ricardobeat 希望看到的是”它是什么、为什么有效，最好有基准测试支撑”，否则看起来”只是又一堆效果未知的 skill”。wyre 质疑”这就是一堆 skill 和 md 文件，为什么需要一个完整的 CLI？”iamjfu 回应 CLI 能让 skill 以确定性方式与规格交互，比如无需花 token 读文件就能校验结构。chandlerklein 则希望有个独立二进制，全局安装 Node 太烦人。