OpenSpec 是什么？怎么正确使用？ - 计算机软件技术总结

OpenSpec 是什么？

OpenSpec 是 Fission-AI/OpenSpec 开源项目的中文名称，是一个专为 AI 编码助手设计的规范驱动开发框架（Spec-driven Development，简称 SDD）。它能帮助开发者和 AI 在写代码之前先就"要构建什么"达成一致。

核心价值

AI 编码助手很强大，但当需求只存在于聊天记录中时，结果往往不可预测。OpenSpec 添加了一个轻量级的规范层。

关键特点

特点	说明
🤝 构建前先对齐	人类和 AI 在写代码之前先在规范上达成一致
📁 保持井然有序	每个变更都有独立的文件夹，包含提案、规范、设计和任务
🔄 流畅迭代	可随时更新任何产物，没有僵化的阶段门控
🛠 兼容多工具	支持 25+ 种 AI 编码助手（Claude Code、Cursor、Windsurf 等）

正确使用 OpenSpec

1. 安装

前置要求： Node.js 20.19.0 或更高版本

# 全局安装
npm install -g @fission-ai/openspec@latest

# 或使用 pnpm/yarn/bun
pnpm add -g @fission-ai/openspec@latest

2. 初始化项目

cd your-project
openspec init

这会在项目中创建 OpenSpec 目录结构：

openspec/
├── specs/              # 真实来源（系统当前行为）
│   └── <domain>/
│       └── spec.md
├── changes/           # 提案的变更（每个变更一个文件夹）
│   └── <change-name>/
│       ├── proposal.md   # 为什么做，做什么
│       ├── design.md     # 怎么做（技术方案）
│       ├── tasks.md      # 实现检查清单
│       └── specs/        # 增量规范
└── config.yaml        # 项目配置

3. 核心工作流

默认快速路径（core profile）：

/opsx:propose ──► /opsx:apply ──► /opsx:archive

扩展工作流（需要手动启用）：

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

4. 使用示例

Step 1：提出变更

你: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — 为什么做，变更什么
     ✓ specs/       — 需求和场景
     ✓ design.md    — 技术方案
     ✓ tasks.md     — 实现检查清单
     Ready for implementation!

Step 2：执行实现

你: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     All tasks complete!

Step 3：归档变更

你: /opsx:archive

AI:  ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

5. 增量规范（Delta Specs）格式

规范使用 ADDED/MODIFIED/REMOVED 标记变更类型：

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

归档时发生的事：

ADDED → 追加到主规范
MODIFIED → 替换现有版本
REMOVED → 从主规范中删除

6. 常用命令参考

命令	用途	何时使用
/opsx:propose	创建变更 + 规划产物	默认快速路径
/opsx:explore	思考想法，调查问题	需求不明确时
/opsx:new	开始变更脚手架	扩展模式，显式控制
/opsx:ff	一次性创建所有规划产物	需求清晰，快速执行
/opsx:apply	实现任务	准备写代码时
/opsx:verify	验证实现是否符合规范	归档前检查
/opsx:archive	完成变更并归档	所有工作完成时

7. CLI 工具

# 查看活跃变更
openspec list

# 查看变更详情
openspec show add-dark-mode

# 验证规范格式
openspec validate add-dark-mode

# 交互式仪表板
openspec view

# 更新 AI 指导
openspec update

# 启用扩展工作流
openspec config profile

工作流模式选择

场景	推荐命令
需求清晰，直接开干	/opsx:propose → /opsx:apply → /opsx:archive
需求不明确，需要调研	/opsx:explore → /opsx:new → /opsx:continue
多个变更并行进行	/opsx:bulk-archive 批量归档