OpenSpec 核心概念

理解规范驱动开发（Spec-Driven Development）的核心理念和 OpenSpec 的工作方式。

什么是 Spec-Driven Development？

传统开发模式

需求 → 人 → 代码 → 测试

问题：

需求理解偏差（人脑翻译损失）
实现与需求不一致
测试覆盖不足
知识无法沉淀

规范驱动模式

意图 → Spec → AI → 代码 & 验证

优势：

人与 AI 先对齐需求
规范成为可执行文档
自动生成验证
知识可复用

OpenSpec 的核心哲学

1. Fluid（流动性）

不是：严格的阶段门，必须完成 A 才能开始 B

而是：灵活迭代，可以随时调整

提案 → 设计 → 实现 → 验证
   ↑              ↓
   └──────────────┘
   发现问题随时调整

2. Iterative（迭代性）

不是：一次性完美交付

而是：小步快跑，持续改进

迭代 1: 基础功能
迭代 2: 添加错误处理
迭代 3: 性能优化
迭代 4: 完善文档

3. Living（活的文档）

不是：写一次就扔的文档

而是：与代码同步演进

Spec 文档 ←→ 代码实现
     ↑
     持续同步

OpenSpec 工作流程

完整工作流

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Propose  │ ──▶ │  Apply   │ ──▶ │ Archive  │
│  (提案)   │     │  (实现)   │     │  (归档)   │
└──────────┘     └──────────┘     └──────────┘
     │                 │                 │
     ▼                 ▼                 ▼
 创建变更            按规范实现         保存历史
 proposal.md        编写代码          可回顾学习
 design.md          更新任务          积累知识
 specs/             自动验证          持续改进
 tasks.md

文档结构

每个变更（Change）包含：

openspec/changes/<change-name>/
├── proposal.md      # 提案：为什么做、做什么
├── design.md        # 设计：怎么做
├── specs/           # 规范：详细需求
│   └── <capability>/
│       └── spec.md
├── tasks.md         # 任务：实现清单
└── summary.md       # 总结：实现摘要（归档时生成）

核心概念详解

1. Change（变更）

定义：一个独立的功能或修复

特征：

原子性：一个变更只做一件事
独立性：变更之间尽量不依赖
完整性：包含从提案到归档的全生命周期

示例：

✅ 好的变更：
- "添加用户登录功能"
- "修复订单计算精度问题"

❌ 不好的变更：
- "添加用户系统和订单系统"（太大）
- "修改一些代码"（不明确）

2. Proposal（提案）

作用：记录"为什么"和"做什么"

内容：

Why: 为什么需要这个变更
What: 具体要做什么
Impact: 影响范围
Non-Goals: 明确不做什么

示例：

markdown

## Why
用户反馈无法找回密码，导致流失率上升 15%

## What
添加"忘记密码"功能：
- 用户输入邮箱，发送重置链接
- 链接 24 小时内有效
- 重置后发送确认邮件

## Impact
- 用户模块
- 邮件服务
- 登录页面 UI

## Non-Goals
- 不添加手机号找回
- 不修改现有登录流程

3. Design（设计）

作用：记录"怎么做"

内容：

架构：系统架构图
数据模型：数据库设计
接口：API 定义
算法：关键算法说明

示例：

架构

用户请求 → API Gateway → Auth Service → Email Service

数据模型

PasswordResetToken
- userId: string
- token: string (UUID)
- expiresAt: DateTime
- usedAt: DateTime?

接口

POST /api/v1/auth/forgot-password
Request: { email: string }
Response: { success: boolean, message: string }

4. Spec（规范）

作用：详细的可测试需求

格式：

markdown

## Requirements

### Requirement: 用户可以通过邮箱重置密码
系统 SHALL 允许用户通过注册邮箱接收密码重置链接。

#### Scenario: 成功发送重置邮件
- **WHEN** 用户提交有效邮箱
- **THEN** 系统发送包含重置链接的邮件
- **AND** 返回"邮件已发送"提示

#### Scenario: 邮箱不存在
- **WHEN** 用户提交未注册邮箱
- **THEN** 系统返回相同提示（安全考虑）
- **AND** 不发送邮件

5. Task（任务）

作用：可追踪的实现步骤

格式：

markdown

## 1. 后端实现
- [ ] 1.1 创建 PasswordResetToken 表
- [ ] 1.2 实现 forgot-password API
- [ ] 1.3 实现 reset-password API
- [ ] 1.4 添加邮件发送逻辑
- [ ] 1.5 编写单元测试

## 2. 前端实现
- [ ] 2.1 创建"忘记密码"页面
- [ ] 2.2 创建"重置密码"页面
- [ ] 2.3 添加表单验证

与传统开发对比

方面	传统开发	OpenSpec
需求传递	口头/文档（易丢失）	Spec 文件（版本化）
人-AI 对齐	多次沟通（耗时）	先对齐再编码（高效）
知识沉淀	依赖人脑记忆	规范文档化
变更追踪	难追溯	完整历史记录
测试覆盖	容易遗漏	规范即测试用例

适用场景

✅ 适合使用 OpenSpec

团队项目：多人协作，需要统一标准
复杂功能：需要详细设计和评审
长期维护：需要知识沉淀
AI 辅助开发：充分利用 AI 能力

❌ 不适合使用 OpenSpec

个人项目：简单功能，快速原型
探索性开发：需求不确定，频繁变更
一次性脚本：用完即弃

实际案例

案例：添加用户评论功能

传统方式：

1. 口头和产品经理对齐需求
2. 开始写代码
3. 发现漏了分页
4. 和产品再次确认
5. 继续写代码
6. 发现权限逻辑不清
7. 再次确认
8. 写测试，发现边界情况没处理
9. 修改代码
...

OpenSpec 方式：

1. /opsx:propose "添加用户评论功能"
   AI 生成 proposal, design, specs, tasks
   
2. 评审并确认规范
   - 需要分页吗？✓
   - 权限如何控制？✓
   - 边界情况？✓
   
3. /opsx:apply
   AI 按规范实现
   
4. 验证符合规范
   - 检查清单自动验证
   
5. /opsx:archive
   保存完整历史

常见误区

误区 1：OpenSpec 太繁琐

实际：对于简单功能确实可能过度。但对于复杂功能，前期对齐比后期返工更高效。

建议：

简单功能：精简规范
复杂功能：完整规范

误区 2：规范一成不变

实际：规范是活的文档，应该随着实现演进。

建议：

发现设计问题 → 更新 design.md
发现需求遗漏 → 更新 specs/
保持同步

误区 3：AI 会完全按规范实现

实际：AI 可能误解规范，需要人工验证。

建议：

使用 /opsx:verify 验证实现
关键部分人工 Review
把验证结果反馈给 AI

下一步

学习 OpenSpec 的具体命令和工作流：

→ 命令参考

OpenSpec 核心概念 ​

什么是 Spec-Driven Development？ ​

传统开发模式 ​

规范驱动模式 ​

OpenSpec 的核心哲学 ​

1. Fluid（流动性） ​

2. Iterative（迭代性） ​

3. Living（活的文档） ​

OpenSpec 工作流程 ​

完整工作流 ​

文档结构 ​

核心概念详解 ​

1. Change（变更） ​

2. Proposal（提案） ​

3. Design（设计） ​

4. Spec（规范） ​

5. Task（任务） ​

与传统开发对比 ​

适用场景 ​

✅ 适合使用 OpenSpec ​

❌ 不适合使用 OpenSpec ​

实际案例 ​

案例：添加用户评论功能 ​

常见误区 ​

误区 1：OpenSpec 太繁琐 ​

误区 2：规范一成不变 ​

误区 3：AI 会完全按规范实现 ​

下一步 ​

OpenSpec 核心概念

什么是 Spec-Driven Development？

传统开发模式

规范驱动模式

OpenSpec 的核心哲学

1. Fluid（流动性）

2. Iterative（迭代性）

3. Living（活的文档）

OpenSpec 工作流程

完整工作流

文档结构

核心概念详解

1. Change（变更）

2. Proposal（提案）

3. Design（设计）

4. Spec（规范）

5. Task（任务）

与传统开发对比

适用场景

✅ 适合使用 OpenSpec

❌ 不适合使用 OpenSpec

实际案例

案例：添加用户评论功能

常见误区

误区 1：OpenSpec 太繁琐

误区 2：规范一成不变

误区 3：AI 会完全按规范实现

下一步