OpenSpec (opsx) 使用指南
OpenSpec 是一个为 AI 编码助手设计的规范驱动开发工具，它通过轻量级的工作流程，确保人类开发者和 AI 助手在编写任何代码之前就能对需求达成明确共识。
为什么需要 OpenSpec？
传统 AI 编码助手的问题
- AI 根据模糊提示生成不符合需求的代码
- 遗漏重要功能要求
- 添加了不必要的功能
- 代码行为不可预测
OpenSpec 的解决方案
| 特性 | 说明 |
|---|---|
| 明确共识 | 在编码前确定所有要求 |
| 结构化变更 | 所有相关文档集中管理 |
| 可审查输出 | AI 根据明确规范生成代码 |
| 版本控制 | 完整追踪所有变更历史 |
安装和初始化
系统要求
- Node.js >= 20.19.0
- 支持的 AI 编码助手（Claude Code、Cursor、OpenCode 等）
安装
npm install -g @fission-ai/openspec@latest
验证安装
openspec --version
初始化项目
cd your-project-directory
openspec init
初始化过程会：
- 询问您使用的 AI 工具（Claude Code、Cursor 等）
- 自动配置相应的斜杠命令
- 创建
.openspec/目录结构 - 生成
AGENTS.md文件
核心概念
目录结构
openspec/
├── AGENTS.md # AI 助手使用指南（自动生成）
├── project.md # 项目专属上下文信息（技术栈、编码规范）
├── specs/ # 权威基准：当前已部署的功能能力
│ └── [capability]/ # 示例：用户认证、支付处理
│ ├── spec.md # 需求说明与场景描述
│ └── design.md # （可选）技术实现模式
├── changes/ # 提案集：正在进行中的活跃工作
│ ├── [change-name]/ # 示例：新增谷歌登录功能
│ │ ├── proposal.md # 提案背景、核心内容与影响评估
│ │ ├── tasks.md # 实现任务清单（检查项）
│ │ ├── design.md # （可选）架构决策文档
│ │ └── specs/ # 增量规格说明
│ └── archive/ # 已完成变更的历史归档
规范格式
规范使用 Markdown 格式，包含：
# Auth Specification
## Purpose
Authentication and session management.
## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT on successful login.
#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned
变更差异（Delta）格式
变更通过”差异”格式显示：
# Delta for Auth
## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.
#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required
## MODIFIED Requirements
### Requirement: User Authentication
[完整更新后的内容]
## REMOVED Requirements
### Requirement: Legacy Login
[已废弃的功能描述]
命令详解
OpenSpec 的命令可以分为 CLI 命令 和 Command 命令 两类。
CLI 命令
CLI 命令用于管理配置或项目：
| 类型 | 命令 | 用途 |
|---|---|---|
| Setup | init, update |
在项目中初始化和更新 OpenSpec |
| Browsing | list, view, show |
探索变更和规格 |
| Validation | validate |
检查变更和规格的问题 |
| Lifecycle | archive |
完成已完成的更改 |
| Workflow | status, instructions, templates, schemas |
支持构建驱动工作流程 |
| Config | config |
查看和修改设置 |
常用 CLI 命令示例
# 查看所有活动变更
openspec list
# 交互式规范仪表板
openspec view
# 显示变更详情
openspec show <change-name>
# 验证规范格式
openspec validate <change-name>
# 归档变更
openspec archive <change-name> --yes
# 刷新 AI 指导
openspec update
Command 命令（斜杠命令）
Command 命令用于与 AI 协作，引导 AI 规划和执行 Spec：
| 命令 | 说明 |
|---|---|
/opsx:explore |
进入探索模式——思考各种想法，研究问题，明确需求 |
/opsx:new |
使用实验性工件工作流开始新的变更操作 |
/opsx:continue |
恢复上一个功能点，继续进行变更工作 |
/opsx:ff |
一步到位，一次性创建变更并生成实施所需的所有文件 |
/opsx:apply |
执行来自 OpenSpec 更改的任务（开始编码） |
/opsx:verify |
在归档之前，核实实施情况与变更工件是否一致 |
/opsx:sync |
将变更后的详细规格同步至主规格中 |
/opsx:archive |
在实验工作流程中归档已完成的变更 |
/opsx:bulk-archive |
一次归档多个已完成的更改 |
/opsx:onboard |
启动引导流程 |
注意：
/opsx:explore和/opsx-explore是等价的，可以使用冒号或连字符。
支持的 AI 工具
| 工具 | 命令格式 |
|---|---|
| Claude Code | /openspec:proposal, /openspec:apply, /openspec:archive |
| Cursor | /openspec-proposal, /openspec-apply, /openspec-archive |
| OpenCode | /openspec-proposal, /openspec-apply, /openspec-archive |
| GitHub Copilot | /openspec-proposal, /openspec-apply, /openspec-archive |
| Amazon Q Developer | @openspec-proposal, @openspec-apply, @openspec-archive |
| Cline | 在 .clinerules/ 目录中的规则 |
完整工作流程
OpenSpec 强制实施严格的三阶段工作流程，以防止需求漂移。
第 1 阶段：创建变更（提案）
这个阶段在将资源投入到”如何”之前，强制要求在”做什么”和”为什么”上保持一致。
要做的事情：
- 识别需求：新功能、重构或架构转变
- 脚手架：在
openspec/changes/<change-id>/下创建唯一目录 - 定义规范：为相关功能编写增量（添加、修改、删除）
- 计划：创建
tasks.md文件，将工作分解成可验证的步骤 - 验证：使用
openspec validate确保提案在结构上是合理的
操作步骤：
# 方式1：逐步创建
/opsx:explore 创建项目架构 # 探索模式，明确需求
/opsx:new # 开始创建变更
# 然后 AI 会依次创建 proposal、design、specs、tasks
# 方式2：一步到位
/opsx:ff {功能名称} # 一次性创建所有文件
第 2 阶段：实施
这是编码阶段，AI 会根据前面创建的 Spec 去执行编码任务。
工作步骤：
- 上下文加载：AI 读取
proposal.md和规范以理解需求 - 执行：AI 按顺序处理
tasks.md - 跟踪：任务实时标记为已完成
操作步骤：
# 开始实施
/opsx:apply {change-name}
# 如果上下文太长需要新开对话，可以恢复进度
/opsx:continue {change-name}
# 实施完成后验证
/opsx:verify {change-name}
第 3 阶段：归档（集成）
一旦代码部署并验证，变更提案就不再是”提案”，而是现实代码了。
操作步骤：
# 归档已完成的更改
/opsx:archive {change-name}
# 或使用 CLI
openspec archive {change-name} --yes
归档会：
- 将 change 文件夹移动到
openspec/changes/archive/ - 自动将规范增量应用于
openspec/specs/目录
完整使用流程示例
示例：添加用户资料搜索过滤功能
步骤 1：探索需求
/opsx:explore 添加按角色和团队过滤的用户资料搜索功能
与 AI 讨论，明确具体需求和技术方案。
步骤 2：创建变更提案
/opsx:new add-profile-filters
AI 会创建以下文件：
openspec/changes/add-profile-filters/proposal.mdopenspec/changes/add-profile-filters/tasks.mdopenspec/changes/add-profile-filters/specs/
步骤 3：验证和审查
# 确认变更文件夹存在
openspec list
# 验证规范格式
openspec validate add-profile-filters
# 审查提案详情
openspec show add-profile-filters
步骤 4：完善规范
能否为角色和团队过滤器添加验收标准？
AI 更新相应的规范差异和任务列表。
步骤 5：实施变更
/opsx:apply add-profile-filters
AI 按任务清单逐步实施，并标记完成状态。
步骤 6：验证实施
/opsx:verify add-profile-filters
步骤 7：归档
/opsx:archive add-profile-filters
常见使用场景
1. 新功能开发
/opsx:explore 新功能描述
/opsx:new feature-name
/opsx:apply feature-name
/opsx:verify feature-name
/opsx:archive feature-name
2. 代码重构
/opsx:explore 重构目标和范围
/opsx:new refactor-module-name
# ... 后续步骤同上
3. Bug 修复
/opsx:new fix-bug-description
# 在 proposal 中详细描述问题原因和修复方案
/opsx:apply fix-bug-description
4. 架构调整
/opsx:explore 架构调整方案
# 充分讨论后再创建变更
/opsx:new architecture-update
最佳实践
1. 小步快跑
不要在一个 change 中做太多事情，建议按模块/功能点逐步迭代：
✅ 好：add-user-auth
✅ 好：add-dark-mode
❌ 不好：add-all-features-at-once
2. 充分探索
在创建变更之前，使用 /opsx:explore 充分讨论需求和方案。
3. 保持上下文同步
如果修改了已归档的规范，使用 /opsx:sync 同步更新：
/opsx:sync {change-name}
4. 团队协作
- 不同团队成员可以使用不同的 AI 工具
- 共享相同的规范文件
- 切换工具时运行
openspec update
5. 项目上下文配置
初始化后，完善 project.md 文件：
# Project Context
## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
## Code Conventions
- 使用 TypeScript 严格模式
- 组件名使用 PascalCase
- 函数名使用 camelCase
常见问题
Q1: AI 助手没有显示新的斜杠命令？
A: 重启 AI 编码助手，然后运行 openspec update 刷新指导。
Q2: 上下文太长怎么办？
A: 新开对话后使用 /opsx:continue {change-name} 恢复进度。
Q3: 可以同时处理多个变更吗？
A: 是的，OpenSpec 支持同时存在多个变更提案，但建议一次只应用一个。
Q4: 如何修改已归档的规范？
A: 创建一个新的变更提案，通过相同的流程来更新现有规范。
Q5: 规范格式要求？
A:
- 使用
### Requirement:作为标题 - 每个要求至少需要一个
#### Scenario:块 - 在要求文本中使用 SHALL/MUST