一、前言 📌

什么是OpenSpec ？流程化编程工具

二、OpenSpec介绍

OpenSpec 的威力

什么是SDD？

有SDD 还有其他的DD是什么意思？

SDD的位置

OpenSpec 特点

模式介绍

切换模型命令 openspec config set profile core / custom

目录介绍

核心文件介绍

三、前置环境安装 ⚙️

OpenSpec 基于Node.js运行，先安装Node环境，再全局安装CLI工具。

1. Node环境校验

node -v
npm -v

要求版本≥v20.19，版本过低需重装Node。

2. 全局安装OpenSpec

npm install -g @fission-ai/openspec

3. 验证安装成功

openspec --version

输出版本号即代表安装完成✅

初始化项目

npx openspec init

会多一些命令和skills，用于当前项目使用

四、项目实战

完整标准工作流：探索 → 提案规划 → 代码实现 → 归档沉淀

一、/opsx:explore 需求探索（前置调研）

核心作用

纯思考、调研、梳理问题，不生成任何文件，仅做需求/技术预研，适合需求模糊场景。

语法

/opsx:explore [调研描述]

使用场景

1. 需求不清晰，先和AI头脑风暴、梳理边界
2. 技术选型、风险评估、现有代码结构分析
3. 接手旧项目，先梳理模块逻辑、历史坑点

示例

/opsx:explore 分析现有用户登录模块，评估新增短信验证码功能的改动范围与潜在风险

执行行为

AI 只读项目代码，输出分析报告、技术方案对比，不会创建 openspec 目录文件，仅对话输出。

二、/opsx:propose 创建变更提案（生成规范图纸）

核心作用

正式发起功能变更，自动创建独立变更目录，一次性生成全套标准化设计文档，是开发的“图纸阶段”。

语法

/opsx:propose [变更标识] [需求描述]

使用场景

需求调研完成、确认要开发新功能/修复Bug，正式产出规格文档。

示例

/opsx:propose user-sms-login 给登录模块新增短信验证码登录功能，支持60秒倒计时、验证码5分钟有效期

自动生成文件（目录：openspec/changes/user-sms-login/）

1. proposal.md：需求背景、业务目标、改动范围
2. specs/：功能规范、接口定义、入参出参、异常场景
3. design.md：技术架构、依赖、数据库/缓存方案
4. tasks.md：拆分好的可执行开发任务清单（后续apply依据）

三、/opsx:apply 按规范实现代码（落地开发）

核心作用

读取 tasks.md 任务清单，严格按照前面生成的规范文档编写代码，不超范围开发。

语法

/opsx:apply [变更标识]

使用场景

评审完 proposal、spec、design 文档，确认方案无误后，执行编码实现。

示例

/opsx:apply user-sms-login

执行行为

1. 逐条读取 tasks 任务，逐个完成代码编写
2. 自动修改对应接口、实体、页面、工具类
3. 每完成一项自动在 tasks.md 勾选完成状态
4. 不会擅自新增规范外的逻辑，约束AI开发边界

四、/opsx:archive 归档完成变更（沉淀全局规范）

核心作用

功能开发自测完成后，将本次变更的规范合并到项目全局主规范，归档本次变更目录，统一沉淀项目知识库。

语法

/opsx:archive [变更标识]

使用场景

功能开发、自测、联调全部完成，准备合并代码、收尾迭代。

示例

/opsx:archive user-sms-login

执行行为

1. 将本次变更 specs 合并至全局 openspec/specs/（项目统一规范源）
2. 把当前变更文件夹移动至 openspec/changes/_archived/ 归档
3. 更新项目总文档，记录本次功能迭代记录
4. 清空活跃变更状态，支持下一轮新需求开发

完整标准实战流程示例

1. 模糊需求先调研
   /opsx:explore 调研短信登录实现方案
2. 确认方案，生成全套规范文档
   /opsx:propose user-sms-login 新增短信验证码登录
3. 人工核对、修改spec/design文档后，执行编码
   /opsx:apply user-sms-login
4. 自测完成，归档沉淀规范
   /opsx:archive user-sms-login