1. 是什么
OpenSpec 是一个规范驱动开发工具，专为 AI 编码助手设计。核心理念很简单：写代码前，先让人类和 AI 对“要做什么”达成一致。
它解决的是“凭感觉聊天”式开发的痛点——需求散落在聊天记录里，AI 容易遗漏需求或偏离预期。OpenSpec 通过轻量级的规范流程，把模糊提示变成可审查、可落地的工程计划。
核心结构：
openspec/
├── specs/ # 已实现的功能（真相之源）
└── changes/ # 待实现的提案
└── [变更名]/
├── proposal.md # 为什么要做、做什么
├── design.md # 技术方案
├── tasks.md # 实施清单
└── specs/ # 规范增量（补丁）
2. 快速上手
环境要求： Node.js 20.19.0 或更高版本
安装与初始化：
# 全局安装
npm install -g openspec-cn/openspec
# 进入项目目录
cd your-project
# 初始化
openspec init
初始化会创建 openspec/ 目录结构，并根据你的 AI 工具配置对应的斜杠命令。
3. 核心工作流
OpenSpec 采用四步工作流，全程通过斜杠命令与 AI 交互：
| 命令 | 阶段 | 功能 |
|---|---|---|
/opsx:new | 规划 | 创建新变更，生成首个工件模板 |
/opsx:ff | 规划 | “快进”——一次性生成所有规划文档 |
/opsx:apply | 实施 | 按任务清单实现代码 |
/opsx:archive | 收尾 | 归档已完成变更，更新主规范 |
实操示例（以“添加深色模式”为例）：
# 1. 创建变更
/opsx:new add-dark-mode
→ 创建 openspec/changes/add-dark-mode/
# 2. 生成全部规划文档
/opsx:ff
→ ✓ proposal.md ✓ specs/ ✓ design.md ✓ tasks.md
# 3. 开始实施
/opsx:apply
→ 逐步完成 tasks.md 中的任务清单
# 4. 归档
/opsx:archive
→ 移至 changes/archive/，更新 specs/
4. 命令速查
斜杠命令（AI 对话）
| 命令 | 读/写 | 用途 |
|---|---|---|
/opsx:explore | 只读 | 探索想法、调研问题 |
/opsx:new | 写入 | 创建新变更 |
/opsx:continue | 写入 | 逐个创建工件 |
/opsx:ff | 写入 | 一次性创建所有工件 |
/opsx:apply | 写入 | 按任务清单实现代码 |
/opsx:verify | 只读 | 验证实现与规范的一致性 |
/opsx:archive | 写入 | 归档已完成变更 |
CLI 命令（终端）
| 命令 | 用途 |
|---|---|
openspec list | 列出进行中的变更 |
openspec list --specs | 列出所有规范 |
openspec show [item] | 查看变更/规范详情 |
openspec validate [item] | 验证变更/规范格式 |
openspec archive <id> --yes | 非交互式归档 |
5. 关键原则
1. 棕地优先 —— 不要求从零开始，与存量项目完美兼容
2. 规范即真相 —— specs/ 是已实现功能的唯一真相源，changes/ 是待实施的提案
3. 增量变更 —— 每个变更独立成文件夹，归档后合并回主规范，历史清晰可追溯
4. 人在回路 —— AI 生成提案后必须经过人工审查确认，再进入实施阶段
6. 支持的工具
OpenSpec 支持 20+ AI 编码助手，包括：
- 原生斜杠命令：Claude Code、Cursor、GitHub Copilot、Windsurf、CodeBuddy
- AGENTS.md 兼容：其他工具可读取
openspec/AGENTS.md获取工作流指引
