第一章：OpenSpec 基础概念

AI 编程的痛点

2024-2025 年，AI 编程助手（Claude、GPT、Cursor 等）彻底改变了软件开发。但随之而来的是新问题：

1. 需求理解偏差

你：帮我做一个用户登录功能
AI：好的，我来实现...（写了 200 行代码）
你：不对，我要的是手机号登录，不是邮箱
AI：好的，我修改...（又改了 100 行）
你：还有，要支持微信登录
AI：好的...（继续改）
你：算了，重新来过吧

问题：AI 在"猜测"你的需求，而不是"理解"你的需求。

2. 上下文丢失

AI 对话有长度限制，长项目会丢失早期上下文
换个对话窗口，AI 就忘了之前的需求
团队成员无法共享 AI 的理解

3. 不可预测的结果

同样的提示词，不同时间结果不同
没有统一标准，代码质量参差不齐
难以 code review，不知道 AI 为什么这么写

4. 团队协作困难

每个人的 AI 对话历史不同
没有统一的需求文档
新成员不知道项目背景和决策过程

OpenSpec 解决了什么问题？

核心解决方案：规范驱动开发（Spec-Driven Development）

在写代码之前，先写规范文档。让 AI 基于明确的规范实现，而不是猜测。

传统方式：需求 → AI 猜测 → 代码 → 修改 → 修改 → 代码
OpenSpec：需求 → 规范文档 → AI 理解 → 代码 → 完成

具体解决的问题

痛点	OpenSpec 解决方案
需求理解偏差	规范文档明确需求，AI 不再猜测
上下文丢失	文档持久化，随时查阅
结果不可预测	基于规范实现，结果可预期
团队协作困难	共享规范，统一认知
代码审查困难	规范作为审查依据
项目知识沉淀	每次变更都有完整记录

实际效果

没有 OpenSpec：

开发一个功能平均需要 3-5 轮对话修正
团队成员对需求理解不一致
3 个月后忘了为什么这样设计

使用 OpenSpec：

一次对齐，精准实现
所有人基于相同规范工作
完整的变更历史，随时追溯

什么是 OpenSpec？

OpenSpec 是一个规范驱动开发（Spec-Driven Development，SDD）框架，专门为 AI 编程助手设计。

工作流程

1. /opsx:propose "添加用户登录功能"
   ↓
2. AI 创建规范文档
   - proposal.md  （为什么做）
   - specs/       （做什么）
   - design.md    （怎么做）
   - tasks.md     （具体步骤）
   ↓
3. 你审查并确认规范
   ↓
4. /opsx:apply
   AI 按规范实现代码
   ↓
5. /opsx:archive
   归档变更记录

核心价值

对齐先于实现 - 先确认需求，再写代码
文档即契约 - 规范是人和 AI 之间的契约
可追溯的历史 - 每次变更都有完整记录
团队协作基础 - 共享规范，统一认知

核心概念

1. Change（变更）

每个功能或修改都是一个 Change，有独立的目录：

openspec/changes/
└── add-user-login/          ← 一个 Change
    ├── proposal.md
    ├── specs/
    ├── design.md
    └── tasks.md

2. Proposal（提案）

描述为什么要做这个功能：

# 提案：用户登录功能

## 背景
当前系统没有用户认证，所有人都可以访问所有数据。

## 目标
- 实现安全的用户认证
- 支持多种登录方式

## 范围
- 手机号 + 验证码登录
- 微信 OAuth 登录
- 不包括：邮箱登录（后续迭代）

3. Specs（规范）

描述要做什么，包含详细需求和场景：

# 需求规范

## 功能需求
- 用户可以用手机号 + 验证码登录
- 验证码 5 分钟内有效
- 登录成功后返回 JWT Token

## 场景
### 场景 1：正常登录
1. 用户输入手机号
2. 点击"获取验证码"
3. 输入验证码
4. 点击"登录"
5. 跳转到首页

### 场景 2：验证码过期
1. 用户输入过期验证码
2. 系统提示"验证码已过期，请重新获取"

4. Design（设计）

描述怎么做，技术方案：

# 技术设计

## 架构
- 前端：React + Ant Design
- 后端：Node.js + Express
- 数据库：MySQL

## API 设计
POST /api/auth/send-code    # 发送验证码
POST /api/auth/login        # 验证码登录
POST /api/auth/wechat       # 微信登录

## 数据模型
User {
  id, phone, wechat_openid,
  created_at, last_login_at
}

5. Tasks（任务）

描述具体步骤，AI 按此实现：

# 实现任务

## 1. 后端 API
- [ ] 1.1 创建 User 数据库表
- [ ] 1.2 实现发送验证码接口
- [ ] 1.3 实现验证码登录接口
- [ ] 1.4 集成微信 OAuth

## 2. 前端页面
- [ ] 2.1 创建登录页面
- [ ] 2.2 实现手机号输入组件
- [ ] 2.3 实现验证码倒计时
- [ ] 2.4 实现微信登录按钮

OpenSpec vs 传统开发

对比项	传统开发	OpenSpec
需求对齐	口头描述，容易误解	规范文档，明确清晰
AI 协作	反复修改，浪费时间	一次对齐，精准实现
项目记录	散落在聊天记录里	结构化文档，随时查阅
团队协作	各自理解不同	共享规范，统一认知
迭代管理	不知道改了什么	每次变更有完整记录

OpenSpec vs 竞品

工具	特点	缺点
OpenSpec	轻量、灵活、多工具支持	-
GitHub Spec-Kit	详尽	重量级，Python 依赖，阶段门僵化
Kiro (AWS)	功能强大	锁定 IDE，只支持 Claude
无规范	简单	AI 随意发挥，结果不可预测

核心哲学

→ fluid not rigid          流体而非僵化
  随时可以修改任何文档，没有严格的阶段门

→ iterative not waterfall  迭代而非瀑布
  支持持续迭代，不是一次性写完所有文档

→ easy not complex         简单而非复杂
  最小化仪式感，专注于价值

→ built for brownfield     适用于已有项目
  不只是新项目，已有项目同样适用

→ scalable                 可扩展
  从个人项目到企业级团队都适用

下一步

→ 第二章：安装配置