OpenSpec https://github.com/Fission-AI/OpenSpec 是一个命令行工具能够帮助我们和 AI 助手之间建立一套规范驱动spec-driven的开发流程强调变更隔离、人类与 AI 的共识和审查闭环本质上是在构建一种新的 “人机协作语言”。一简介1.1 核心思想将开发流程拆解为两个清晰的阶段:明确 “要什么” —— 在openspec/specs/文件夹中定义当前系统的完整规范。管理怎么改 —— 在openspec/changes/文件夹中存放所有变更提案。从边写边改 到 “规范先行”OpenSpec 能够让复杂的功能演进变得清晰、可审查、可追溯非常适合 1-n 的项目迭代。1.2亮点变更从提案到落地、全流程规范、闭环管理每一步都可溯源、复查与协同。规范落地后后续团队成员查阅 specs 文档 即可快速了解业务历史和变更细节。二初始化工作1. 安装OpenSpec// 全局安装 OpenSpec需要 Node 20.19.0npm install-g fission-ai/openspeclatest2. 项目初始化# 先进入到项目的跟目录建议新建一个新的分支在新的分支上探索cdyour_project# Tips如果提示 openspec 命令不存在可尝试使用 npx fission-ai/openspec 替换执行openspec init回车后选择工具通过space来选择支持多选注意用什么工具就选什么工具每选择一个都会在项目跟目录下生成一个对应的文件夹所以还是不建议选太多这里我只选择Cursor一个。配置完毕。所谓的command就是md文件所谓的skill也是md文件。3. 填充项目上下文信息在Cursor 对话框中输入以下关键词让它帮我们阅读现有项目充分理解项目背景和规范Please read openspec/project.md and help me fill it outwithdetails about my project,tech stack,and conventionsCursor 会分析当前项目已有代码自动填写 project.md其中 project.md 的内容结构大致如下# [项目名] Context## Purpose[描述项目的目的和目标]## Tech Stack-[列出主要技术]-[例如: TypeScript, React, Node.js]## Project Conventions### Code Style[描述代码风格偏好、格式化规则和命名约定]### Architecture Patterns[记录架构决策和模式]### Testing Strategy[解释测试方法和要求]### Git Workflow[描述分支策略和提交约定]## Domain Context[添加 AI 助手需要理解的领域特定知识]## Important Constraints[列出任何技术、业务或法规约束]## External Dependencies[记录关键外部服务、API 或系统]4. 生成变更提案在Cursor对话框中输入斜杠 / 选择 openspec-propose输入你的需求/openspec-propose 需求文档地址为 https://mi.feishu.cn/wiki/XrYcwaeD6ijfBSk每一次提案都会生成一个 Change ID 放在changes 下作为变更目录其中核心内容包含proposal.md提案说明变更原因 Why、内容 What Changes 和 影响 Impackdesign.md技术方案和架构决策tasks.md任务清单将整个开发工作拆分为多个阶段每个阶段包含若干可勾选的 checkbox 任务specs/article-management/spec.md可测试的需求规格5.审查和验证1.重新提案生成提案后我们可以查看 changes 目录下的提案任务清单和技术方案。当你对提案变更不够满意的时候你可以和 AI 交流反复迭代变更提案直到完全符合预期为止比如/openspec-propose 查询功能中的按标题查询支持模糊搜索创建新的审查后会在changes下生成新的变更纪要 id如果不想创建新的提案不要使用 /openspec-proposal 指令进行对话个人理解一个提案算一个需求当需求不明确需要更改时不是再新增一个提案而是使用下面的反复迭代直接修改task.md文件2. 反复迭代当我发现AI 给出的提案和任务不太合理或完善时你可以针对本次提案继续追问和优化更新openspec/changes/support-fuzzy-title-search/tasks.md 当关键字小于2个字时点击查询时给报错“文章标题不能少于2个字”6. 执行任务通过反复迭代提案已初步符合预期后我们可以在Cursor中通过 /opsx:apply 开始执行代码实现# 先实现第一版/opsx:apply add-article-management如果有什么阻塞需要继续沟通让AI完成掉阻塞的内容。# 再实现第二版/opsx:apply support-fuzzy-title-search # 也可用通过该命令实现变更实现/openspec-apply-change7. 归档所有测试通过后完成归档后每个变更独立保存用日期作为前缀标识归档时间并移动到archive中执行归档命令/opsx:archive add-article-management/opsx:archive support-fuzzy-title-searchhttps://github.com/mengday/ruoyi-spec-kit.git branchfeat_openspec三操作流程汇总AI 理解当前项目填充project.mdPlease read openspec/project.md and help me fill it outwithdetails about my project,tech stack,and conventions需求提案一个需求应该算一个提案。/openspec-propose 需求文档地址为 https://mi.feishu.cn/wiki/XrYcwaeD6ijfBSk反复修改和确认提案openspec/changes/add-article-management/tasks.md 当关键字小于2个字时点击查询时给报错“文章标题不能少于2个字”功能实现指定对应的changeID使用 /opsx:apply 命令来实现功能# 先实现第一版/opsx:apply add-article-management验收归档自测通过后使用 /opsx:archive 进行归档/opsx:archive add-article-management四FAQ4.1 OpenSpec Vs 其他工具 ?spec-kit更适合 0 - 1 开始的新项目强调“规格即代码工件”团队遵循统一的标准和最佳实践单层结构易混乱生成的 Markdown 文件可能冗长且内容交叉审查难度较大OpenSpec轻量、兼容性强具备双文件夹模型管理非常适合 现有系统 (1- n) 的功能演进与维护当需要跨多个模块进行重构时其 变更分组机制能 更好地追踪影响范围Cursor plan代码驱动边开发边调整与Cursor IDE 紧密结合创建任务清单适合快速原型和bug修复4.2 Bug 修复是否需要新的变更简单 Bug 修复 → 直接修复如果 bug 修复涉及到功能变更 - 添加新功能或修改现有功能架构修改 - 改变系统架构或设计API 变更 - 修改接口或配置向后兼容破坏 - 影响现有用户此时需要:创建新的变更提案openspec change create fix-bug-name完整的变更流程proposal → design → tasks → 实现 → 归档4.3 OpenSpec 是如何持续迭代OpenSpec 采用的是当前状态 增量变更 的迭代模式如下每次新变更OpenSpec都是在当前 specs/ 基础上进行读取最新构建状态并添加增量要求最后归档。初始状态: specs/(基础功能)↓ 变更1归档: specs/ 变更1 → archive/变更1/ ↓ 变更2归档: specs/ 变更2 → archive/变更2/ ↓ 变更3归档: specs/ 变更3 → archive/变更3/ ↓ 当前状态: specs/(包含所有已归档功能)
OpenSpec
OpenSpec https://github.com/Fission-AI/OpenSpec 是一个命令行工具能够帮助我们和 AI 助手之间建立一套规范驱动spec-driven的开发流程强调变更隔离、人类与 AI 的共识和审查闭环本质上是在构建一种新的 “人机协作语言”。一简介1.1 核心思想将开发流程拆解为两个清晰的阶段:明确 “要什么” —— 在openspec/specs/文件夹中定义当前系统的完整规范。管理怎么改 —— 在openspec/changes/文件夹中存放所有变更提案。从边写边改 到 “规范先行”OpenSpec 能够让复杂的功能演进变得清晰、可审查、可追溯非常适合 1-n 的项目迭代。1.2亮点变更从提案到落地、全流程规范、闭环管理每一步都可溯源、复查与协同。规范落地后后续团队成员查阅 specs 文档 即可快速了解业务历史和变更细节。二初始化工作1. 安装OpenSpec// 全局安装 OpenSpec需要 Node 20.19.0npm install-g fission-ai/openspeclatest2. 项目初始化# 先进入到项目的跟目录建议新建一个新的分支在新的分支上探索cdyour_project# Tips如果提示 openspec 命令不存在可尝试使用 npx fission-ai/openspec 替换执行openspec init回车后选择工具通过space来选择支持多选注意用什么工具就选什么工具每选择一个都会在项目跟目录下生成一个对应的文件夹所以还是不建议选太多这里我只选择Cursor一个。配置完毕。所谓的command就是md文件所谓的skill也是md文件。3. 填充项目上下文信息在Cursor 对话框中输入以下关键词让它帮我们阅读现有项目充分理解项目背景和规范Please read openspec/project.md and help me fill it outwithdetails about my project,tech stack,and conventionsCursor 会分析当前项目已有代码自动填写 project.md其中 project.md 的内容结构大致如下# [项目名] Context## Purpose[描述项目的目的和目标]## Tech Stack-[列出主要技术]-[例如: TypeScript, React, Node.js]## Project Conventions### Code Style[描述代码风格偏好、格式化规则和命名约定]### Architecture Patterns[记录架构决策和模式]### Testing Strategy[解释测试方法和要求]### Git Workflow[描述分支策略和提交约定]## Domain Context[添加 AI 助手需要理解的领域特定知识]## Important Constraints[列出任何技术、业务或法规约束]## External Dependencies[记录关键外部服务、API 或系统]4. 生成变更提案在Cursor对话框中输入斜杠 / 选择 openspec-propose输入你的需求/openspec-propose 需求文档地址为 https://mi.feishu.cn/wiki/XrYcwaeD6ijfBSk每一次提案都会生成一个 Change ID 放在changes 下作为变更目录其中核心内容包含proposal.md提案说明变更原因 Why、内容 What Changes 和 影响 Impackdesign.md技术方案和架构决策tasks.md任务清单将整个开发工作拆分为多个阶段每个阶段包含若干可勾选的 checkbox 任务specs/article-management/spec.md可测试的需求规格5.审查和验证1.重新提案生成提案后我们可以查看 changes 目录下的提案任务清单和技术方案。当你对提案变更不够满意的时候你可以和 AI 交流反复迭代变更提案直到完全符合预期为止比如/openspec-propose 查询功能中的按标题查询支持模糊搜索创建新的审查后会在changes下生成新的变更纪要 id如果不想创建新的提案不要使用 /openspec-proposal 指令进行对话个人理解一个提案算一个需求当需求不明确需要更改时不是再新增一个提案而是使用下面的反复迭代直接修改task.md文件2. 反复迭代当我发现AI 给出的提案和任务不太合理或完善时你可以针对本次提案继续追问和优化更新openspec/changes/support-fuzzy-title-search/tasks.md 当关键字小于2个字时点击查询时给报错“文章标题不能少于2个字”6. 执行任务通过反复迭代提案已初步符合预期后我们可以在Cursor中通过 /opsx:apply 开始执行代码实现# 先实现第一版/opsx:apply add-article-management如果有什么阻塞需要继续沟通让AI完成掉阻塞的内容。# 再实现第二版/opsx:apply support-fuzzy-title-search # 也可用通过该命令实现变更实现/openspec-apply-change7. 归档所有测试通过后完成归档后每个变更独立保存用日期作为前缀标识归档时间并移动到archive中执行归档命令/opsx:archive add-article-management/opsx:archive support-fuzzy-title-searchhttps://github.com/mengday/ruoyi-spec-kit.git branchfeat_openspec三操作流程汇总AI 理解当前项目填充project.mdPlease read openspec/project.md and help me fill it outwithdetails about my project,tech stack,and conventions需求提案一个需求应该算一个提案。/openspec-propose 需求文档地址为 https://mi.feishu.cn/wiki/XrYcwaeD6ijfBSk反复修改和确认提案openspec/changes/add-article-management/tasks.md 当关键字小于2个字时点击查询时给报错“文章标题不能少于2个字”功能实现指定对应的changeID使用 /opsx:apply 命令来实现功能# 先实现第一版/opsx:apply add-article-management验收归档自测通过后使用 /opsx:archive 进行归档/opsx:archive add-article-management四FAQ4.1 OpenSpec Vs 其他工具 ?spec-kit更适合 0 - 1 开始的新项目强调“规格即代码工件”团队遵循统一的标准和最佳实践单层结构易混乱生成的 Markdown 文件可能冗长且内容交叉审查难度较大OpenSpec轻量、兼容性强具备双文件夹模型管理非常适合 现有系统 (1- n) 的功能演进与维护当需要跨多个模块进行重构时其 变更分组机制能 更好地追踪影响范围Cursor plan代码驱动边开发边调整与Cursor IDE 紧密结合创建任务清单适合快速原型和bug修复4.2 Bug 修复是否需要新的变更简单 Bug 修复 → 直接修复如果 bug 修复涉及到功能变更 - 添加新功能或修改现有功能架构修改 - 改变系统架构或设计API 变更 - 修改接口或配置向后兼容破坏 - 影响现有用户此时需要:创建新的变更提案openspec change create fix-bug-name完整的变更流程proposal → design → tasks → 实现 → 归档4.3 OpenSpec 是如何持续迭代OpenSpec 采用的是当前状态 增量变更 的迭代模式如下每次新变更OpenSpec都是在当前 specs/ 基础上进行读取最新构建状态并添加增量要求最后归档。初始状态: specs/(基础功能)↓ 变更1归档: specs/ 变更1 → archive/变更1/ ↓ 变更2归档: specs/ 变更2 → archive/变更2/ ↓ 变更3归档: specs/ 变更3 → archive/变更3/ ↓ 当前状态: specs/(包含所有已归档功能)
