openspec业务SDD驱动开发

一、OpenSpec 是什么

OpenSpec 是由 Fission‑AI 团队开源的 AI‑原生规范驱动开发（Spec‑Driven Development, SDD）框架 + CLI 工具 ，核心口号：先对齐规格，再写代码（Align before code）。

• 定位：给 AI 编程助手（Claude Code、Cursor、Copilot ,opencode等）配一套结构化需求契约，防止需求跑偏、幻觉、上下文丢失。
• 形态：本地目录 + Markdown 文件 + 一套 /opsx: 斜杠命令，无云端依赖、无需 API Key、完全 Git 友好。
• 开源：MIT 协议，GitHub 34.9k+ Stars，Node.js 20+ 运行。

二、解决的核心痛点

• 需求散在聊天记录里，会话一丢就找不到。
• AI 理解偏差，代码反复返工。
• 文档与代码脱节，技术债务累积。
• 多人协作时，变更不可追溯、难以审查。

三、核心设计：双文件夹模型

所有配置都在项目根目录的 openspec/ 下：

plaintext

openspec/
├── specs/          # 系统当前生效的规范（Source of Truth，事实来源）
└── changes/         # 正在进行的变更提案（每个功能一个子目录）

• specs/：已确认的需求、设计、约束，归档后自动合并至此。
• changes/：每个变更独立目录，含 proposal.md、specs/、design.md、tasks.md，并行开发互不干扰

四、两套工作流（Core vs Expanded）

• 默认（core）：只有 /opsx:propose、/opsx:apply、/opsx:archive 等少数几个 "一步到位" 的命令，适合快速开发。
• 扩展（expanded）：多了 /opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:bulk-archive、/opsx:onboard 这些细粒度命令，适合需要精细控制流程的场景。
• openspec config profile + openspec update：就是把 CLI 从默认的 core 切换成 expanded（或自定义），让 AI 能识别并使用这些额外命令。

1）Core（默认，极简快流）

适合小需求、快速开发，3 个核心命令：

• /opsx:propose <name>：一键生成变更目录 + 所有规划产物（相当于 new + ff）
• /opsx:apply：按 tasks.md 实现代码
• /opsx:archive：归档完成的变更
• /opsx:explore：纯思考，不产生产物

流程：

plaintext

/opsx:propose → /opsx:apply → /opsx:archive

2. Expanded（扩展，细粒度控制）

在 core 基础上，多出这些命令（需要手动开启）：

• /opsx:new <name>：只创建空的 change 目录，不生成任何 spec
• /opsx:continue：逐步生成下一个产物（每次一个，适合边想边做）
• /opsx:ff（fast-forward）：一次性生成所有规划产物（直接跳到可实现状态）
• /opsx:verify：实现后做完整性、一致性检查
• /opsx:bulk-archive：批量归档多个变更（适合大项目批量收尾）
• /opsx:onboard：给存量项目做 SDD 冷启动引导

流程：

plaintext

/opsx:new → /opsx:continue 或 /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

五、如何切换工作流（你之前问的）

默认只启用 Core，要使用 Expanded 需两步：

1. 选 Profile（配置）

运行

openspec config profile

交互式勾选 new/continue/ff/verify/bulk-archive/onboard。

2. 生效（更新项目文件）

bash

运行

openspec update

重生成 AGENTS.md、CLAUDE.md、命令定义，AI 即可识别扩展命令。

六、核心价值总结

• ✅ 可控：需求文档化，AI 按 "图纸" 施工，减少幻觉。
• ✅ 可追溯：每次变更留痕，归档后自动入规范，便于审计。
• ✅ 轻量：纯本地文件，无侵入，存量项目可逐步接入。
• ✅ 兼容：支持 20+ AI 工具，不锁定厂商。

七、典型使用场景

• 新功能开发：先写规格再编码，一次通过。
• 复杂重构：分阶段设计、审核、实现，降低风险。
• 多人协作：变更独立提案，评审通过后再合并。
• 存量项目治理：用 /opsx:onboard 快速补全规范。

八、OPSX Slash 命令

在 AI 编码助手的对话界面中调用（如 Claude Code、Cursor、Windsurf）

默认快速路径（CORE PROFILE）

/opsx:propose创建变更并一键生成规划产物

/opsx:explore在提交变更前思考和探索想法

/opsx:apply实现变更中的任务

/opsx:archive归档已完成的变更

扩展工作流命令（自定义选择）

/opsx:new创建新变更脚手架

/opsx:continue按依赖顺序创建下一个产物

/opsx:ff快进：一次创建所有规划产物

/opsx:verify验证实现是否与产物匹配

/opsx:sync将 Delta 规范合并到主规范

/opsx:bulk-archive批量归档多个变更

/opsx:onboard引导式完整工作流教程

/opsx:propose

深入理解 OpenSpec

1.1 OpenSpec 是什么？

OpenSpec 是一个轻量级规范驱动开发框架，专为 AI 编码助手时代设计。它通过建立「人机对齐」的规范层，让开发者和 AI 在编写代码之前先达成共识。

核心定位

OpenSpec 不是取代 AI 编码助手，而是增强它们的可控性和可预测性。它让 AI 从「被动响应聊天历史」转变为「主动遵循结构化规范」。

维度	传统 AI 编码	OPENSPEC 增强
需求来源	聊天历史（易丢失、难追溯）	结构化规范文件（可版本控制）
实现过程	一次性生成，难以迭代	任务驱动，可暂停、可恢复
变更管理	无记录，难以审计	Delta 机制，完整审计轨迹
团队协作	依赖个人 prompt 技巧	标准化工作流，经验可复用

1.2 为什么需要 OpenSpec？

AI 编码助手（如 Claude Code、Cursor、Copilot，opencode）的普及带来了三个核心痛点：

痛点一：AI 幻觉与偏离

需求只存在于聊天中，AI 容易「忘记」上下文或产生幻觉。长对话后，AI 可能偏离最初意图，实现出完全不符合预期的功能。

痛点二：迭代成本高

没有结构化记录，每次修改都需要重新描述上下文。复杂功能的迭代开发变成「从头再来」，效率极低。

痛点三：团队协作难

个人 prompt 技巧无法复用，团队成员的 AI 协作质量参差不齐。缺乏统一的工作流程和质量标准。

OpenSpec 的解决方案

01规范先行

在编码前通过 Proposal 明确意图、通过 Specs 定义行为契约、通过 Design 确定技术方案

02任务驱动

Tasks 文件作为实现清单，AI 按任务逐项执行，可随时暂停和恢复，进度可追踪

03Delta 机制

变更以增量方式记录（ADDED/MODIFIED/REMOVED），完美适配存量项目改造场景

1.3 核心架构解析

理解 OpenSpec 的架构设计，是高效使用它的基础。

OpenSpec 目录结构

openspec/
├── specs/                    # 【权威基准】系统当前行为的完整描述
│   ├── auth/
│   │   └── spec.md           # 认证模块规范
│   ├── payments/
│   │   └── spec.md           # 支付模块规范
│   └── ui/
│       └── spec.md           # UI 行为规范
│
├── changes/                  # 【变更工作区】正在进行的修改
│   ├── add-dark-mode/        # 变更文件夹（每个变更独立）
│   │   ├── proposal.md       # 提案：为什么做、做什么
│   │   ├── specs/            # Delta 规范：正在变化的部分
│   │   │   └── ui/
│   │   │       └── spec.md   # ADDED/MODIFIED/REMOVED 格式
│   │   ├── design.md         # 设计：如何实现
│   │   ├── tasks.md          # 任务：具体实现步骤
│   │   └── .openspec.yaml    # 变更元数据
│   │
│   └── archive/              # 【历史归档】已完成的变更
│       └── 2025-01-24-add-auth/
│
├── schemas/                  # 【可选】自定义工作流 Schema
│   └── my-workflow/
│       ├── schema.yaml
│       └── templates/
│
└── config.yaml               # 项目配置（上下文、规则等）

架构设计哲学
specs/ 与 changes/ 的分离是 OpenSpec 的核心设计。这确保了：① 主规范始终保持稳定 ② 多个变更可并行进行而不冲突 ③ 归档时 Delta 能干净合并回主规范

1.4 产物（Artifact）体系详解

OpenSpec 的产物体系遵循「渐进式明确」原则，每个产物为下一个提供上下文。

Proposal（提案）

**职责：**回答「为什么做」和「做什么」

• Intent（意图）：解决什么问题
• Scope（范围）：包含/不包含什么
• Approach（方案）：高层次的实现思路

💡 Proposal 是与 AI 对齐的第一步，确保你们对「做什么」有共识

Specs（规范）

**职责：**定义系统的行为契约

• Requirements：系统必须具备的行为
• Scenarios：可验证的具体场景（Given/When/Then）
• Delta 格式：ADDED / MODIFIED / REMOVED

💡 Specs 是行为契约，不是实现细节。关注「系统做什么」而非「代码怎么写」

Design（设计）

**职责：**回答「如何实现」

• Technical Approach：技术方案概述
• Architecture Decisions：关键决策及理由
• Data Flow：数据流和组件交互

💡 Design 记录架构决策的「为什么」，方便后续维护和回溯

Tasks（任务）

**职责：**具体的实现步骤清单

• 分组编号：按模块分组，层级编号（1.1, 1.2...）
• 复选框：- [ ] 未完成 / - [x] 已完成
• 可追踪：AI 按任务执行，进度实时可见

💡 Tasks 是 AI 实现代码的「导航图」，粒度要适中（一个任务 ≈ 一次提交）

产物依赖关系图

OpenSpec 最佳实践

2.1 工作流选择策略

OpenSpec 提供两种主要工作流，选择合适的工作流能显著提升效率。

推荐

Core 快速路径

/opsx:propose → /opsx:apply → /opsx:archive

适用场景：

• 需求明确的中小型功能
• Bug 修复和小型优化
• 时间紧迫需要快速交付
• 个人项目或快速原型

**优势：**一条命令生成所有产物，最小化仪式感

精细控制

Expanded 扩展路径

/opsx:new → /opsx:continue/ff → /opsx:apply → /opsx:verify → /opsx:archive

适用场景：

• 复杂功能开发（跨模块、跨团队）
• 需求不明确，需要探索
• 需要逐步审查每个产物
• 团队协作项目

**优势：**每个产物可单独创建和审查，控制粒度更细

工作流选择决策树

选择指南

你能在 30 秒内描述清楚「做什么」吗？
├── 是 → 需求明确
│   ├── 功能复杂度高（>10 个任务）？
│   │   ├── 是 → 使用 Expanded（/opsx:new + /opsx:ff）
│   │   └── 否 → 使用 Core（/opsx:propose）
│   └── 需要团队审查？
│       ├── 是 → 使用 Expanded（/opsx:continue 逐步审查）
│       └── 否 → 使用 Core（/opsx:propose）
│
└── 否 → 需求不明确
    └── 先使用 /opsx:explore 探索，然后选择合适路径

2.2 变更命名规范

好的命名让 openspec list 一目了然，也方便日后追溯。

模式	示例	适用场景
add-<feature>	add-dark-mode、add-export-csv	新增功能
fix-<issue>	fix-login-redirect、fix-memory-leak	Bug 修复
refactor-<module>	refactor-auth-service	代码重构
optimize-<target>	optimize-query-performance	性能优化
update-<component>	update-react-18	依赖更新
implement-<spec>	implement-2fa	实现某个规范

命名原则： 动词-名词格式，kebab-case 连字符分隔，具体描述意图。避免使用 feature-1、update、wip 等模糊命名。

.3 高质量规范编写

规范是 OpenSpec 的核心，写好规范是提高 AI 实现质量的关键。

✅ 好的规范示例

# Auth 规范

## 目的
用户身份验证和会话管理。

## 需求

### 需求：JWT 令牌认证
系统 SHALL 在登录成功时颁发 JWT 令牌。

#### 场景：有效凭据登录
- GIVEN 用户具有有效的邮箱和密码
- WHEN 用户提交登录表单
- THEN 系统返回包含 accessToken 和 refreshToken 的响应
- AND accessToken 有效期为 15 分钟
- AND refreshToken 有效期为 7 天
- AND 用户被重定向到 dashboard 页面

#### 场景：无效凭据登录
- GIVEN 用户提交无效的邮箱或密码
- WHEN 用户提交登录表单
- THEN 系统返回 401 状态码
- AND 响应包含 "Invalid credentials" 错误信息
- AND 不颁发任何令牌

❌ 避免的写法

反例：过于实现细节

# 不好的规范 - 包含实现细节

### 需求：登录功能
使用 bcrypt 比较密码，用 jsonwebtoken 库生成 JWT。
在 UserController.login() 方法中实现，
调用 AuthService.validatePassword() 验证...

⚠️

规范 ≠ 实现计划

规范描述「系统应该做什么」（行为契约），不是「代码怎么写」（实现细节）。内部类名、库选择、代码结构应该放在 design.md 中。

2.4 Delta 规范高级用法

Delta 机制是 OpenSpec 适配「存量项目改造」的核心能力。

ADDED：新增需求

## ADDED Requirements

### 需求：双因素认证
系统 MUST 支持基于 TOTP 的双因素认证。

#### 场景：启用 2FA
- GIVEN 用户未启用 2FA
- WHEN 用户在设置页面启用 2FA
- THEN 显示二维码供 Authenticator App 扫描
- AND 用户需输入验证码确认激活

归档效果：追加到主规范末尾

MODIFIED：修改现有需求

示例

## MODIFIED Requirements

### 需求：会话过期时间
系统 MUST 在 15 分钟不活动后使会话过期。
（之前：30 分钟）

#### 场景：空闲超时
- GIVEN 已认证的会话
- WHEN 15 分钟内无任何操作
- THEN 会话被作废
- AND 用户需重新登录

归档效果：替换主规范中同名需求

REMOVED：删除需求

示例

## REMOVED Requirements

### 需求：记住我功能
（因支持 2FA 而废弃。用户应在每次会话重新认证。）

归档效果：从主规范中删除该需求

2.5 项目配置最佳实践

合理的 config.yaml 配置能显著提升 AI 产物质量。

openspec/config.yaml --- 推荐配置模板复制

schema: spec-driven

# 项目上下文 - AI 生成产物时会参考这些信息
context: |
  # 项目概述
  项目名称：MyApp
  项目类型：Web 应用
  
  # 技术栈
  前端：React 18 + TypeScript + Tailwind CSS
  后端：Node.js + Express + PostgreSQL
  测试：Jest + React Testing Library
  
  # 代码规范
  - 使用 ESLint + Prettier 进行代码格式化
  - 组件使用函数式组件 + Hooks
  - API 遵循 RESTful 设计
  - 所有公共 API 需保持向后兼容
  
  # 分支策略
  - main: 生产分支
  - develop: 开发分支
  - feature/*: 功能分支

# 每产物规则 - 针对特定产物的额外指导
rules:
  proposal:
    - 必须包含回滚计划
    - 说明对现有功能的影响
    - 列出需要协调的团队
  specs:
    - 使用 Given/When/Then 格式编写场景
    - 优先引用现有模式，避免重复发明
    - 包含边界条件和异常场景
  design:
    - 说明关键技术决策的理由
    - 列出受影响的文件和模块
    - 考虑性能和安全影响
  tasks:
    - 任务粒度适中（每个任务约 1-2 小时工作量）
    - 按模块分组，使用层级编号
    - 包含必要的测试任务

PART 3

从零开始实践

通过完整案例掌握 OpenSpec 工作流

通过完整案例掌握 OpenSpec 工作流

3.1 环境准备

1 安装 OpenSpec

bash复制

# 使用 npm 全局安装（推荐）
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

2 初始化项目

bash复制

# 进入项目目录
cd your-project

# 交互式初始化（推荐）
openspec init

# 或非交互式，指定 AI 工具
 openspec init --tools opencode --force --profile custom jettodata-auth

3配置项目上下文（可选但推荐）

bash复制

# 编辑配置文件，添加项目上下文
# 参考上一节的配置模板
vim openspec/config.yaml

3.2 完整案例：为应用添加暗色模式

让我们通过一个完整案例，体验 OpenSpec 的工作流。

PHASE 1 启动变更

在 AI 编码助手的对话窗口中输入：

AI 对话复制

/opsx:propose add-dark-mode

我想为应用添加暗色模式功能，包括：
1. 在设置页面添加主题切换开关
2. 支持检测系统偏好（跟随系统）
3. 用户选择持久化到 localStorage
4. 所有页面即时切换，无需刷新

AI 将创建：

• openspec/changes/add-dark-mode/proposal.md --- 提案文档
• openspec/changes/add-dark-mode/specs/ui/spec.md --- Delta 规范
• openspec/changes/add-dark-mode/design.md --- 设计文档
• openspec/changes/add-dark-mode/tasks.md --- 任务清单

PHASE 2 审查产物（重要！）

在执行实现前，花几分钟审查 AI 生成的产物：

bash --- 查看产物复制

# 列出当前变更
openspec list

# 查看变更详情
openspec show add-dark-mode

# 或使用交互式仪表板
openspec view

审查清单：

• ☐ Proposal：意图和范围是否准确？
• ☐ Specs：场景是否覆盖了主要用例和边界情况？
• ☐ Design：技术方案是否合理？
• ☐ Tasks：任务拆分是否合理？粒度是否适中？

**Pro Tip：**如果发现产物有问题，直接告诉 AI 修改即可，如：「请把 tasks.md 中的第 2 组任务拆分得更细一些」

PHASE 3 实现代码

AI 对话复制

/opsx:apply add-dark-mode

AI 将按照 tasks.md 中的清单逐项实现：

✓ 1.1 创建 ThemeContext

✓ 1.2 添加 CSS 自定义属性

✓ 1.3 实现 localStorage 持久化

→ 2.1 创建 ThemeToggle 组件（进行中）

○ 2.2 添加到设置页面

○ 3.1 定义暗色调色板

💡

可以随时暂停

实现过程中如果需要暂停（下班、开会等），直接停止即可。下次继续时，AI 会从未完成的任务继续执行。

PHASE 4 验证实现（推荐）

AI 对话复制

/opsx:verify

AI 将检查实现是否与产物一致：

• Completeness：所有任务是否完成？所有需求是否实现？
• Correctness：实现是否符合规范意图？
• Coherence：代码是否反映了设计决策？

PHASE 5 归档变更

AI 对话复制

/opsx:archive

归档过程会：

1. 将 Delta 规范合并到 openspec/specs/ui/spec.md
2. 将变更文件夹移动到 openspec/changes/archive/2026-xx-xx-add-dark-mode/
3. 保留完整的产物作为审计轨迹

3.3 CLI 常用命令速查

命令	用途	示例
openspec list	列出所有活动变更	openspec list --json
openspec show	查看变更/规范详情	openspec show add-dark-mode
openspec view	交互式仪表板	openspec view
openspec validate	验证产物格式	openspec validate --all
openspec status	查看产物完成状态	openspec status --change add-dark-mode
openspec archive	归档变更（CLI 方式）	openspec archive add-dark-mode -y
openspec update	更新 AI 工具配置	openspec update
openspec config profile	配置工作流 profile	openspec config profile core

https://radebit.github.io/OpenSpec-Docs-zh/#installation