openSpec 详细介绍以及使用

OpenSpec 是一个用于 AI 辅助编程的规范驱动开发（Spec-Driven Development, SDD）框架和命令行工具。它的核心目标是解决与 AI 结对编程时常见的“需求偏移”和“AI 幻觉”问题，将开发模式从依赖模糊提示的“vibe coding”转变为基于清晰规范的工程化流程。

简单来说，OpenSpec 要求在写任何代码之前，先与 AI 就“要构建什么”达成一份正式的、机器可读的协议（即规范），这份规范将成为开发过程中的“唯一真相源”。

💡 为什么需要 OpenSpec？

在传统的 AI 辅助编程中，需求常常散落在聊天记录里，导致 AI 容易误解意图、遗漏细节或添加多余功能，带来不可预测的结果。OpenSpec 通过引入结构化的规范，为开发流程带来了确定性、可审计性和可控性，让 AI 从一个有创意的“协作者”转变为严格执行计划的“工程师”。

🚀 如何使用 OpenSpec？

OpenSpec 的使用遵循一个清晰的“提案-审查-实施-归档”四阶段工作流。它将项目状态（specs/）和提议的变更（changes/）清晰地分离开来。

1. 核心目录结构

初始化后，你的项目根目录下会生成一个 openspec/ 文件夹，其结构如下：

text

openspec/
├── project.md          # 项目整体上下文、技术栈和编码约定
├── specs/              # “唯一真相源”。存放项目当前已实现功能的最终规范。
│   └── [功能名称]/
│       └── spec.md
└── changes/            # 所有进行中或已完成的变更都存放在这里。
│   ├── [变更名称]/     # 一个具体的变更（如 add-login-api）
│   │   ├── proposal.md # 变更提案：为什么要做，做什么，影响范围
│   │   ├── tasks.md    # AI 实施的详细检查清单
│   │   ├── design.md   # (可选) 技术设计决策
│   │   └── specs/      # 此变更对规范的“增量更新”
│   │       └── [功能名称]/
│   │           └── spec.md # 仅包含 ADDED/MODIFIED/REMOVED 的部分
│   └── archive/        # 已完成的变更会被移入此归档目录

2. 四阶段工作流

整个流程可以让你和 AI 高效协作：

flowchart TD
    A[“1. 起草提案
（开发者发起）”] --> B[“2. 审查与对齐
（开发者与AI协作）”]
    B -- 批准计划 --> C[“3. AI驱动实施
（AI执行任务清单）”]
    C --> D[“4. 归档并更新真相源
（AI或开发者执行）”]
    D -.-> A

起草提案 (Draft)：你通过自然语言（如“创建一个用户登录功能的OpenSpec提案”）或AI助手内置的 /openspec:proposal 命令发起一个变更。AI 会自动在 changes/ 目录下创建对应的文件夹和 proposal.md、tasks.md 等文件。
审查与对齐 (Review)：你和团队审查 AI 生成的提案和规范增量，可以通过 AI 对话或直接编辑文件来修改，直到这个计划完全符合你的预期。可以使用 openspec validate <变更名> 命令检查规范格式。
AI 驱动实施 (Implement)：计划锁定后，你通过 /openspec:apply <变更名> 命令或告诉 AI“开始实施”。此时，AI 会严格遵循 tasks.md 中的清单来编写代码，而不会自行发挥，从而确保产出与计划一致。
归档并更新真相源 (Archive)：实施完成并验证通过后，执行 /openspec:archive <变更名> 命令。OpenSpec 会将本次变更中对规范的修改合并到 specs/ 目录下的主规范文件中，并将整个变更文件夹移至 changes/archive/。这标志着项目“真相源”的正式更新。

🛠️ 快速开始

安装 CLI 工具：
确保你的系统已安装 Node.js (>= 20.19.0)，然后在终端全局安装 OpenSpec ：bashnpm install -g @fission-ai/openspec@latest
在项目中初始化：
进入你的项目根目录，运行以下命令，并根据提示选择你使用的 AI 工具（如 Cursor, Copilot等）：bashopenspec init
开始第一个变更：
在你的 AI 聊天界面中（如 Cursor），输入 /openspec-proposal 你的功能描述，即可开始第一个规范驱动的开发流程。

⚙️ 主要命令

OpenSpec 的命令分为两类：你直接操作的终端命令 和 你在 AI 聊天界面中使用的斜杠命令。

命令类型	常用命令	主要作用
终端命令 (CLI)	`openspec list`	查看所有进行中的变更及任务进度。
	`openspec validate <change>`	验证某个变更的规范格式是否正确。
	`openspec archive <change>`	归档一个已完成并验证的变更。
AI 斜杠命令	`/openspec-proposal`	让 AI 为一个新功能创建变更提案（包括目录和文件）。
	`/openspec-apply`	让 AI 根据已批准的提案和任务清单开始编写代码。
	`/openspec-archive`	让 AI 执行归档操作，将变更合并到主规范中。