openspec 是什么？怎么正确使用？

OpenSpec 是什么？

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

核心价值

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

关键特点

正确使用 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. 常用命令参考

7. CLI 工具

# 查看活跃变更
openspec list

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

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

# 交互式仪表板
openspec view

# 更新 AI 指导
openspec update

# 启用扩展工作流
openspec config profile

工作流模式选择

与其他工具对比

注意事项

1. 模型选择：OpenSpec 在高推理模型上效果最佳，推荐 Opus 4.5 和 GPT 5.2
2. 上下文卫生：保持上下文窗口干净，开始实现前清除上下文
3. 变更命名：清晰的命名让 openspec list​ 更有用（如 add-dark-mode​ 而非 feature-1）
4. 保持聚焦：一个逻辑工作单元一个变更，避免 scope 蔓延

官网：https://openspec.dev/
Discord：https://discord.gg/YctCnvvshC
GitHub：https://github.com/Fission-AI/OpenSpec ⭐ 48.6k