OpenSpec 简明教程

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 交互：

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

# 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 对话）

CLI 命令（终端）

5. 关键原则

1. 棕地优先 —— 不要求从零开始，与存量项目完美兼容

2. 规范即真相 —— specs/ 是已实现功能的唯一真相源，changes/ 是待实施的提案

3. 增量变更 —— 每个变更独立成文件夹，归档后合并回主规范，历史清晰可追溯

4. 人在回路 —— AI 生成提案后必须经过人工审查确认，再进入实施阶段

6. 支持的工具

OpenSpec 支持 20+ AI 编码助手，包括：

• 原生斜杠命令：Claude Code、Cursor、GitHub Copilot、Windsurf、CodeBuddy
• AGENTS. md 兼容：其他工具可读取 openspec/AGENTS.md 获取工作流指引