一、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.md4.2 逐步探索（推荐复杂需求）
适合场景：思路不清晰，需要逐步明确
# 第一步：启动变更
/opsx:new add-payment
# 第二步：创建提案
/opsx:continue
# 生成 proposal.md
# 第三步：创建规格
/opsx:continue
# 生成 specs/
# 第四步：创建设计
/opsx:continue
# 生成 design.md
# 第五步：创建任务
/opsx:continue
# 生成 tasks.md4.3 快速前进
适合场景：已经想清楚了，想一步到位
/opsx:new add-payment
/opsx:ff add-payment4.4 实现任务
生成完规划文档后，开始实现：
/opsx:applyAI 会逐个完成
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:verifyAI 会检查：
- 所有需求是否已实现
- 场景是否覆盖
- 边界条件是否处理
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-archiveOpenSpec 会：
- 列出所有未归档的变更
- 检测规格冲突
- 提供合并确认
- 一次性归档多个变更
---
六、完整案例：为博客添加评论功能
让我们通过一个完整的例子来体验 OpenSpec 的工作流。
6.1 初始化（假设已完成）
cd my-blog
openspec init
# 选择使用的工具：Claude Code
# 选择 Profile：core6.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
// 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
// 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:applyAI 开始逐个完成任务：
✓ 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:verifyAI 检查实现：
✓ Comment Creation — 已实现
✓ 发表成功 — 已实现
✓ Markdown 支持 — 已实现
✓ 垃圾词过滤 — 已实现
✓ Comment Pagination — 已实现
✓ 分页浏览 — 已实现
⚠ 发现问题：
- DOMPurify XSS 过滤未实现
- 建议：在 tasks.md 中添加对应任务6.8 归档阶段
/opsx:archiveOpenSpec 执行归档：
✓ 合并 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 → tasks7.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-archive10.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
- 中文文档：https://lzw.me/docs/OpenSpec-Docs-zh/
---
**记住**：OpenSpec 不是束缚你工作流的枷锁，而是帮助你更好地思考和协作的工具。从简单开始，逐步探索，找到适合你的使用方式。
**最重要的建议**：
- 先小范围尝试，找到感觉
- 根据项目需求调整配置
- 定期回顾和优化工作流
- 与团队分享最佳实践