OpenSpec 简明教程

1. 是什么

OpenSpec 是一个规范驱动开发 工具，专为 AI 编码助手设计。核心理念很简单：写代码前，先让人类和 AI 对"要做什么"达成一致。

它解决的是"凭感觉聊天"式开发的痛点------需求散落在聊天记录里，AI 容易遗漏需求或偏离预期。OpenSpec 通过轻量级的规范流程，把模糊提示变成可审查、可落地的工程计划。

核心结构：

ini 复制代码

openspec/
├── specs/        # 已实现的功能（真相之源）
└── changes/      # 待实现的提案
    └── [变更名]/
        ├── proposal.md   # 为什么要做、做什么
        ├── design.md     # 技术方案
        ├── tasks.md      # 实施清单
        └── specs/        # 规范增量（补丁）

2. 快速上手

环境要求： Node.js 20.19.0 或更高版本

安装与初始化：

bash 复制代码

# 全局安装
npm install -g openspec-cn/openspec

# 进入项目目录
cd your-project

# 初始化
openspec init

初始化会创建 openspec/ 目录结构，并根据你的 AI 工具配置对应的斜杠命令。

3. 核心工作流

OpenSpec 采用四步工作流，全程通过斜杠命令与 AI 交互：

命令	阶段	功能
`/opsx:new`	规划	创建新变更，生成首个工件模板
`/opsx:ff`	规划	"快进"------一次性生成所有规划文档
`/opsx:apply`	实施	按任务清单实现代码
`/opsx:archive`	收尾	归档已完成变更，更新主规范

实操示例（以"添加深色模式"为例）：

bash 复制代码

# 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 获取工作流指引