一、openspec

1.使用指南

openspec是一个轻量级的规范驱动(spec-driven development)框架，专为AI编码助手设计。
核心理念：先写规范，再写代码。让AI在明确的“契约”下工作，避免模糊提示导致的需求偏移。

2.安装与初始化

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

# 检查 Node.js 版本
node --version

# 全局安装 OpenSpec（中文版）
npm install -g @studyzy/openspec-cn

# 或安装英文原版
npm install -g @fission-ai/openspec@latest

进入项目根目录并初始化：

cd your-project
openspec-cn init

初始化时会提示选择你使用的 AI 工具（Cursor、Claude Code、GitHub Copilot 等），选择后会自动生成对应的斜杠命令配置。
初始化后生成的目录结构：

openspec/
├── specs/           # 当前系统规范（已构建的内容）
│   └── [capability]/
│       └── spec.md
├── changes/         # 提案变更（待实施的内容）
│   ├── [change-name]/
│   │   ├── proposal.md   # 变更说明
│   │   ├── tasks.md      # 实施清单
│   │   ├── design.md     # 技术方案（可选）
│   │   └── specs/        # 规范增量
│   └── archive/     # 已完成的变更
└── AGENTS.md        # AI 助手的操作指南

3.核心工作流

OpenSpec 采用四阶段工作流，通过斜杠命令在 AI 助手的聊天面板中操作：

注意：命令的具体名称可能因工具而异。在 Cursor 中可能是 /opsx:propose，在 GitHub Copilot 中可能是 /openspec-proposal。初始化时会自动生成对应格式。

4.实战示例：构建一个厨房计时器

以创建一个简单的厨房计时器为例，演示完整流程：

步骤 1：编辑项目上下文
初始化后，编辑 openspec/project.md，描述项目目的和技术栈：

# 项目目的
提供一个简单、高可见性的厨房计时器，用于家庭和商用厨房。

## 功能需求
- 提供 1分钟、3分钟、5分钟 按钮
- 按下按钮开始倒计时
- 倒计时期间显示剩余时间
- 倒计时中再次按下按钮，重置并重新开始

## 技术栈
- HTML5 / CSS3 / JavaScript (ES6)

步骤 2：创建提案
在 AI 聊天面板中输入：

/opsx:propose 创建一个厨房计时器 UI

AI 会自动在 openspec/changes/create-ui/ 目录下生成以下文件：

proposal.md：变更摘要、动机、范围

tasks.md：实施清单（搭建 HTML/CSS/JS、实现计时逻辑等）

spec.md：规范增量（需求描述、测试场景）

步骤 3：审查与迭代
检查生成的提案和规范是否准确
如有遗漏，直接在 AI 聊天中说明，AI 会自动修改
也可以手动编辑 Markdown 文件进行微调

步骤 4：实施
提案确认后，执行：

/opsx:apply

AI 会按照 tasks.md 中的清单逐项实施，生成完整的代码。

步骤 5：归档
验证功能正常后：

/opsx:archive

该变更会被移动到 openspec/changes/archive/，规范增量合并到 openspec/specs/ 主目录。

5.核心概念深度解析

(1)为什么需要 OpenSpec？

传统"凭感觉聊天（Vibe Coding）"的问题：

• 需求只存在于聊天记录中，不可追溯
• AI 经常遗漏需求或添加不需要的功能
• 反复返工，效率低下
  OpenSpec 通过结构化的规范文档，让 AI 在编码前就锁定意图

(2)specs/ 与 changes/ 的分离

这是 OpenSpec 的核心架构：

这种设计让 AI 有两个清晰的上下文：

• 稳定参考：specs/ 中的规范
• 当前任务：changes/ 中的提案

(3)规范增量（Delta）格式

在 changes/[name]/specs/ 中，使用增量标记描述变更：

## 新增需求

### 需求：计时器 UI
计时器 UI 应提供直观的操作界面。

#### 场景：用户启动计时器
- 当用户点击"1分钟"按钮
- 则倒计时显示 01:00
- 且开始倒计时

## 修改需求
（原有规范中需要修改的部分）

## 移除需求
（原有规范中需要删除的部分）

每个需求至少包含一个 #### 场景： 块。

6.常用命令参考

CLI 命令（终端）

AI 聊天命令（在 AI 助手中输入）

7.最佳实践

1.何时创建提案：新功能、重大变更、架构调整、性能优化（改变行为时）
2.何时跳过提案：Bug 修复（恢复预期行为）、拼写错误、注释、依赖更新（非重大变更）、配置调整
3.change-id 命名规范：短横线命名，动词开头
✅ add-dark-mode
✅ update-api-rate-limit
✅ remove-legacy-module
❌ dark_mode（下划线）
❌ new-feature（动词不明确）

4.验证后再实施：在运行 /opsx:apply 之前，先运行 openspec-cn validate --strict 确保规范格式正确

5.保持上下文干净：OpenSpec 受益于干净的上下文窗口，开始实施前建议清除聊天历史

8.支持的 AI 工具

OpenSpec 支持 20+ 种 AI 编码助手：
Cursor
Claude Code
GitHub Copilot
Windsurf
Codex
Gemini CLI
Amazon Q Developer等
初始化时会自动生成对应工具的斜杠命令配置。

9.版本更新

# 升级 OpenSpec
npm install -g @studyzy/openspec-cn@latest

# 刷新项目中的 AI 指令（每个项目都需要执行）
cd your-project
openspec-cn update

update 命令只会更新标记 和 之间的内容，保留用户自定义配置

10.总结

OpenSpec 的核心价值在于用工程纪律约束 AI 的创造性，让开发过程从"凭感觉聊天"转向"基于规范开发"。它特别适合：

• 已有项目的功能迭代（棕地优先）
• 多人协作的 AI 辅助开发
• 需要变更可追溯的生产级项目
  如果你是第一次使用，建议从一个简单功能（如"添加一个按钮"）开始体验完整流程。