OpenSpec 基础概念与 OPSX 工作流：AI 时代的规范驱动开发

发布日期：2026-06-06 | 分类：AI 开发方法论 | 难度：入门

一、简介

1.1 什么是 OpenSpec？

OpenSpec （openspec.dev）是一个开源的**规范驱动开发（Spec-Driven Development, SDD）**框架，由 Fission-AI 团队维护。其核心理念极其简洁：

先对齐需求，再写代码。 🚫 不写没有规范的代码

在 AI 编程助手（如 Claude Code、Codex CLI）日益普及的今天，OpenSpec 解决了 AI 编码中最核心的问题：AI 不知道你要做什么。它用 4 个核心 Markdown 文件来锁定「要做什么」和「怎么做」，然后喂给 AI 去执行，从根本上消除需求模糊和多次返工。

1.2 为什么要用 OpenSpec？

问题	没有 OpenSpec	使用 OpenSpec
需求模糊	AI 猜需求，做出来不是你要的	spec 写清楚再写代码，一次过
反复返工	「改一下这里」→ AI 改歪了 → 再改	改 spec 再 apply，精准定向
缺乏记录	改了什么、为什么改，全凭记忆	propose + archive 天然记录变更历史
团队协作	各说各话，AI 不知道听谁的	spec 就是权威参考
代码审计	改了多少东西？不知道	tasks.md 逐条 check，一目了然

1.3 适用场景

场景	推荐度	说明
新功能开发（>半天工作量）	⭐⭐⭐⭐⭐	需求明确后再开工
重构/技术债务清理	⭐⭐⭐⭐	重构边界清晰，不越界
多人 AI 协作同一代码库	⭐⭐⭐⭐⭐	不同 AI 按同一规范工作
修复一行 bug	⭐	直接改，走快速通道
快速原型/实验	⭐	跳过规范，用 `/opsx:ff`

二、核心文件结构

OpenSpec 在你的项目里生成如下文件结构：

markdown 复制代码

openspec/
├── project.md                ← 项目全局约定（技术栈、架构风格、规范）
└── specs/
    └── <change-name>/        ← 每次变更一个目录
        ├── proposal.md       ← 变更提案（为什么做、做什么）
        ├── spec.md           ← 行为规范（输入输出、边界条件）
        ├── design.md         ← 技术设计（架构、组件、数据流）
        └── tasks.md          ← 实施清单（逐条可 check 的任务）

2.1 各文件职责

文件	解决的问题	类比	谁写
`proposal.md`	Why & What	PRD / 需求文档	人类（AI 辅助生成）
`spec.md`	Behavior	功能规格 / 验收标准	AI 生成，人类审核
`design.md`	How	技术设计文档	AI 生成，人类审核
`tasks.md`	Execution	Jira 任务列表	AI 生成，人类审核

2.2 project.md 示例

markdown 复制代码

# Project: 电商后台管理系统

## 技术栈
- 前端：React 18 + TypeScript + Tailwind CSS
- 后端：Node.js + Express + Prisma ORM
- 数据库：PostgreSQL
- 测试：Vitest + Playwright

## 架构风格
- 组件用函数式 + hooks
- API 遵循 RESTful 规范
- 错误处理使用统一的 ErrorBoundary

## 代码规范
- 使用 ESLint + Prettier
- 提交信息遵循 Conventional Commits
- 每个 PR 必须包含测试

三、OPSX 工作流详解

OpenSpec 的核心是一套 OPSX 命令，在 Claude Code 中通过斜杠命令执行。整个流程分为四个阶段：

3.1 `/opsx:propose` --- 提出变更

你描述需求，AI 自动生成 proposal.md：

对话示例：

markdown 复制代码

你: "我想给用户模块加一个忘记密码功能"
Claude: 让我帮你生成 proposal...

# Proposal: 忘记密码功能

## 目标
允许用户通过注册邮箱重置密码，提升账户安全性。

## 范围
- 发送重置邮件（含有效期 30 分钟的链接）
- 重置密码页面
- 密码强度校验

## 不做
- 短信验证码重置
- 用户自助修改邮箱

产物： openspec/specs/forgot-password/proposal.md

人类职责： 审核 proposal --- 范围是否准确？有没有遗漏什么？「不做」列表是否完整？

3.2 `/opsx:explore` --- 探索与细化

AI 分析现有代码，生成完整的 spec.md + design.md + tasks.md 三件套：

spec.md（行为规范）：

markdown 复制代码

# POST /api/auth/forgot-password
- Input: { email: string, pattern: ^\S+@\S+\.\S+$ }
- Output: { message: "重置链接已发送至邮箱" }
- Error: 404 用户不存在, 429 频率限制(同一邮箱 5 分钟1次)
- 注意：无论用户是否存在都返回相同消息（防止邮箱枚举攻击）

# GET /api/auth/reset-password/:token
- 验证 token 有效性
- 展示重置密码表单
- Error: 400 token 无效或已过期

# POST /api/auth/reset-password/:token
- Input: { password: string, minLength: 8 }
- 密码必须包含大小写字母 + 数字 + 特殊字符
- 成功后使 token 失效
- 返回 JWT 自动登录

design.md（技术设计）：

markdown 复制代码

## 架构
- 使用 nodemailer 发送邮件
- Token 使用 crypto.randomBytes(32) 生成，存入 Redis
- Token 有效期：30 分钟
- Redis key 格式：reset_token:{sha256(token)}

## 安全考量
- 使用 bcrypt 加密新密码
- Token 一次性使用，使用后立即删除
- 添加全局频率限制（每 IP 每小时 5 次）

## 组件
- ForgotPasswordForm.tsx       --- 邮箱输入表单
- ResetPasswordForm.tsx        --- 密码重置表单
- AuthController.resetPassword --- 后端控制器
- ResetTokenService            --- Token 管理服务

tasks.md（实施清单）：

markdown 复制代码

- [ ] 1.1 安装 nodemailer 和 Redis 客户端依赖
- [ ] 1.2 实现 ResetTokenService（生成、验证、过期）
- [ ] 1.3 编写 POST /api/auth/forgot-password 接口
- [ ] 1.4 编写 GET /api/auth/reset-password/:token 页面
- [ ] 1.5 编写 POST /api/auth/reset-password/:token 接口
- [ ] 1.6 添加 ForgotPasswordForm 前端组件
- [ ] 1.7 添加 ResetPasswordForm 前端组件
- [ ] 1.8 编写前后端单元测试
- [ ] 1.9 编写 E2E 测试

人类职责： 三审：

spec 是否覆盖了所有边界情况（错误状态、安全考量）？
design 的方案选择是否合理（为什么用 Redis 而不是 DB？）
tasks 粒度是否合适（每个 task 应在一次 Claude Code 对话内完成）？

3.3 `/opsx:apply` --- 实施

关键步骤：AI 严格按 tasks.md 逐条实现，每完成一条就 check：

bash 复制代码

✅ 1.1 安装 nodemailer 和 Redis 客户端依赖
✅ 1.2 实现 ResetTokenService（生成、验证、过期）
⬜ 1.3 编写 POST /api/auth/forgot-password 接口  ← 当前正在做
⬜ 1.4 编写 GET /api/auth/reset-password/:token 页面
⬜ 1.5 编写 POST /api/auth/reset-password/:token 接口
⬜ 1.6 添加 ForgotPasswordForm 前端组件
⬜ 1.7 添加 ResetPasswordForm 前端组件
⬜ 1.8 编写前后端单元测试
⬜ 1.9 编写 E2E 测试

这个阶段的人类参与原则：只审核，不改代码。

查看 AI 每次完成的 diff
spec 的实现是否偏离原始定义？
design 的方案有没有执行偏差？
如果有问题，回退到 /opsx:explore 修改 spec，再重新 apply

3.4 `/opsx:archive` --- 归档

实现完成后，将完整记录归档：

bash 复制代码

openspec/archive/2025Q2/forgot-password/
├── proposal.md
├── spec.md
├── design.md
└── tasks.md    ← 带 check 状态（✅ 表示完成）

归档的价值：

变更历史：任何时候回溯「为什么这么改」
知识复用：类似功能直接参考上次的 spec
审计追踪：谁、什么时候、改了什么、为什么

四、与 Claude Code 的集成方式

OpenSpec 本身不需要安装 MCP 服务器或 API Key，纯文件即可运行。有三种集成方式：

方式 A：CLAUDE.md（推荐）

在项目根目录的 CLAUDE.md 中声明 OpenSpec 工作流：

markdown 复制代码

# CLAUDE.md

## 工作流规则
1. 所有变更必须先生成 OpenSpec 文件
2. 除非是紧急修复，否则不要跳过 proposal 阶段
3. 实施前必须通过 /opsx:propose → /opsx:explore 流程
4. 实施时逐条遵循 tasks.md
5. 完成后运行 /opsx:archive

优点： Claude Code 自动加载，所有会话共享规则。

方式 B：`.claude/instructions/` 目录

markdown 复制代码

.claude/
└── instructions/
    └── openspec-workflow.md

内容与 CLAUDE.md 相近，优势在于是独立的文件，不会与项目约定的其他内容混在一起。

方式 C：Claude Code Skills

如果你使用 Claude Code 的 Skills 功能，可以将 OpenSpec 工作流封装成一个 skill：

bash 复制代码

.claude/skills/
└── openspec-workflow.md

Skill 文件可包含更详细的操作指南、模板和示例代码。

黄金组合

四种组件分工明确，可以一起使用：

bash 复制代码

OpenSpec       管「做什么 + 怎么做」
  ↓
CLAUDE.md      管「上下文约定」------ 技术栈、代码规范、架构风格
  ↓
.claude/skills/ 管「最佳实践模板」------ 可复用的编码模式
  ↓
.claude/rules/  管「每次对话自动加载的规则」------ 安全限制、命名规范

五、安装与初始化

5.1 安装 OpenSpec CLI

bash 复制代码

# 需要 Node.js ≥ 18.0.0（推荐 ≥ 20.19.0）
npm install -g @fission-ai/openspec@latest

# 验证安装
openspec --version

5.2 在项目中初始化

bash 复制代码

cd your-project
openspec init

这会创建 openspec/ 目录和 openspec/project.md 文件。然后你可以手动编辑 project.md 填写项目信息。

5.3 在 Claude Code 中使用

初始化完成后，启动 Claude Code：

bash 复制代码

claude

然后就可以使用 OPSX 命令了：

bash 复制代码

/opsx:propose "给用户模块加一个忘记密码功能"

⚠️ 注意： OpenSpec 通过 Claude Code 的 /opsx: 斜杠命令工作。如果你的 Claude Code 版本不支持斜杠命令，需要更新到最新版本。不同的 Claude Code 版本使用的命令前缀可能不同，请参考官方文档。

六、完整工作流全景图

bash 复制代码

你: "我想加一个夜间模式切换功能"

  ┌──────────────────────┐
  │ 1. /opsx:propose     │  ← 你说需求，AI 生成 proposal
  └──────────┬───────────┘
             ▼
  ┌──────────────────────┐
  │ 2. 你审核 proposal   │  ← 你做「Yes/No/修改」
  └──────────┬───────────┘
             ▼  Yes
  ┌──────────────────────┐
  │ 3. /opsx:explore     │  ← AI 生成 spec + design + tasks
  └──────────┬───────────┘
             ▼
  ┌──────────────────────┐
  │ 4. 你三审             │  ← 你审核 spec、design、tasks
  └──────────┬───────────┘
             ▼  OK
  ┌──────────────────────┐
  │ 5. /opsx:apply       │  ← AI 逐条实施 tasks
  └──────────┬───────────┘
             ▼
  ┌──────────────────────┐
  │ 6. 你 Code Review     │  ← 你检查 diff，提修改意见
  └──────────┬───────────┘
             ▼  OK
  ┌──────────────────────┐
  │ 7. /opsx:archive     │  ← 归档，版本化
  └──────────────────────┘

你: "PR 可以合并了"

七、常见问题 (FAQ)

Q1: OpenSpec 和普通的 Markdown 文档有什么区别？

区别在于结构化和可执行性。 普通 Markdown 文档是人读的，OpenSpec 的文件是 AI 可执行的------AI 能理解 proposal 中的范围定义、spec 中的输入输出规范、tasks 中的逐条实施清单，并严格按此执行。

Q2: 一定要装 CLI 才能用吗？

不必须。CLI 主要是为了初始化 openspec/ 目录和提供 init 命令。你可以手动创建 openspec/ 目录和文件，然后通过 Claude Code 的斜杠命令使用 OPSX 工作流。

Q3: 小改动也要走完整流程吗？

不需要。对于 3 行以内的 bug 修复或微调，可以使用快速通道：

/opsx:ff（fast-forward）：跳过 propose 和 explore，直接进入 apply
或者直接在 Claude Code 中描述需求，走常规聊天

Q4: Tasks 的粒度应该多大？

每个 task 应该能在一次 Claude Code 对话内完成，通常不超过 50 行代码。如果一个 task 超过 50 行，说明粒度太粗，应该进一步拆分。

Q5: 多人使用 Claude Code 时，OpenSpec 文件冲突怎么办？

建议：

不同人负责不同的 openspec/specs/<change-name>/ 目录
使用 Git 分支隔离变更
定期合并 archive 记录
在 project.md 中声明编码规范，确保所有人遵循相同约定

Q6: OpenSpec 只能和 Claude Code 一起用吗？

不是。OpenSpec 是纯文件协议，理论上可以与任何支持 Markdown 操作的 AI 编程工具配合使用。不过目前 OPSX 斜杠命令是专为 Claude Code 设计的。在其他工具中使用时，需要手动创建和编辑 OpenSpec 文件。

Q7: spec 写得太抽象怎么办？

spec 应该精确到能当验收测试写。一个检验标准：给一个不了解需求的工程师读 spec，他能写出准确的测试用例吗？ 如果不能，说明 spec 不够具体。

Q8: 跳过审核有什么后果？

OpenSpec 最大的价值就在「审核这步」。跳过审核等于放弃了整个流程的核心------人类对 AI 产出的质量控制。如果跳过，还不如直接用普通对话模式。

八、与 MCP 和 Hermes Agent 的关系

OpenSpec、MCP（Model Context Protocol）和 Hermes Agent 是三个不同层次的工具，可以组合使用：

css 复制代码

┌──────────────────────────────────────┐
│          OpenSpec（规范层）            │
│  「做什么 + 怎么做」的规范定义         │
└──────────────┬───────────────────────┘
               ↓
┌──────────────────────────────────────┐
│          Claude Code（执行层）         │
│  按 tasks.md 逐条实施                 │
│  通过 MCP 工具访问外部服务             │
└──────────────┬───────────────────────┘
               ↓
┌──────────────────────────────────────┐
│          MCP Servers（工具层）         │
│  Playwright MCP / 文件系统 MCP / ...  │
└──────────────┬───────────────────────┘
               ↓
┌──────────────────────────────────────┐
│          Hermes Agent（调度+记忆层）   │
│  Cron 定时任务 / 持久记忆 / 会话搜索   │
└──────────────────────────────────────┘

典型组合案例：

Hermes Agent 检测到仓库有新 Issue
分析 Issue 内容，生成 OpenSpec proposal
委派 Claude Code 执行 OPSX 流程
Claude Code 通过 MCP 工具访问数据库/浏览器
完成实施后归档，Hermes 通知用户

九、总结

OpenSpec 的核心价值可以用一句话概括：

用写文档的时间，换 debug 的时间。

阶段	时间	产出
传统方式	立即写代码 → 反复调试	工作时间全在 debug
OpenSpec 方式	10 分钟写 spec → 一次通过	高效、可追溯、可复用

什么时候该用： 任何超过半天的功能开发或重构。 什么时候不该用： 修复一行 typo、快速实验原型。

下一步，建议阅读 OpenSpec 实战指南：从规范到代码的完整工作流，看一个完整的前后端功能开发案例。

本文基于 OpenSpec v0.x + Claude Code 的最新版本。工具版本更新较快，建议关注 openspec.dev 获取最新文档。

OpenSpec 基础概念与 OPSX 工作流：AI 时代的规范驱动开发