OpenSpec是海外很火的一个规范化和自动化工作流程系统，会在先代码前，先跟用户明确需求，并且有较强的规范约束能力，让写出的代码更符合用户需求。目前支持大部分常用的 vibecoding 工具
使用说明
针对v1.x 版本的使用说明
使用各种 vibecoding 工具打开对应的工程后，再命令台中执行 openspec init 后，和 ai 对话接入下面的命令
安装
# 原版 @fission-ai/openspec 或汉化版 @studyzy/openspec-cn
npm install -g @fission-ai/openspec@latest初始化
openspec init初始化是指当前项目（新老项目）第一次进入时，执行会生成 openspec 对应的格式文件目录
如果没有生成对应的 openspec/project.md 文件则需手动创建（项目上下文（技术栈、规范、业务背景））
案例：
你是一个资深 Java 架构师，请帮我生成一个“企业级可落地”的 Spring Boot 单体 Web 项目初始化模板（具备未来演进为微服务的能力），要求结构清晰、规范统一、扩展性强、可直接用于公司项目脚手架。
---
# 一、基础技术栈（必须严格遵守）
* Spring Boot 3.x
* Spring Web MVC
* Spring AOP
* Spring Validation（Hibernate Validator）
* MyBatis-Plus（ORM）
* Redis（必须用于分布式能力）
* Lombok
* Hutool（工具类统一依赖）
* Jackson
* Logback
* springdoc-openapi（Swagger）
* JDK：17+
* 构建工具：Maven
---
# 二、架构设计（企业级要求）
采用“增强版分层架构 + 领域隔离设计”：
com.example.project(模块名称project)
├── infrastructure # 基础设施层（Redis、DB、第三方）
├── domain # 领域层（Entity / 领域服务）
├── application # 应用层（Service 编排）
├── interfaces # 接口层（Controller）
├── common
│ ├── response # 统一响应
│ ├── exception # 异常体系
│ ├── enums # 枚举
│ ├── utils # 工具类（基于 Hutool）
│ ├── constant # 常量
│ ├── aspect # AOP（防抖、日志、限流）
│ ├── config # 全局配置
│ ├── annotation # 自定义注解
│ └── trace # traceId 追踪
└── Application.java
com.example.project.api(模块名称project-api)
要求：
* 明确职责边界
* 禁止 controller 直接操作 mapper
* 为未来微服务拆分预留空间
* project为对应的具体功能，project-api为对外提供的包；如本模块有些对外提供的接口的出入参对象可以定义在这个 project-api 中，其他服务调用这个服务的接口不用写重复代码，引入 project-api 包即可
---
# 三、核心功能（必须完整实现）
## 1. 统一响应结构 Result<T>
* 字段：code / message / data / traceId / timestamp
* 支持链式调用
* 提供 success / fail 方法
---
## 2. 全局异常处理器
* 使用 @RestControllerAdvice
* 必须处理：
* BusinessException
* 参数校验异常
* 系统异常
* 返回统一结构
---
## 3. 异常体系
* BaseException
* BusinessException
* ErrorCode 枚举（code + message + httpStatus）
---
## 4. 参数校验体系
* 使用 @Validated
* DTO 必须使用：
* @NotNull / @NotBlank / @Size / @Pattern
* 错误信息统一处理
---
## 5. 防重复提交
必须实现：
* 注解：@NoRepeatSubmit
* 基于 Redis 分布式锁（如 SETNX + 过期时间）
* 支持：
* 自定义时间窗口（默认 3 秒）通过配置可以进行调整
* key 支持（用户ID + URI + 参数hash）
---
## 6. 日志切面（企业级）
必须记录：
* 请求 URL
* 请求方法
* 入参（可开关，默认为关，防止数据量过大影响性能）
* 返回值（可开关，默认为关，防止数据量过大影响性能）
* 执行耗时，需要定义耗时级别并且跟随打印
* jvm 内存空间打印
---
## 7. TraceId 全链路追踪
实现：
* Filter 注入 traceId（使用 Hutool UUID）
* 放入 MDC
* 每行日志最前面插入【traceId】自动输出 traceId
* 返回给前端
---
## 8. 时间格式统一（必须精确到毫秒 ❗）
统一配置 Jackson：
格式：
yyyy-MM-dd HH:mm:ss.SSS
要求：
* 全局生效
* 时区统一（Asia/Shanghai 或 UTC+8）
---
## 9. MyBatis-Plus 配置
必须包含：
* 分页插件
* 自动填充
* SQL 性能日志（dev环境）
---
## 10. 通用字段自动填充（强制规范 ❗）
字段必须包含：
* id 主键
* isDelete 逻辑删除
* createdDate 创建时间
* lastModifiedDate 最后更新时间
* createdBy 创建人 （用户名）
* lastModifiedBy 最后更新人 （用户名）
要求：
* 使用 MetaObjectHandler 实现
* 自动填充新增 / 更新
---
## 11. 工具类规范（强制 Hutool ❗）
要求：
* 优先使用 Hutool：
* DateUtil
* StrUtil
* BeanUtil
* JSONUtil
* CollUtil
* ❗禁止重复造轮子
* 只有 Hutool 没有的功能才允许自定义工具类
* 初始化定义以上 util 空类继承对应的hutool 工具类
---
## 12. 枚举体系
* 所有枚举实现统一接口
* 支持返回：
* value
* label
---
## 13. 跨域配置（CORS）
---
## 14. Swagger 文档（springdoc）
---
## 15. 示例模块（必须完整 CRUD）
生成 User 示例：
* UserController
* UserService
* UserServiceImpl
* UserMapper
* UserMapper.xml
* UserPO 对应表的实体
* UserQuery 对应业务的查询 （入参）
* UserVO 对应业务的出参
* UserRequest 对应业务的请求（入参）
---
# 四、企业级增强能力（必须实现）
## 1. 接口统一前缀
/api/v1
如： /api/v1/user/save 标识 user 业务的新增
---
## 2. 全局限流
接入sentinel
---
## 3. 响应数据脱敏
* 使用 AOP + 注解 @Sensitive
---
## 4. 防SQL注入基础处理
---
## 5. 多环境配置
* application-dev.yml
* application-prod.yml
---
## 6. 统一常量管理
---
## 7. 统一返回错误码规范
---
## 8. 可扩展设计（重要）
必须预留：
* 多租户扩展点
* 数据权限扩展点
* 插件化扩展点
---
# 五、代码质量要求（非常严格）
* 每个类必须有完整注释
* 不允许伪代码
* 不允许省略 import
* 必须提供完整实现类
* 命名符合企业规范
* 代码可以直接运行
---
# 六、输出要求
按顺序输出：
1. 项目结构说明
2. 核心代码（按模块分类）
3. 配置文件（application.yml + 多环境）
4. 示例接口调用
5. 架构设计说明（重点解释设计原因）
---
# 七、架构风格（关键）
* 参考阿里巴巴开发规范
* 面向扩展设计（开闭原则）
* 避免过度设计
* 优先保证可读性和可维护性
* 将遵循 RESTful API 规范
---
# 八、最终目标（必须达成）
请生成的代码满足：
👉 可以作为公司“项目脚手架模板”直接使用
👉 可支持中大型系统扩展
👉 具备良好的工程规范和统一标准
👉 后续可以平滑升级为微服务架构/opsx:propose : 创建题案
会生成你所说的功能执行步骤和详细的需求场景 specs/{xxx}/spec.md 中体现
proposal.md- 为什么做、做什么specs/{xxx}/spec.md- 需求场景详情design.md- 技术方案tasks.md- 实现清单
/opsx:apply : 执行题案
会根据 tasks.md 中的内容进行一步一步执行，执行完的会将 md 中的 [ ] -> [x]
/opsx:verify : 执行完毕后进行核对
用于检查代码实现是否符合规范文档的要求。它确保你的代码与规范保持一致。
/opsx:archive : 功能完成并上线后进行归档
进行当前功能的完结操作，会对openspec的项目结构调整
将之前通过 /opsx:propose : 创建题案 产生的内容进行归档
对话命令详解表
以下命令是和ai对话中接入（而非命令行指令）
| 命令 | 触发节点 | 做什么 | 产物 | 使用频率 |
|---|---|---|---|---|
/opsx:explore | 想法模糊，需要讨论方案 | AI 分析代码库，给出建议 | 仅对话 | ⭐⭐⭐ 中等 |
/opsx:propose | 需求明确，准备开工 | 一步到位：创建变更 + 生成所有规划文档 | proposal + specs + design + tasks | ⭐⭐⭐⭐⭐ 高频 |
/opsx:new | 想手动逐步创建 | 只创建变更目录，不生成内容 | 空变更目录 | ⭐ 低频 |
/opsx:continue | 已有变更，想补全缺失文档 | 逐个生成下一个缺失的 artifact | 当前缺失的文档 | ⭐⭐ 偶尔 |
/opsx:ff | 已有变更目录，想批量生成 | 一次性生成所有剩余文档 | 补全所有缺失 | ⭐⭐ 偶尔 |
/opsx:apply | 规划文档确认后 | 按 tasks.md 逐项实施，写代码 | 实际代码 | ⭐⭐⭐⭐⭐ 高频 |
/opsx:verify | apply 完成后 | 验证代码是否符合 spec | 验证报告 | ⭐⭐⭐ 中等 |
/opsx:archive | 功能上线后 | 将变更归档到 specs/ | 规范更新 | ⭐⭐⭐ 中等 |
终端命令
| 命令 | 用途 | 示例 |
|---|---|---|
openspec init | 初始化项目 | openspec init |
openspec list | 查看活跃变更 | openspec list |
openspec list --specs | 查看已归档规范 | openspec list --specs |
openspec show <id> | 查看变更详情 | openspec show add-user |
openspec validate <id> | 验证规范格式 | openspec validate add-user |
openspec archive <id> | 归档变更 | openspec archive add-user |
openspec update | 更新 AI 命令文件 | openspec update |
openspec --version | 查看版本 | openspec --version |
openspec view | 在终端中显示项目的规范和变更概览 | openspec view |
openspec结构说明
your-project/
├── openspec/ # OpenSpec 核心目录
│ ├── project.md # 项目上下文（技术栈、规范、业务背景）
│ ├── AGENTS.md # AI 工作流说明书
│ ├── config.yaml # OpenSpec 配置文件（可选）
│ ├── specs/ # 已归档规范（真理之源）
│ │ ├── user/ # 用户模块规范
│ │ │ └── spec.md # 用户功能规范
│ │ ├── auth/ # 认证模块规范
│ │ │ └── spec.md # 认证功能规范
│ │ └── ... # 其他模块
│ └── changes/ # 活跃的变更提案
│ ├── add-user-registration/ # 变更1：用户注册
│ │ ├── proposal.md # 提案说明（为什么、做什么）
│ │ ├── design.md # 技术设计方案
│ │ ├── tasks.md # 实现任务清单
│ │ └── specs/ # 增量规范
│ │ └── user/
│ │ └── spec.md # 用户注册的规范增量
│ ├── add-jwt-auth/ # 变更2：JWT认证
│ │ ├── proposal.md
│ │ ├── design.md
│ │ ├── tasks.md
│ │ └── specs/
│ │ └── auth/
│ │ └── spec.md
│ └── archive/ # 已归档的变更
│ ├── 2024-01-15-add-login/
│ └── 2024-01-20-add-profile/
│
└── .trae/ # Trae IDE 配置目录
└── skills/ # AI 技能文件（OpenSpec 命令）
├── opsx-propose.md # /opsx:propose 命令定义
├── opsx-apply.md # /opsx:apply 命令定义
├── opsx-archive.md # /opsx:archive 命令定义
├── opsx-verify.md # /opsx:verify 命令定义
├── opsx-explore.md # /opsx:explore 命令定义
├── opsx-new.md # /opsx:new 命令定义
├── opsx-continue.md # /opsx:continue 命令定义
├── opsx-ff.md # /opsx:ff 命令定义
└── opsx-task.md # /opsx:task 命令定义（可能）openspec配置说明
# openspec/config.yaml
# 规范存储配置
specs:
# 规范文件存储路径（相对于项目根目录）
path: ./openspec/specs
# 规范文件命名规则
naming: "{module}.spec.md"
# 是否强制使用特定的规范格式
enforce_format: true
# 变更管理配置
changes:
# 变更目录路径
path: ./openspec/changes
# 变更目录命名规则
naming: "{date}-{name}"
# 归档配置
archive:
# 归档路径
path: ./openspec/changes/archive
# 归档文件前缀（如：2024-）
prefix: ""
# 归档后是否删除原目录
delete_after_archive: false
# 归档后是否创建 Git tag
create_git_tag: false
# 验证配置
validation:
# 严格模式：强制要求所有字段完整
strict: true
# 是否要求 tasks.md 文件存在
require_tasks: true
# 是否要求 design.md 文件存在（复杂变更）
require_design: false
# 规范格式验证级别（error/warning/ignore）
spec_format_level: error
# 自定义验证规则
custom_rules:
- "所有 Requirement 必须包含至少一个 Scenario"
- "每个 Scenario 必须包含 GIVEN/WHEN/THEN"
# 模板配置
templates:
# 提案模板（可自定义）
proposal: |
# Proposal: {name}
## Why
{why}
## What Changes
{what}
## Impact
{impact}
# 设计模板
design: |
# Design: {name}
## Architecture
{architecture}
## Database Changes
{database}
## API Changes
{api}
# 任务模板
tasks: |
# Tasks: {name}
## Implementation
- [ ] {task1}
- [ ] {task2}
# 规范模板
spec: |
# {module}
## Requirement: {name}
{description}
#### Scenario: {scenario}
- GIVEN {given}
- WHEN {when}
- THEN {then}
# AI 集成配置
ai:
# 使用的 AI 工具（auto/cursor/claude/copilot）
tool: auto
# 生成代码时使用的语言
language: zh-CN
# 自动读取上下文文件
auto_context:
- openspec/project.md
- openspec/specs/**/*.md
# Git 集成配置
git:
# 归档时自动提交
auto_commit_on_archive: true
# 提交信息模板
commit_template: "docs: archive change {name}"
# 是否在变更时创建分支
auto_branch: false
# 日志配置
logging:
# 日志级别（debug/info/warn/error）
level: info
# 日志输出文件
file: ./openspec/logs/openspec.log老项目接入openspec的痛点
1 主要痛点
| 痛点 | 严重程度 | 说明 | 解决方案 |
|---|---|---|---|
| 缺少规范文档 | 🔴 高 | 现有代码没有规范记录 | 渐进式补充规范 |
| 代码与规范不一致 | 🔴 高 | 重构时可能出现不一致 | 先写规范再改代码 |
| 技术栈混乱 | 🟡 中 | 多种框架混用 | 在 project.md 中明确标准 |
| 命名不统一 | 🟡 中 | 各种命名风格混用 | 定义规范，逐步重构 |
| 历史债务 | 🔴 高 | 想改不敢改 | 从新功能开始，逐步覆盖 |
| 团队习惯 | 🔴 高 | 开发人员不习惯写规范 | 培训 + 工具强制 |
| 规范维护成本 | 🟡 中 | 已有代码需要补充规范 | 按优先级，不要一次做完 |
2 老项目接入的真实困境
困境 1: 先有鸡还是先有蛋？
┌─────────────────────────────────────────┐
│ 规范派：先写规范再改代码 │
│ 代码派：代码已经在那了，规范应该匹配代码 │
│ 结果：陷入"规范应该反映代码"的争论 │
└─────────────────────────────────────────┘
困境 2: 规范补充的工作量
┌─────────────────────────────────────────┐
│ 10 万行代码 + 50 个模块 │
│ 补充所有规范 = 2-3 人月 │
│ 团队：没时间！ │
└─────────────────────────────────────────┘
困境 3: 规范与代码不一致
┌─────────────────────────────────────────┐
│ 规范说：密码用 BCrypt │
│ 代码实际：MD5 │
│ 问：改规范还是改代码？ │
│ 答：改代码需要重构，风险大 │
│ 改规范失去规范意义 │
└─────────────────────────────────────────┘老项目接入的实用策略
1 核心原则：渐进式接入，不追求完美
策略对比：
❌ 错误策略：一次性补充所有规范
→ 工作量巨大，团队抵触，容易失败
✅ 正确策略：从当前开始，逐步覆盖
→ 新功能强制规范，旧功能逐步补充2 分阶段接入计划
## Phase 1: 建立基础（1-2 天）
- [ ] openspec init
- [ ] 填写 project.md（技术栈、架构）
- [ ] 团队培训（1 小时）
- [ ] 配置 CI/CD 验证
## Phase 2: 新功能规范（持续）
- [ ] 所有新功能使用 OpenSpec
- [ ] 新代码 100% 符合规范
- [ ] 建立规范审阅流程
## Phase 3: 核心模块补充（2-4 周）
- [ ] 用户模块补充规范
- [ ] 订单模块补充规范
- [ ] 支付模块补充规范
- [ ] 每个规范补充后验证一致性
## Phase 4: 重构时补充（持续）
- [ ] 每次重构前先写规范
- [ ] 重构后验证规范
- [ ] 规范驱动重构
## Phase 5: 形成规范体系（3-6 个月）
- [ ] 规范覆盖率 > 70%
- [ ] 团队习惯形成
- [ ] 规范成为开发流程一部分3 优先级策略
## P0 - 立即补充（核心业务）
- 用户认证模块（安全相关）
- 订单支付模块（资金相关）
- 核心 API（对外接口）
## P1 - 近期补充（高频变更）
- 促销活动模块
- 推荐算法模块
- 数据统计模块
## P2 - 有时间补充（稳定模块）
- 后台管理模块
- 日志监控模块
## P3 - 暂不补充（边缘功能）
- 工具类
- 配置类
- 已计划废弃的功能4 处理代码与规范不一致的策略
## 策略 1：规范反映现状（推荐）
- 基于现有代码编写规范
- 规范 = 当前实现
- 目的：记录现状，便于后续重构
## 策略 2：规范定义目标（有风险）
- 定义理想的实现方式
- 代码需要重构
- 适用于：安全漏洞、架构问题
## 策略 3：混合策略（最实用）
- 核心安全功能：规范定义目标，推动重构
- 一般功能：规范反映现状
- 新功能：规范先行老项目接入实战案例
案例：电商平台接入 OpenSpec
项目背景：
- 代码量：50 万行
- 服务数：12 个微服务
- 团队：15 人
- 历史：5 年
- 痛点：文档缺失，新人上手慢，技术债严重接入过程：
# Week 1-2: 准备阶段
1. openspec init（每个服务单独初始化）
2. 填写各服务的 project.md
3. 团队培训（2 次，共 3 小时）
4. 确定优先级：用户服务 → 订单服务 → 支付服务
# Week 3-4: 用户服务规范补充
1. 分析现有用户服务代码
2. 编写用户模块规范（基于现状）
3. 发现安全漏洞（密码 MD5）
4. 创建提案：重构密码加密为 BCrypt
5. 实施重构，验证规范
# Week 5-6: 订单服务规范补充
1. 编写订单模块规范
2. 发现状态机混乱
3. 创建提案：规范化订单状态机
4. 逐步重构
# Week 7-8: 新功能规范
1. 添加优惠券功能（新功能）
2. 使用 OpenSpec 规范开发
3. 验证通过后归档
# 3 个月后：
- 核心模块规范覆盖率：60%
- 新功能 100% 使用 OpenSpec
- 团队习惯逐步形成
- Bug 率下降 30%