技术知识库

主题

OpenSpec 指南 ​

目录 ​

  1. 什么是 OpenSpec
  2. 安装与初始化
  3. 扩展工作流
  4. 分阶段流程详解

1. 什么是 OpenSpec ​

OpenSpec 是一个 AI 辅助开发的结构化工作流工具。它通过一系列斜杠命令（/opsx:）引导开发者与 AI 协作，从需求探索、规划、编码到验证、归档，每一步都清晰可控，避免沟通偏差，提升开发效率和质量。

OpenSpec 的核心思想是 “先约定，后编码” —— 在写代码前，先与 AI 共同明确需求、设计规范、拆解任务；代码实现后，再验证其是否符合约定，最后归档变更，形成可追溯的历史记录。

2. 安装与初始化 ​

2.1 安装 ​

bash
npm install -g @fission-ai/openspec@latest

2.2 初始化 ​

bash
openspec init

初始化的时候，会询问添加到哪个 AI 工具，选择 claude code。项目根文件会新建 .claude 文件。

初始化后项目根生成 .claude 目录，内含 commands 与 skills，skills 内是 openspec-apply-change、openspec-explore 等工作流

重启 claude code 之后，输入 /opsx: 可以看到四个命令，分别对应着：执行、创建变更 + 生成规划、探索和归档。也就是最基础的 探索 → 规划 → 执行 → 归档 四个阶段。

输入 /opsx: 后列出 /opsx:apply、/opsx:propose、/opsx:explore、/opsx:archive 四个命令

3. 扩展工作流 ​

除了基础的四个命令，还可以使用命令扩展工作流。

3.1 运行 ​

bash
openspec config profile

运行 openspec config profile 后显示当前 Delivery 与 Workflows 设置，并提示选择 Delivery and workflows

选择 Delivery and workflows。

Delivery：决定了这些命令将如何打包安装给 AI 工具去识别和执行，有 Skills 和 Commands 两种模式。（如果使用 Codex APP 或者插件，需要开启 Skills，安装后使用 $ 调用对应的 skills，记得先重启 Codex）

workflows：决定了你有哪些命令可用，通过 workflows 开启扩展的工作指令。

3.2 选择 Both (skills + commands) ​

同时支持 skills 和 commands 两种方式，这种方式兼容性最好，能适配绝大多数 AI 工具。如果习惯使用 claude code 指令的，也可选择 “commands only”。

Delivery mode 选择界面：Both (skills + commands) 为当前项，另有 Skills only 与 Commands only

3.3 勾选扩展指令 ​

除了默认的四个命令外，再勾选 Verify change，也可全部勾选。默认的 propose 包含了 New change、Continue change、Fast-forward 功能。

使用空格勾选指令，并按回车确认。

Select workflows to make available 界面：Propose、Explore、New、Continue、Apply、Fast-forward、Sync、Archive、Bulk archive、Verify、Onboard 全部勾选

4. 分阶段流程详解 ​

4.1 探索阶段：/opsx:explore ​

在动手写代码前，与 AI 进行纯粹的讨论，分析需求、调研技术方案、梳理潜在风险。

命令：

text
/opsx:explore

行为：AI 进入“只读模式”，不会创建任何文件，只生成讨论性回答。

输出：通常是一段对话记录，可手动保存到项目文档中作为参考。

4.2 规划阶段 ​

规划阶段的目标是产出清晰的提案、规范、设计和任务清单，作为后续编码的依据。

一次性规划 ​

命令：

text
/opsx:propose

行为：在 changes/ 下创建一个以当前时间戳命名的新目录，并生成基础文件框架。

规划阶段产出物：

  • proposal.md：描述变更的背景、目标、验收标准。
  • specs/：存放与该变更相关的详细规范（接口设计、数据结构、UI 约定等）。
  • design.md：技术设计方案，包括模块划分、关键算法、依赖等。
  • tasks.md：拆解后的可执行任务清单（通常带复选框），供后续 apply 使用。

逐步规划 ​

并不一定每次都是一下子创建的，有时候需要逐步创建 proposal、design、specs 和 tasks。

先运行命令启动新变更：

text
/opsx:new

再运行命令逐步完善：

text
/opsx:continue

4.3 执行阶段：/opsx:apply ​

当任务清单准备就绪后，就可以让 AI 根据任务列表编写代码。

命令：

text
/opsx:apply

行为：AI 读取当前变更下的 tasks.md，逐个任务生成代码，并将代码文件放到项目中的正确位置。

交互：每完成一个任务，AI 可能会请求确认或提供解释；你也可以中途打断，修改任务清单后继续。

4.4 验证阶段：/opsx:verify ​

代码实现后，需要检查其是否完全符合当初制定的规范和设计。

命令：

text
/opsx:verify

行为：AI 分析变更中的代码，对照 specs/ 和 design.md 进行一致性检查，生成一份验证报告。

报告内容：指出符合项、不符合项、潜在问题、建议修复方案。

后续：如果发现问题，可以手动修改代码或调整规范，然后再次运行 verify 直至通过。

4.5 归档阶段：/opsx:archive ​

当变更所有工作（编码、验证）完成，并已同步规范后，就可以归档本次变更。

命令：

text
/opsx:archive

行为：将变更目录移到 changes/archive/ 目录。

4.6 同步阶段：/opsx:sync ​

在变更过程中，你可能会产生新的、可复用的规范（如一个通用的组件接口、API 设计模式）。这些规范应该合并到项目的主规范库中，供未来变更使用。

text
/opsx:sync

行为：将当前变更中新增或修改的规范文件（位于 changes/<change>/specs/）复制或合并到项目根目录的 openspec/specs/ 中。