轻量级 SDD 开发工具 OpenSpec 实用入门指南

一、OpenSpec 是什么？

一句话：OpenSpec 是一个轻量级的规格驱动开发（SDD）工具，帮助你在写代码前先明确"要做什么"和"怎么做"，让 AI 编码助手更好地理解你的项目。

核心价值：
- 先写规格，后写代码，避免返工
- 规格、设计、任务联动，实现有据可依
- 支持 20+ AI 编码助手（Cursor、Claude Code、Windsurf 等）
- 完全开源，轻量级，无需 API 密钥

---

二、快速开始：5 分钟上手

2.1 安装 OpenSpec

npm install -g @fission-ai/openspec

验证安装：

openspec --version
# 输出：1.2.0 或更高版本

2.2 在项目中初始化

cd your-project
openspec init

初始化过程：

1. 扫描现有工具：OpenSpec 会自动检测你项目中已安装的 AI 工具（如 .claude/、.cursor/）
2. 选择工具：确认或补充你要使用的工具
3. 选择 Profile：选择安装哪些技能（后续详解）
4. 生成配置：自动生成配置文件和技能文件

生成的文件结构：

your-project/
├── openspec/
│   ├── config.yaml          # 项目配置
│   ├── schemas/             # 自定义工作流（可选）
│   ├── specs/               # 主规格文档
│   └── changes/             # 变更提案
│       ├── add-auth/        # 示例变更
│       └── archive/         # 已归档的变更
├── .claude/skills/          # Claude Code 技能
├── .cursor/commands/        # Cursor 命令
└── ...

---

三、核心概念：三个关键理解

3.1 什么是规格驱动开发（SDD）？

传统开发流程：

想法 → 直接写代码 → 发现问题 → 返工

规格驱动开发：

想法 → 写规格 → 明确设计 → 拆解任务 → 写代码

好处：
- 在写代码前发现问题，减少返工
- 规格、设计、任务有明确的文档记录
- AI 更好地理解你的意图，生成更准确的代码

3.2 什么是 Artifact（产物）？

Artifact 是 OpenSpec 工作流中生成的文档，常见的有：

Artifact	用途	示例内容
proposal	变更提案	为什么做、范围、方法
specs	规格文档	需求、场景、验收标准
design	技术设计	架构、数据模型、API 设计
tasks	任务清单	实现步骤、待办事项

3.3 什么是 Delta Specs？

Delta Specs 是增量规格，用语义标记描述变更，而不是重写整个文档。

格式示例：

# Delta for User Auth

## ADDED Requirements
### Requirement: Two-Factor Authentication
系统必须要求用户在登录时输入二次验证码。

## MODIFIED Requirements
### Requirement: Session Timeout
会话超时时间从 60 分钟缩短为 30 分钟。

## REMOVED Requirements
### Requirement: Remember Me
已弃用，不再支持"记住我"功能。

---

四、工作流：从提案到归档

OpenSpec 提供灵活的工作流，你可以根据自己的情况选择。

4.1 一键提案（推荐新手）

适合场景：思路清晰，想快速开始

/opsx:propose add-dark-mode

发生的事情：
1. AI 询问你要构建什么
2. 一次性生成所有规划文档：
- openspec/changes/add-dark-mode/proposal.md
- openspec/changes/add-dark-mode/specs/
- openspec/changes/add-dark-mode/design.md
- openspec/changes/add-dark-mode/tasks.md

4.2 逐步探索（推荐复杂需求）

适合场景：思路不清晰，需要逐步明确

# 第一步：启动变更
/opsx:new add-payment

# 第二步：创建提案
/opsx:continue
# 生成 proposal.md

# 第三步：创建规格
/opsx:continue
# 生成 specs/

# 第四步：创建设计
/opsx:continue
# 生成 design.md

# 第五步：创建任务
/opsx:continue
# 生成 tasks.md

4.3 快速前进

适合场景：已经想清楚了，想一步到位

/opsx:new add-payment
/opsx:ff add-payment

4.4 实现任务

生成完规划文档后，开始实现：

/opsx:apply

AI 会逐个完成 tasks.md 中的任务，并在完成时打勾：

## Tasks
- [x] 1.1 Create Payment entity
- [x] 1.2 Implement PaymentService
- [ ] 2.1 Implement POST /api/payments

关键特性：你可以在实现过程中随时编辑 design.md 或 tasks.md，AI 会感知到修改并调整策略。

4.5 验证实现

完成实现后，验证是否符合规格：

/opsx:verify

AI 会检查：
- 所有需求是否已实现
- 场景是否覆盖
- 边界条件是否处理

4.6 归档变更

完成后，归档变更：

/opsx:archive

发生的事情：
1. 将 Delta Specs 合并到主规格：openspec/specs/
2. 将变更移动到归档目录：openspec/changes/archive/YYYY-MM-DD-add-payment/
3. 清理临时文件

---

五、实用技巧：让 OpenSpec 更好用

5.1 配置项目上下文

编辑 openspec/config.yaml，让 AI 了解你的项目：

schema: spec-driven

# 项目背景：会注入到所有文档生成中
context: |
  技术栈：TypeScript, React, Node.js
  API 风格：RESTful, JSON 响应
  测试：Vitest 单元测试，Playwright E2E
  代码规范：ESLint + Prettier

# 每个文档的特定规则
rules:
  proposal:
    - 必须包含回滚计划
    - 必须列出影响的团队
  specs:
    - 使用 Given-When-Then 格式描述场景
  design:
    - 复杂流程需包含时序图

效果：AI 生成的文档会自动遵循这些规范。

5.2 使用 Explore 模式思考

在不确定是否要开始时，先探索：

/opsx:explore

这是一个纯粹的"思考伙伴"模式，不会创建任何文件。你可以：
- 探索不同的方案
- 澄清需求
- 比较技术选项

思考清楚后，再运行 /opsx:new 开始正式工作流。

5.3 选择合适的 Profile

Profile 决定了安装哪些技能文件：

openspec config profile

Core Profile（推荐新手）：
- 只安装 4 个核心技能：explore、new、apply、archive
- 轻量级，适合个人项目

All Profile（默认）：
- 安装全部 10 个技能
- 适合需要完整工作流的团队

Custom Profile：
- 自定义选择需要的技能
- 灵活性最高

5.4 查看变更状态

随时查看当前变更的进度：

openspec status --change "add-payment"

输出示例：

{
  "artifacts": [
    {"id": "proposal", "status": "done"},
    {"id": "specs", "status": "done"},
    {"id": "design", "status": "done"},
    {"id": "tasks", "status": "in-progress"}
  ],
  "tasks": {
    "total": 10,
    "completed": 7,
    "remaining": 3
  }
}

5.5 批量归档

当你完成了多个变更，可以批量归档：

/opsx:bulk-archive

OpenSpec 会：
- 列出所有未归档的变更
- 检测规格冲突
- 提供合并确认
- 一次性归档多个变更

---

六、完整案例：为博客添加评论功能

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

6.1 初始化（假设已完成）

cd my-blog
openspec init
# 选择使用的工具：Claude Code
# 选择 Profile：core

6.2 提案阶段

/opsx:propose add-comments

AI 询问：

你想构建什么功能？请描述你的需求。

你的回答：

我想为博客文章添加评论功能。用户可以在文章下方发表评论，支持 markdown 格式，需要简单的审核机制（垃圾词过滤）。管理员可以删除评论。

AI 生成的提案（openspec/changes/add-comments/proposal.md）：

# Proposal: Add Comments Feature

## Intent
增加用户参与度，允许读者在文章下发表评论和讨论。

## Scope
**包含**：
- 评论发表（支持 Markdown）
- 评论展示（分页显示）
- 简单审核（垃圾词过滤）
- 管理员删除评论

**不包含**：
- 用户点赞评论
- 评论回复（嵌套评论）
- 评论通知

## Approach
1. 创建 Comment 实体和数据库模型
2. 实现评论 API（CRUD）
3. 前端添加评论表单和展示区域
4. 实现垃圾词过滤中间件
5. 管理后台添加评论管理页面

6.3 规格生成（自动）

OpenSpec 自动生成规格（openspec/changes/add-comments/specs/comment/spec.md）：

# Delta for Comment

## ADDED Requirements

### Requirement: Comment Creation
系统必须允许认证用户在文章下发表评论。

#### Scenario: 发表成功
- **Given** 一个已登录用户
- **When** 在文章页提交评论内容
- **Then** 评论成功保存
- **And** 评论立即显示在文章下

#### Scenario: Markdown 支持
- **Given** 用户提交包含 Markdown 的评论
- **When** 评论被渲染
- **Then** Markdown 正确解析
- **And** 恶意脚本被过滤

#### Scenario: 垃圾词过滤
- **Given** 评论包含垃圾词（如"广告"、"中奖"）
- **When** 用户提交评论
- **Then** 评论被拒绝
- **And** 显示友好提示

### Requirement: Comment Pagination
评论列表必须分页显示，每页 10 条。

#### Scenario: 分页浏览
- **Given** 文章有 25 条评论
- **When** 用户查看第 2 页
- **Then** 显示第 11-20 条评论
- **And** 提供翻页控件

6.4 设计生成（自动）

OpenSpec 自动生成设计（openspec/changes/add-comments/design.md）：

# Design: Comments Feature

## Data Model

// ```typescript
interface Comment {
  id: string
  articleId: string
  userId: string
  content: string          // Markdown 格式
  renderedContent: string  // HTML 格式
  status: 'pending' | 'approved' | 'rejected'
  createdAt: Date
  updatedAt: Date
}
// ```

## API Endpoints

- `POST /api/articles/:articleId/comments` — 发表评论
- `GET /api/articles/:articleId/comments` — 获取评论列表
- `DELETE /api/comments/:id` — 删除评论（管理员）

## Spam Filter

// ```typescript
const spamKeywords = ['广告', '中奖', '免费', '兼职'];

function isSpam(content: string): boolean {
  return spamKeywords.some(keyword => content.includes(keyword));
}
// ```

## Frontend Components

- `CommentForm` — 评论表单
- `CommentList` — 评论列表
- `CommentItem` — 单条评论
- `CommentAdmin` — 管理后台

6.5 任务生成（自动）

OpenSpec 自动生成任务（openspec/changes/add-comments/tasks.md）：

# Tasks

## 1. 后端开发
- [ ] 1.1 创建 Comment 数据库模型和迁移
- [ ] 1.2 实现 Comment CRUD API
- [ ] 1.3 实现垃圾词过滤中间件
- [ ] 1.4 添加评论分页逻辑
- [ ] 1.5 编写单元测试

## 2. 前端开发
- [ ] 2.1 创建评论表单组件
- [ ] 2.2 创建评论列表组件
- [ ] 2.3 集成 Markdown 编辑器
- [ ] 2.4 实现评论加载和分页
- [ ] 2.5 添加错误提示

## 3. 管理功能
- [ ] 3.1 创建评论管理页面
- [ ] 3.2 实现删除评论功能
- [ ] 3.3 添加评论审核视图

## 4. 集成测试
- [ ] 4.1 E2E 测试：发表评论流程
- [ ] 4.2 E2E 测试：垃圾词过滤
- [ ] 4.3 E2E 测试：分页显示

6.6 实现阶段

/opsx:apply

AI 开始逐个完成任务：

✓ 1.1 创建 Comment 数据库模型和迁移
  - 创建了 Comment 实体
  - 生成了数据库迁移文件

✓ 1.2 实现 Comment CRUD API
  - 实现了 POST /api/articles/:articleId/comments
  - 实现了 GET /api/articles/:articleId/comments
  - 实现了 DELETE /api/comments/:id

✓ 1.3 实现垃圾词过滤中间件
  - 创建了 spamKeywords 列表
  - 实现了 isSpam 函数
  - 集成到评论创建流程

...

关键特性：在实现过程中，你发现 Markdown 渲染需要更严格的 XSS 过滤，你可以：

1. 编辑 design.md，添加：

   ## Security
   - 使用 DOMPurify 过滤 HTML
   - 禁用所有 script 标签
   

2. 编辑 tasks.md，添加：

   - [ ] 1.6 添加 DOMPurify XSS 过滤
   

3. 继续运行 /opsx:apply

AI 会感知到修改并调整实现策略。

6.7 验证阶段

/opsx:verify

AI 检查实现：

✓ Comment Creation — 已实现
  ✓ 发表成功 — 已实现
  ✓ Markdown 支持 — 已实现
  ✓ 垃圾词过滤 — 已实现

✓ Comment Pagination — 已实现
  ✓ 分页浏览 — 已实现

⚠ 发现问题：
  - DOMPurify XSS 过滤未实现
  - 建议：在 tasks.md 中添加对应任务

6.8 归档阶段

/opsx:archive

OpenSpec 执行归档：

✓ 合并 Delta Specs 到主规格
  - openspec/specs/comment/spec.md 已更新

✓ 归档变更
  - 移动到 openspec/changes/archive/2026-03-31-add-comments/

✓ 清理临时文件
  - 删除 openspec/changes/add-comments/

---

七、自定义工作流：定义你的节奏

7.1 创建自定义 Schema

如果你的团队有特殊的工作流程，可以创建自定义 Schema：

# 基于默认 Schema 创建
openspec schema fork spec-driven my-workflow

编辑 openspec/schemas/my-workflow/schema.yaml：

name: my-workflow
artifacts:
  - id: research
    generates: research.md
    requires: []
    templates:
      - templates/research.md

  - id: proposal
    generates: proposal.md
    requires: [research]  # 先做调研，再写提案

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # 跳过详细设计和规格

新的依赖图：

research → proposal → tasks

7.2 使用自定义 Schema

在 openspec/config.yaml 中设置：

schema: my-workflow

或者在创建变更时指定：

/opsx:new my-feature --schema my-workflow

---

八、团队协作最佳实践

8.1 共享配置

将 openspec/config.yaml 和 openspec/schemas/ 提交到版本控制：

git add openspec/config.yaml openspec/schemas/
git commit -m "chore: add OpenSpec config"

8.2 PR 引用

在 PR 描述中引用对应的 OpenSpec 变更：

## Related OpenSpec Change
- Proposal: `openspec/changes/add-comments/proposal.md`
- Specs: `openspec/changes/add-comments/specs/`
- Design: `openspec/changes/add-comments/design.md`

评审时先看规格，再看代码。

8.3 定期同步

团队成员定期运行：

openspec update

确保配置和技能文件同步。

---

九、常见问题解答

Q1：我必须在开始前写完所有文档吗？

不是。OpenSpec 支持灵活的工作流：

• 思路清晰：用 /opsx:propose 一次性生成
• 思路模糊：用 /opsx:new + /opsx:continue 逐步创建
• 甚至可以在实现过程中随时修改 design.md 和 tasks.md

Q2：我可以在实现过程中修改规格吗？

可以。这是 OpenSpec 的核心优势之一：

1. 编辑 specs/ 或 design.md
2. 编辑 tasks.md，添加或修改任务
3. 继续运行 /opsx:apply
4. AI 会感知到修改并调整策略

Q3：Delta Specs 是什么？我需要写吗？

Delta Specs 是 OpenSpec 自动生成的。

当你创建变更时，OpenSpec 会自动在 specs/ 中创建 Delta Specs 格式的文档。你只需要填写内容，归档时会自动合并到主规格。

为什么不用重写整个规格？
- 清晰追踪变更历史
- 减少多人协作时的冲突
- 便于回滚和审计

Q4：我的项目很小，需要用 OpenSpec 吗？

取决于你的需求：

• 小项目（个人、单作者）：可以使用 Core Profile，只安装核心功能
• 中型项目（小团队）：推荐使用完整工作流
• 大型项目（多团队）：强烈推荐，规格文档是协作的基础

判断标准：
- 是否经常因为需求不明确返工？
- 是否需要多人协作？
- 是否需要 AI 更好地理解项目？

如果答案是肯定的，OpenSpec 会很有帮助。

Q5：OpenSpec 会锁定我吗？

不会。OpenSpec 是轻量级的：

• 完全开源，无依赖
• 不需要 API 密钥
• 生成的就是 Markdown 文件，随时可以脱离工具使用
• 不强制工作流，你可以随时调整

Q6：如何更新 OpenSpec？

npm install -g @fission-ai/openspec@latest

然后在项目中运行：

openspec update

这会：
- 更新配置文件
- 重新生成技能文件
- 清理过时的命令文件

---

十、进阶技巧

10.1 使用 Explore 模式深入思考

在不确定技术方案时，先探索：

/opsx:explore

你可以问 AI：
- "评论系统应该用实时推送还是轮询？"
- "垃圾词过滤用什么算法比较好？"
- "评论和文章的数据库关系怎么设计？"

探索清楚后，再运行 /opsx:new 开始正式工作流。

10.2 批量处理多个变更

如果你同时在做多个功能：

# 查看所有变更
openspec list

# 批量归档
/opsx:bulk-archive

10.3 查看详细文档

# 查看命令帮助
openspec --help
openspec <command> --help

# 查看配置
openspec config list

# 查看技能
openspec skills list

---

十一、总结：下一步行动

如果你完全没用过 OpenSpec

1. 安装：npm install -g @fission-ai/openspec
2. 初始化：在项目中运行 openspec init
3. 尝试：用 /opsx:propose 创建第一个变更
4. 体验：走完提案→实现→归档的完整流程

如果你已经在用 OpenSpec

1. 更新：npm install -g @fission-ai/openspec@latest
2. 配置：设置适合你的 Profile
3. 尝试：体验新的 /opsx:propose 工作流
4. 优化：根据团队需求自定义 Schema

如果你想了解更多

• GitHub 仓库：https://github.com/Fission-AI/OpenSpec
• 官方文档：https://openspec.dev/
• 社区讨论：查看 GitHub Issues

---

记住：OpenSpec 不是束缚你工作流的枷锁，而是帮助你更好地思考和协作的工具。从简单开始，逐步探索，找到适合你的使用方式。

最重要的建议：
- 先小范围尝试，找到感觉
- 根据项目需求调整配置
- 定期回顾和优化工作流
- 与团队分享最佳实践