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

2026-06-06 AI 开发方法论 AI 开发方法论, OPSX, OpenSpec, 教程 0

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 在你的项目里生成如下文件结构：

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 示例

# 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：

对话示例：

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

# Proposal: 忘记密码功能

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

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

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

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

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

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

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

spec.md（行为规范）：

# 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（技术设计）：

## 架构
- 使用 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（实施清单）：

- [ ] 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：

✅ 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` — 归档

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

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 工作流：

# CLAUDE.md

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

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

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

1
2
3

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

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

方式 C：Claude Code Skills

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

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

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

黄金组合

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

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

五、安装与初始化

5.1 安装 OpenSpec CLI

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

# 验证安装
openspec --version

5.2 在项目中初始化

1 2	cd your-project openspec init

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

5.3 在 Claude Code 中使用

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

claude

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

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

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

六、完整工作流全景图

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

  ┌──────────────────────┐
  │ 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 是三个不同层次的工具，可以组合使用：

┌──────────────────────────────────────┐
│          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 获取最新文档。

本文链接： https://www.geniux.top/article/78edbcc1f25d/

版权声明： 本博客所有文章除特别声明外，均采用 CC BY 4.0 CN协议许可协议。转载请注明出处！

CaoZHProgrammer

学习使我快乐。

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

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

一、简介

1.1 什么是 OpenSpec？

1.2 为什么要用 OpenSpec？

1.3 适用场景

二、核心文件结构

2.1 各文件职责

2.2 project.md 示例

三、OPSX 工作流详解

3.1 /opsx:propose — 提出变更

3.2 /opsx:explore — 探索与细化

3.3 /opsx:apply — 实施

3.4 /opsx:archive — 归档

四、与 Claude Code 的集成方式

方式 A：CLAUDE.md（推荐）

方式 B：.claude/instructions/ 目录

方式 C：Claude Code Skills

黄金组合

五、安装与初始化

5.1 安装 OpenSpec CLI

5.2 在项目中初始化

5.3 在 Claude Code 中使用

六、完整工作流全景图

七、常见问题 (FAQ)

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

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

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

Q4: Tasks 的粒度应该多大？

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

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

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

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

八、与 MCP 和 Hermes Agent 的关系

九、总结

CaoZHProgrammer

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

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

3.3 `/opsx:apply` — 实施

3.4 `/opsx:archive` — 归档

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