OpenSpec完整工作流使用说明

OpenSpec 的完整工作流包含七个核心步骤：探索（Explore）、提案（Propose）、审查（Review）、执行（Apply）、验证（Verify）、同步（Sync）、归档（Archive）、以及更新 （update） 。这八个步骤构成一个完整的“变更即代码”（Change-as-Code）闭环。

1. 探索 (Explore) — /opsx:explore

用途：
探索是无风险的思考与调研阶段，它在你投入任何代码或创建任何正式文档之前，帮助你与AI一起理清问题、权衡方案。探索阶段不会创建任何文件或修改代码，纯粹是对话式的分析与讨论-。

触发执行的场景：

• 你知道问题但不知道解决方案（如“页面加载很慢”“认证逻辑混乱”）
• 需要在多个技术方案间做选择，希望AI基于实际代码库列出权衡
• 刚接手一个代码库，需要在修改前理解某功能如何运作
• 需求模糊，希望在投入前将其明确化
• 怀疑工作量比表面看起来更大或更小，希望诚实评估范围

判断执行效果的标准：

维度	合格标准
问题理解	AI准确识别了问题的根因（如定位到重复订单的两个可能原因）
方案对比	AI列出了至少2-3个可选方案及其优缺点
范围界定	模糊想法被缩小为具体、可构建的范围
无副作用	没有创建任何变更文件夹、没有写入任何制品、没有修改任何代码

💡 最佳实践：养成“不确定时先探索”的习惯。即使探索三条死路，每条都能学到东西，然后再提案最终存活下来的路径。

---

2. 提案 (Propose) — /opsx:propose

用途：
在探索完成、意图明确后，提案阶段将意图转化为结构化的变更文档-。AI会读取现有的openspec/specs/（当前系统的“单一事实来源”），生成一个完整的变更目录，包含四份核心文件：

• **proposal.md**：解决什么问题、有什么变化（标记ADDED/MODIFIED/REMOVED）、什么不变、关键风险和依赖
• **specs/**：以 GIVEN/WHEN/THEN 格式写成的行为场景（验收标准），精确到可直接当测试用例-
• **design.md**：技术方案——选什么库、什么架构模式、关键决策
• **tasks.md**：拆成小块、可独立审查的实现清单

触发执行的场景：

• 需要新增功能或特性-
• 需要做破坏性变更（API变更、数据模型变更）-
• 探索完成后，准备将调研结果正式化为可执行的变更计划

判断执行效果的标准：

维度	合格标准
提案完整性	四份文件（proposal/specs/design/tasks）全部生成且结构完整
规格可测试性	specs中的场景使用GIVEN/WHEN/THEN格式，可直接转化为测试用例
变更标记清晰	明确标注了ADDED/MODIFIED/REMOVED，而非模糊描述
任务可独立执行	tasks.md中的每个任务足够小、可独立测试和验证

---

3. 审查 (Review) — 人工审查（无专属命令）

用途：
审查是人机协作的关键环节，确保AI完全理解任务目标，避免后续返工-。OpenSpec的承诺是“在写任何代码之前，你和AI先就构建什么达成一致”。在写下任何一行实现代码之前必须完成审查。

审查有两个关键时刻-：

1. 提案审查（/opsx:propose之后、/opsx:apply之前）——最重要、也最容易被跳过
2. 代码审查（/opsx:apply之后、/opsx:archive之前）——配合/opsx:verify

审查阅读顺序：

1. proposal.md → 意图和范围（如果这里错了，立刻停下）
2. specs/下的delta规范 → 需求（审查的核心）
3. **design.md**（仅大变更需要）→ 技术方案
4. tasks.md → 工作计划的合理性

触发执行的场景：

• 每次/opsx:propose或/opsx:ff之后，执行/opsx:apply之前
• 每次/opsx:apply执行完毕后，执行/opsx:archive之前

判断执行效果的标准：

审查对象	合格标准	危险信号（需返工）
proposal.md	一个清晰的意图+可识别的范围+值得现在做的理由	解决的是不同问题/范围悄悄扩大/太模糊
specs/	每条需求有明确的SHALL/MUST声明+至少一个GIVEN/WHEN/THEN场景	需求模糊无法测试/有需求无场景
tasks.md	任务拆分合理，可独立审查和测试	任务粒度过大或依赖关系不清晰

💡 核心理念：在一个段落式的计划中发现错误几乎零成本；在300行代码中发现同样的错误则代价高昂。

---

4. 执行 (Apply) — /opsx:apply

用途：
提案获批后，AI按照tasks.md中的任务列表，逐一实现代码逻辑。关键区别在于：AI每一步都会读取规范文件，而非凭记忆或prompt工作。每个任务足够小，可以独立测试；哪个任务失败，能精确看到违反了哪条规范场景。

触发执行的场景：

• 提案审查通过、团队批准后-
• 需求明确、规范已锁定、准备进入编码阶段

判断执行效果的标准：

维度	合格标准
任务进度	tasks.md中所有任务标记为- [x]（已完成）
规范遵守	代码行为符合specs中的GIVEN/WHEN/THEN场景
独立可测	每个任务产生的代码可独立测试且通过
无偏离	代码未超出tasks.md定义的范围（避免“顺手改了别处”）

---

5. 验证 (Verify) — /opsx:verify

用途：
验证是关键的质量关卡，它在apply之后、archive之前，对照规范检查实现是否真正符合要求。它不只是跑测试，而是验证代码的行为是否符合GIVEN/WHEN/THEN场景。

验证从三个维度检查实现-：

• 完整性（Completeness） ：所有实现任务100%完成，所有delta规范中的需求都有对应的实现证据
• 正确性（Correctness） ：需求实现匹配意图，场景被测试覆盖或在代码中处理
• 一致性（Coherence） ：实现遵循design.md中的决策，与项目模式保持一致

触发执行的场景：

• /opsx:apply执行完毕后、/opsx:archive之前-
• 可迭代执行，在实现过程中阶段性检查进度
• 代码审查配合环节-

判断执行效果的标准：

检查项	合格标准	不合格信号
任务完成度	tasks.md所有项标记- [x]	存在未完成- [ ]任务
需求映射	每条### Requirement:都有代码实现证据	某需求无对应实现
场景覆盖	每个#### Scenario:在代码或测试中有对应处理	场景未覆盖
设计遵循	design.md中的关键决策在代码中得到体现	实现偏离设计决策

验证会生成分优先级报告：CRITICAL级别的问题必须在归档前修复。

---

6. 同步 (Sync) — /opsx:sync

用途：
同步是在变更未完成时，将delta规范提前合并到主规范中。它的核心价值是为长期运行的变更建立增量检查点：让其他团队成员或AI Agent能访问最新的“当前现实”规范，而无需等待整个变更最终完成。

与归档（Archive）不同，同步是AI驱动的智能合并：

• 部分更新：只需插入新增的场景，无需复制整个需求块
• 上下文保留：保留delta中未提及的现有内容
• 规则执行：合并前获取制品特定规则作为约束

触发执行的场景：

• 长期运行的、跨多个迭代的大功能开发，需要中途让团队看到最新规范
• 实施过程中发现计划需要调整，希望先将已确认的部分同步到主规范
• 归档前，如果delta规范存在，AI会询问是否先同步再归档

判断执行效果的标准：

维度	合格标准
合并准确性	delta中的变更正确合并到主规范，未丢失或重复内容
上下文保留	主规范中未在delta中提及的内容完整保留
变更可继续	同步后changes/目录仍存在，可继续在该变更上工作
无提前归档	变更未被标记为已完成，仍处于活跃状态

---

7. 归档 (Archive) — /opsx:archive

用途：
归档是变更的“结项”操作——宣告一个OpenSpec变更已完成，将其从“进行中的变更”转为“历史记录”，同时确保主规范（Main Spec）反映最终实现-。

归档会将delta规范程序化地合并回openspec/specs/（单一事实来源），并将整个变更目录保留在openspec/changes/中作为审计轨迹-。OpenSpec通过归档提供可审计的历史记录，包括归档变更和明确的验证步骤-。

触发执行的场景：

• 所有实现任务完成、验证通过后-
• 代码审查通过后-
• 变更准备合入主分支时-

判断执行效果的标准：

维度	合格标准
前置条件满足	所有任务已完成（tasks.md全[x]）、验证已通过
规范合并正确	delta specs成功合并到主specs，无冲突或遗漏-
变更状态变更	变更从“活跃”转为“历史记录”-
审计轨迹完整	变更目录完整保留，可供后续追溯-
Delta已同步	如果存在delta specs，归档前应已同步或确认无需同步

8. 规划修订—/opsx:update

/opsx:update 是一个规划修订命令，用于在变更的规划阶段（即/opsx:propose之后、/opsx:apply之前），对已生成的规划工件（如proposal.md、specs/中的delta specs、design.md、tasks.md）进行修订和调整-。

它的核心用途是在审查过程中发现问题、或在讨论后调整方案时，无需从头开始（重新执行propose），直接对现有计划进行修正，并确保各工件之间保持逻辑一致性-。

触发场景：

• 需求澄清：在审查提案时，发现proposal.md对问题定义或范围描述不准确。
• 方案调整：审查design.md时，发现技术选型或架构决策需要更改。
• 规格细化：审查specs/中的delta specs时，发现某个GIVEN/WHEN/THEN场景遗漏或描述有误。
• 任务拆分优化：审查tasks.md时，认为任务粒度太大或依赖关系需要调整。

注意：/opsx:update是命令，而openspec update是CLI命令，后者用于在升级OpenSpec CLI后更新AI工具的配置文件-。

---

update 与 sync 的区别

这是OpenSpec工作流中一个关键的区分点，两者的操作对象和目的截然不同。

维度	/opsx:update	/opsx:sync
操作对象	变更目录（changes/<change-name>/）内的规划工件	主规范（openspec/specs/）
核心目的	修订计划：修改提案、设计、任务或delta specs本身-	合并增量：将变更中的delta specs提前合并到主规范中-
操作阶段	规划与审查阶段（/opsx:propose之后，/opsx:apply之前或期间）	实现与归档阶段（/opsx:apply期间或/opsx:archive之前）
变更状态	变更仍处于活跃和未完成状态，可以继续修改和完善	变更保持活跃，但将其部分成果（规范）提前“发布”到主规范中-
典型场景	“这个设计需要调整，帮我更新一下design.md。”	“这个功能已经实现了，先把规范合并到主文档，方便其他人查阅。”

一句话总结：**update是“改计划”，sync是“交作业”**——update让你在内部修改施工图纸，sync则是将已完成的图纸部分提前更新到总蓝图里。

何时调update、何时调sync：

1. 必须调用 /opsx:update 的场景（规划工件变了）

无论修改者是人工还是 AI，只要规划文件被改动，就必须执行更新。

• 人工手动编辑后：你在 IDE 里直接修改了 design.md 的技术方案，或者调整了 tasks.md 的任务拆分。
• 审查反馈后的 AI 修订：审查时你提出“范围太大”，AI 根据你的反馈，自动重写了 proposal.md 中的变更范围。
• 验证失败后的计划调整：执行 /opsx:verify 后发现实现与规范不符，经讨论发现是规范写错了，于是 AI 或你更新了 delta specs 中的场景描述。

为什么必须执行？ 因为 OpenSpec 的规划文件之间是强逻辑关联的（例如 tasks.md 必须覆盖 specs/ 中的场景）。/opsx:update 命令会重新读取所有规划文件，检查内部一致性（确保任务能覆盖需求、设计能支撑提案），避免出现“改了一个文件，其他文件没跟上”的脱节。

2. 绝对不需要调用 /opsx:update 的场景（只有代码变了）

如果只修改了业务代码或测试代码，而上述规划文件（changes/ 目录内的文件）一字未动，则完全不需要调用 update。

• 场景举例：人工修复了 AI 生成的某个逻辑 Bug（例如把 > 改成了 >=），但原本的 tasks.md 中写的任务就是“实现该逻辑”，且 specs/ 中的场景描述（GIVEN/WHEN/THEN）依然正确。
• 正确操作：修复代码后，直接运行 /opsx:verify 确认代码依然符合规范，然后继续走 /opsx:archive 归档流程即可。

3. 需要特别注意的灰色场景（只改了 tasks.md 中的勾选状态）

在日常操作中，你可能会在 tasks.md 中手动把 - [ ] 改成 - [x]（勾选已完成任务）。**这种情况通常不需要调用 /opsx:update**。

• 原因：勾选框的变动属于“状态标记”，而非“规划内容”的实质性变更（没有新增、删除或重写任务描述）。AI Agent 在执行 /opsx:apply 和 /opsx:verify 时，会实时读取这些勾选状态作为进度依据。
• 例外：如果你不仅改了勾选，还重写了任务描述或调整了任务顺序/依赖，那就回到了第 1 种情况，必须调用 update。

一句话总结

/opsx:update 是用来“统一规划文件口径”的。 只要 changes/ 目录下的规划文本（提案、设计、规范增量、任务清单内容）被动了，就调它；如果只动了 src/ 下的代码，就不要调它，直接 verify + archive 即可。

附：CLI 命令 (终端执行)，用于管理 OpenSpec 项目本身

命令	用途	使用场景
openspec init	在当前目录初始化 OpenSpec 项目-。	新项目接入 OpenSpec 时的第一步。
openspec update	更新项目配置。	切换工作流模式（如从 Core 切换到 Expanded）后刷新配置-2 。
openspec list	查看所有进行中的变更或规范-。	快速浏览当前工作进度。
openspec view	打开交互式仪表盘，可视化探索变更与规范-。	需要图形化概览项目状态时。
openspec show <item>	查看特定变更或规范的详细内容-。	需要查阅某个变更的细节。
openspec validate	检查变更或规范是否存在格式等问题-。	在归档前进行最终检查，确保质量-。
openspec archive	完成并归档一个已结束的变更-。	开发完成，准备将变更合并回主规范。
openspec config	查看或修改 OpenSpec 的配置。	调整工作流模式（profile）等设置-。

注：来源网络，非原创