1. 为什么要先写规格OpenSpec 到底解决了什么问题1.1 不只是“AI写代码工具”而是一座需求与实现的翻译桥最近几个月我陆续帮几个团队把手头的 AI 编程工作流做了重构。大家普遍的抱怨不是“AI 写不出代码”而是“AI 写得很快但方向经常跑偏”。一个功能做三遍每一遍代码质量都还行但第一遍理解错了字段第二遍漏了权限校验第三遍又发现交互逻辑跟现有模块冲突。问题出在哪绝大部分场景下问题不出在实现而出在“需求到底有没有被说清楚”。这也是我主动去研究 OpenSpec 和 Spec-Kit 的原因。OpenSpec 是一个把“规格驱动开发”落地成具体工作流的开源工具核心思路特别简单在写代码之前先让 AI 和你共同维护一份结构化的规格文档把“要做什么”这件事变成可校验、可追踪、可回滚的产物。Spec-Kit 则是配套的辅助工具负责把日常聊天、会议记录、Issue 描述这些非结构化的输入自动整理成 OpenSpec 能用的规格草稿。如果你用过 Cursor、Claude Code 这类 AI 编码工具又总觉得“让 AI 干活像拆盲盒”那这套组合基本就是为你准备的。它适合个人开发者也适合小团队适合从零起步的新项目也适合在存量代码库上做功能迭代。OpenSpec 本身不绑架你的技术栈它只管需求和任务的组织形式。1.2 Spec-Kit 在整条链路里的位置把 Spec-Kit 放在 OpenSpec 旁边说是因为这两个工具解决的是同一个问题链路上的两个环节。OpenSpec 管的是“规格的存储与流转”它给规格文档设计了固定目录、固定字段、固定状态机并且提供了一组命令行工具来操作这些内容。Spec-Kit 管的是“规格的生成与更新”它更像个文书助理你把零散的对话记录、PR 描述、产品想法丢给它它能整理出一份接近 OpenSpec 格式要求的提案草稿。打个比方OpenSpec 是档案室Spec-Kit 是文书员。档案室告诉你每一份档案必须放在哪个柜子、封面写什么、正文分几章文书员负责把领导随口说的几句话整理成符合档案室要求的正式文件。没有 Spec-Kit你也可以手动写规格照样能用 OpenSpec没有 OpenSpecSpec-Kit 生成的东西就缺少一个沉淀和流转的容器用完就散了。实际操作里我建议把 Spec-Kit 用在两处一是项目启动阶段把已有的 README、需求文档、历史讨论记录一次性投喂给它生成初始规格二是每次接到新需求时先把需求聊天记录粘给它让 AI 替你把“用户想要什么”翻译成结构化的 Change 提案。后面我会给出具体的命令和操作示例。2. 核心概念拆解Change、Spec、Task 到底怎么组织2.1 OpenSpec 的目录结构与设计逻辑先看一个用openspec init初始化后的目录长什么样. ├── openspec/ │ ├── projects/ │ ├── specs/ │ │ ├── capabilities/ │ │ └── requirements/ │ ├── changes/ │ │ └── new/ │ ├── templates/ │ └── agents/ ├── .gitignore └── README.md第一次看到这个结构的人最容易困惑的是changes/和specs/有什么区别。我的理解是specs/保存的是“长期有效”的规格描述系统当前应该具备的能力changes/保存的是“待办”的变更提案描述我们下一步打算改动什么。一个 change 经过评审、开发、合并之后它提出的改动会被合并进specs/而这个 change 本身会被标记为 closed 或 archived。这种设计和 Git 的分支工作流很像。每个 change 相当于一个功能分支你的主线规格specs/永远保持在一个“已确认无误”的状态。谁想加功能就切出一个 change在里面折腾折腾完再合并回主线。这个模式的好处是AI 在生成代码前可以先读主线规格了解系统现状再读 change 了解本次目标不需要把整个代码库翻一遍。再看specs/目录内部。OpenSpec 把系统能力拆成了 capabilities 和 requirements 两层。Capability 描述“系统能力域”比如“用户认证”“支付处理”Requirement 描述具体的行为规则挂在某个 capability 下面。每个 requirement 有稳定的地址比如specs/capabilities/user-auth/requirements/force-password-change.md这样 AI 和人在讨论时可以用一个固定地址来指代某条规则而不是说“就是那个改密码的地方”。2.2 一份规范 Change 长什么样openspec new change会在changes/new/下创建一个以变更 ID 命名的目录里面一般包含三个文件proposal.md、tasks.md、specs/可选。我拆开来看。proposal.md是提案正文必须包含三块内容User Story、PODProof of Delivery、Context。User Story 描述用户的真实诉求格式可以灵活但一定要能回答“谁在什么场景下遇到了什么问题”。POD 是一份验收标准清单每条都要能在代码层面验证。Context 是背景说明写清楚为什么要做这个变更、有没有替代方案、受影响的模块有哪些。这里我踩过最大的坑是写 User Story 时天然地想让 AI “怎样做”而不是“做什么”。比如有人会写“用户点击按钮后调用某接口把结果存入数据库”——这在 OpenSpec 里不是好写法。正确的 User Story 是“用户希望能在看板中拖拽卡片来调整任务优先级”。至于用哪个接口、怎么存储那是开发阶段的事规格阶段不关心。tasks.md是开发任务的拆分列表OpenSpec 约定每个任务用- [ ]标记未完成- [x]标记已完成。这个文件主要给 AI 执行用它能在开发过程中勾选任务进度。specs/则用来放这次变更的详细规格段落通常会引用proposal.md中的 POD把验收条件细化成可校验的规格描述。2.3 validate 为什么是整套流程的思想核心OpenSpec 的validate命令是我认为整套工具最被低估的部分。它不校验代码校验的是规格文档本身的结构完整性和描述清晰度。比如User Story 里提到的业务对象是否引用了对应的 capabilityPOD 里的验收点是否至少有一条能被机器理解tasks 里的任务是否有明确的完成判据你大概会有疑问让工具来校验自然语言怎么个校验法OpenSpec 的做法是做一个基础的结构化扫描同时提供扩展点允许你在openspec/agents/下配置额外的校验规则这些规则可以调用 AI 模型做语义检查。我在实际项目中配了一条自定义规则提案里不得出现“优化体验”“提升效率”这类不可测量的描述一旦检测到validate 直接报错。这背后其实是一种工作方式的转变。以前我们强调 Code Review默认代码写完之后才有人检查。OpenSpec 把“检查”提前到了需求与设计阶段而且让机器先检查一遍。机器能挡掉大部分“没想清楚”的提交人工评审的负担能降不少。3. 实操过程从安装到生成第一份可执行的开发计划3.1 三种安装方式与版本选择OpenSpec 的安装方式比较多我按推荐程度排一下安装脚本方式适合 macOS 和 Linuxcurl -LsSf https://openspec.dev/install.sh | sh装完后执行openspec --version验证。如果你在 mac 上安装最新版本需要注意是否为 Apple Silicon 芯片脚本默认会拉对应架构的二进制一般没问题。但我遇到过一种情况公司的安全策略禁用了终端执行来自网络的脚本那就没法用这种方式只能走下面两条路。npm 全局安装适合已经有 Node.js 环境的团队npm install -g openspec这个方式对前端工程师特别友好因为 Node 环境基本是标配。命令装完之后openspec会自动进入 PATH不需要额外配置。需要注意 Node 版本OpenSpec 对 Node 18 以下的老版本支持不好我之前在一台老服务器上装完直接运行时报错把 Node 升到 20 才正常。从 GitHub Releases 下载预编译二进制适合离线内网环境# 在联网机器上下载对应平台的压缩包传到内网服务器 tar -xzf openspec-x86_64-unknown-linux-gnu.tar.gz sudo mv openspec /usr/local/bin/ chmod x /usr/local/bin/openspec openspec --versionSpec-Kit 的安装则主要通过 Python 生态pip install spec-kit # 或者用 uv 这类更快的包管理器 uv tool install spec-kit装好之后spec-kit命令就可以用了。如果你完全不熟悉 Python也可以只装 OpenSpec然后手动写规格文档Spec-Kit 只是加速器而不是必需品。3.2 创建第一个 Change端到端演示我们用一个真实场景来演示。假设你要给一个内部工具加“看板卡片拖拽排序”功能并且你希望 AI 能基于规格直接产出开发计划。初始化项目并创建变更cd my-project openspec init openspec new change 看板卡片支持拖拽排序执行第二条命令后changes/new/下会生成一个目录目录名类似20250101-kankan-tuozhuai具体格式视版本而定。我建议你拿到目录 ID 后立刻记住它后面所有操作都要用到我曾因为忘了 ID 重复创建了好几个空 change。打开proposal.md填入内容# Proposal: 看板卡片支持拖拽排序 ## User Story 作为看板使用者我希望通过鼠标拖拽卡片来调整它们在同一列内的顺序 以便更直观地安排任务优先级而不需要手动填写排序数字。 ## POD - [ ] 用户在同一列内拖拽卡片时卡片顺序实时更新 - [ ] 拖拽结束后新顺序持久化到服务端刷新页面后仍然保持 - [ ] 拖拽过程中其他卡片不会出现异常抖动或错位 - [ ] 服务端接口按新的顺序保存时具备幂等性重复提交不会产生重复排序记录 ## Context 当前看板卡片列表是根据数据库中的 sort_order 字段升序展示的 但管理后台没有提供任何修改排序的入口用户只能通过删除重建来变相调整顺序。 本变更在现有列表接口基础上增加批量更新排序的接口并改造前端列表为可拖拽组件。注意 POD 的写法。我没有写“实现拖拽功能”这种笼统描述而是拆成了四条可以测试的验收点。尤其是第四条“幂等性”这是这类功能最容易被忽略的细节很多开发者做完拖拽后测试通过一上线就发现重复请求把顺序搞乱了。接下来用 Spec-Kit 补全任务拆分。你可以把proposal.md的内容丢给 Spec-Kit CLIspec-kit analyze --input changes/new/xxx/proposal.md --output changes/new/xxx/tasks.md如果没有安装 Spec-Kit也可以让 Cursor 或 Claude Code 直接读proposal.md要求它按照 OpenSpec 的 tasks 格式生成任务清单。生成后的tasks.md大致长这样# Tasks - [x] 分析现有看板列的数据结构确认 sort_order 字段的作用范围 - [ ] 设计批量排序更新接口定义请求与响应格式 - [ ] 实现服务端幂等校验逻辑 - [ ] 引入拖拽排序前端组件并接入现有卡片列表 - [ ] 在拖拽结束后调用批量排序接口并处理失败回滚 - [ ] 补充自动化测试覆盖顺序持久化、幂等、异常抖动三个场景第一项任务直接被标记为完成是因为我在 Context 里已经描述了当前实现方式AI 判断无需再分析。这里有个技巧Context 写得越清楚tasks 的前置调查任务就越少。3.3 与 Cursor、IDEA 插件 ccgui 的集成很多人装好 OpenSpec 后不知道怎么让它跟自己的 IDE 配合。我目前主力开发环境是 Cursor集成方式是在项目根目录建一个规则文件让 Cursor 的 Agent 在执行任务前先读一遍 OpenSpec 的规格。.cursor/rules/openspec.mdc内容如下在生成代码或提出修改方案前必须执行以下步骤 1. 运行 openspec list change查看是否存在与当前需求相关的变更提案 2. 若存在阅读 changes/id/proposal.md 和 tasks.md 3. 开发过程中完成 tasks 中的任务后使用 openspec update change id 更新进度 4. 在准备提交代码前执行 openspec validate确保规格校验通过这样配置之后Cursor 里的 Agent 会把这些规则当作强约束。我实测下来的感受是Agent 仍然会偶尔“偷懒”跳步但相比没有规则时它跑偏的概率明显降低。IDEA 插件 ccgui 的集成方式稍有不同。ccgui 本身是一个 GUI 客户端它支持把 OpenSpec 作为外部工具接入。操作路径大致是在 ccgui 的设置中找到外部工具配置添加一个新工具命令填openspec参数填validate工作目录设成项目根目录。保存后你在 ccgui 里就可以一键运行校验。如果你装了 ccgui 相关的 OpenSpec 集成插件它还能把校验结果以面板形式展示不用切回终端看输出。3.4 离线环境下的安装与使用“OpenSpec 离线下载”是很多人搜索的关键词可能你所在的公司有严格的内网隔离制度。我在服务外包项目里遇到过好多次这种环境目标服务器不能访问公网但开发机可以。这时请记住一句话所有依赖必须在联网机器上提前打包内网机器只负责解压与放置。如果项目用的是 Node 方案离线安装 npm 包的方法是先在一台联网机器上执行npm pack openspec这会生成一个openspec-x.x.x.tgz文件把它通过内网传输工具拷到目标机器然后执行npm install -g ./openspec-x.x.x.tgz如果目标机器完全没有 Node 环境那就直接用前面提到的 GitHub Releases 二进制方案。下载时注意选对平台和 CPU 架构x86_64用于 Intel 机器aarch64用于 Apple Silicon 或 ARM 服务器。传输完后记得chmod x否则会提示 Permission denied。4. 常见问题与排查技巧实录4.1 高频报错与处理方案速查表现象可能原因处理方法openspec: command not found二进制未放入 PATH检查安装目录追加export PATH$PATH:/usr/local/bin或重新安装Node.js version is too oldNode 版本低于 18升级 Node 到 20 以上或改用二进制安装validate 报Root scope not declaredproposal 中 User Story 提到了未定义的能力域在specs/capabilities/下补充对应 capability 文件或在 proposal 中显式声明引用生成的 tasks.md 颗粒度太粗Spec-Kit 输出缺少执行步骤细节手动补充“完成判据”或让 Agent 先读 Context 再生成Cursor Agent 不执行 openspec 命令rules 文件没有生效确认.cursor/rules/路径正确并在 Cursor 设置中开启 rules 加载ccgui 集成后校验结果不显示外部工具参数配置错误在工作目录中使用绝对路径确认 ccgui 能读取到 openspec 的可执行权限4.2 Spec-Kit 与 Superpowers 搭配使用的分工热词里有个高频问题“openspec 怎么和 superpower 一起用”。这里说的 Superpowers 是一套给 AI 编程助手用的技能增强集合它提供了会话管理、任务缓冲、行为纠偏等能力。我的经验是把两者的分工划得非常明确Superpowers 管“过程”OpenSpec 管“产物”。具体来说Superpowers 擅长在长对话中保持上下文它能把 AI 的实验性操作、临时命令、中间结果缓冲起来避免会话一长就“失忆”。但它不擅长把这些中间结果变成正式文档。OpenSpec 和 Spec-Kit 刚好擅长这个。所以我通常的做法是用 Superpowers 让 AI 在一个相对稳定的会话状态里做探索性工作一旦探索有了结论马上把结论交给 Spec-Kit 生成 Change 提案再交给 OpenSpec 落地为开发任务。这里有个容易犯的错有人把 Superpowers 的会话缓冲内容直接粘贴进 proposal.md。缓冲内容里有大量实验噪音比如试错的命令、无效的假设这些不应该污染规格文档。正确的做法是让 Spec-Kit 或你自己提炼出“结论”只保留与变更直接相关的信息。4.3 让 OpenSpec 真正融入日常开发流程的几点心得我团队实际跑了两个月之后总结了三个真正改变工作方式的点。第一一个 change 对应一个分支一个分支对应一次 review。在 Git 工作流里change ID 可以直接放进分支名比如feat/20250101-kankan-tuozhuai。这样一来代码评审人在看 diff 之前可以先看openspec status change的输出了解这次变更“打算做什么”。评审从“看代码猜意图”变成“对照规格查实现”效率高很多。第二validate 应该在 CI 里跑而不仅仅在本地跑。OpenSpec 支持无交互式执行我把openspec validate写进了 GitHub Actions 的 workflow每次 push 都会自动校验变更目录下的规格文档是否合规。如果有人提交的 proposal 缺了 PODCI 直接红掉这个功能比任何规范文档都管用。第三AI 生成的 tasks 是起点不是终点。我用 Spec-Kit 自动生成 tasks 后会人工检查一轮重点看两点有没有遗漏异常处理有没有把“验证性工作”错误地标成“开发工作”。举个例子AI 可能只写“实现接口”不会主动加“验证接口在并发请求下是否幂等”这种任务需要人来补。另外提醒一个小细节如果你用openspec new change时发现交互式提示符比如询问变更名称、描述在自动化脚本里卡住了可以查一下命令行参数大部分版本支持直接传参跳过交互式步骤。我之前写自动化脚本时就卡在这里后来改成openspec new change 修改订单状态流转 --template feature才顺利通过。我个人跑通这套工作流之后的体会是OpenSpec 和 Spec-Kit 表面上是两个命令行工具实际是在帮你重塑 AI 编程时代的“需求管理规范”。过去我们写需求文档一半是给产品经理看一半是给未来的自己留证据现在写规格是为了让 AI 在读代码之前能够准确地知道边界与验收标准。这个转变一开始会让人觉得繁琐但一旦你习惯了“先规格、后开发、再验证”的节奏AI 产出的代码质量会稳定非常多。