04 - 一张图看懂 OpenSpec 变更的一生：从创建到归档

一张图看懂 OpenSpec 变更的一生：从创建到归档

一句话：上一篇我们 5 分钟跑通了一个 change，但它只是「最小路径」。这篇把完整地图补给你------一个 OpenSpec change 从创建到归档，其实只走 7 个阶段，Skill 和 CLI 两条路都能走。

引子：跑通一次之后，你需要一张地图

上一篇我们用 5 条命令跑完了 OpenSpec 的最小闭环：

text 复制代码

new change → explore → propose → apply → archive

跑完体感有了，但心里可能还有几个问号：

explore 和 propose 中间到底发生了什么？
update 什么时候用？
sync 和 archive 不是一回事吗？
那些规划工件（proposal / spec / design / tasks）是按什么顺序长出来的？

这篇就是来回答这些问题的。我会把 OpenSpec change 的完整生命周期展开成 7 个阶段 ，并给你一张总览图 + 速查表 + 状态流转图。看完你会明白：上一篇你跑的那条路，只是这张图里的一条捷径。

一、7 个阶段总览：一个 change 从生到死

一个 OpenSpec change 的完整生命周期如下：

text 复制代码

阶段 0：项目配置（config.yaml）
    ↓
阶段 1：创建变更（openspec new change / /opsx:propose）
    ↓
阶段 2：探索与澄清（/opsx:explore，可选）
    ↓
阶段 3：规划提案（/opsx:propose）
    ↓
阶段 4：审查与更新（/opsx:update，可选/循环）
    ↓
阶段 5：实现任务（/opsx:apply）
    ↓
阶段 6：规格同步（/opsx:sync，可选）
    ↓
阶段 7：归档变更（/opsx:archive）

把这 7 个阶段对应到上一篇你跑过的路上，就长这样：

本篇讲的阶段	上一篇的命令	你当时的体感
阶段 0	安装时配的 `config.yaml`	"项目背景和技术栈写进去，AI 后面就不会乱写"
阶段 1	`openspec new change "search-demo"`	"开了个文件夹，发了张身份证"
阶段 2	`/opsx:explore`	"跟 AI 聊清楚需求"
阶段 3	`/opsx:propose`	"AI 一次性写出四件套"
阶段 4	没用到	"需求没变，不用改"
阶段 5	`/opsx:apply`	"照着 tasks 打勾"
阶段 6	被 `archive` 自动做了	"归档时一起合并进主 specs"
阶段 7	`/opsx:archive`	"文件夹被搬进 archive/，主 specs 有了内容"

💡 看出来了吗？上一篇的最小路径是 0 → 1 → 2 → 3 → 5 → 7，跳过了 4 和 6。但完整地图里，4 和 6 是真实存在的出口，只是你的需求简单，不需要走罢了。

二、阶段速查表：每个阶段用什么、产什么

下面这张表是全文最值得收藏的部分。它把每个阶段的 Skill 调用、产出工件、核心作用 都列在一起，以后你卡在任何一个环节，回来查就行。

阶段	Skill	产出/影响	核心作用
0. 项目配置	无	`openspec/config.yaml`	给所有 change 统一上下文和约束
1. 创建变更	`/opsx:propose`（内部执行）	`openspec/changes/<name>/` + `.openspec.yaml`	开文件夹、发身份证
2. 探索澄清	`/opsx:explore`	思考过程、方案对比	需求不清时先聊清楚
3. 规划提案	`/opsx:propose`	`proposal.md` → `specs/.../spec.md` → `design.md` → `tasks.md`	把想法沉淀为标准四件套
4. 审查更新	`/opsx:update`	修订后的规划工件	需求/设计变更时保持一致
5. 实现任务	`/opsx:apply`	代码 + 更新的 `tasks.md`	按 tasks 清单施工
6. 规格同步	`/opsx:sync`	delta spec 合并进主 specs	把变更需求沉淀到公共需求库
7. 归档变更	`/opsx:archive`	文件夹移动到 `changes/archive/YYYY-MM-DD-<name>/`	完成生命周期闭环

三、7 个阶段逐个讲

阶段 0：项目配置（config.yaml）

这是最容易被忽略、但又最基础的一步。

text 复制代码

openspec/config.yaml

它定义了项目的全局约束：技术栈、设计规范、兼容性、命名规则、页面/组件写法红线等等。后面每个 change 的 proposal / design / tasks 生出来时，都会继承这里的规则。

比如一个金融移动端 H5 项目的 config.yaml 可能长这样：

yaml 复制代码

context: |
  项目类型：金融类移动端 H5 应用
  技术栈：React 18.2.0 + MobX 4.2.1 + antd-mobile-v2
  设计规范：750px 设计稿，px 自动转 vw
  兼容性：微信内置浏览器、鸿蒙系统、各类移动端
rules:
  proposal: []
  specs: []
  design: []
  tasks: []

🪝 注意：context 必须是字符串（用 | 折叠），rules 的 key 是 artifact ID（proposal/specs/design/tasks）。格式写错会静默失效------AI 后面像没穿秋裤一样照猜。这个坑我们在番外 B 会专门讲。

阶段 1：创建变更（new change）

所有 change 的起点。

bash 复制代码

openspec new change "condition-order-list"

它干三件事：

创建 openspec/changes/condition-order-list/ 文件夹；
生成 .openspec.yaml 身份证；
让 OpenSpec CLI 识别这是一个「活的」变更。

.openspec.yaml 内容很简单：

yaml 复制代码

schema: spec-driven
created: 2026-08-18

💡 用 /opsx:propose 时，AI 通常会自动跑 new change。但你要知道这条命令本身------排查「change 没身份证」问题时，这就是根因。

阶段 2：探索与澄清（/opsx:explore）

可选阶段，但非常重要。

当需求不够清晰、有多种方案可选、涉及跨模块改造时，先用 /opsx:explore 当「思考伙伴」。它不生成正式工件，只输出思考过程、方案对比、风险提醒。

典型用法：

text 复制代码

/opsx:explore 我想做基金条件单列表页，但不确定列表要展示哪些字段、点击卡片后跳转哪里、状态筛选怎么设计

explore 会：

追问澄清（"要不要支持分页？默认排序是什么？"）
画 ASCII 结构图
对比方案（"卡片式 vs 行式列表"）
挖风险（"多个状态筛选组合时为空态怎么展示"）

如果需求很明确，跳过 explore 直接 propose 完全没问题。

阶段 3：规划提案（/opsx:propose）

把阶段 2 的思考（或直接的需求）沉淀为四件套标准工件：

text 复制代码

proposal.md
    ↓
specs/<capability>/spec.md
    ↓
design.md
    ↓
tasks.md

依赖关系是：

tasks.md 依赖 design.md
design.md 依赖 specs/.../spec.md
specs/.../spec.md 依赖 proposal.md

所以 /opsx:propose 会按顺序依次生成，后一个读取前一个作为上下文。

四件套各自回答的问题：

工件	回答的问题
`proposal.md`	为什么做（背景、目标、范围、风险、验收标准）
`specs/<capability>/spec.md`	做什么（系统必须满足的行为契约，delta 形式）
`design.md`	怎么做（页面结构、数据流、状态、接口、组件边界）
`tasks.md`	怎么执行（可勾选的实现步骤清单）

💡 上一篇的 search-demo，四件套就是这一步一次性生成的。你现在回头看，会明白它们不是平铺的四个文件，而是有依赖链条的四层规划。

阶段 4：审查与更新（/opsx:update）

规划不是一成不变的。需求变了、实现时发现设计有问题、接口调整了，都需要改规划工件。

/opsx:update 的作用：只修改规划工件，不修改代码，并确保各工件之间保持一致。

典型场景：

需求范围变化 → 更新 proposal.md
字段设计不合理 → 修改 design.md
后端接口变更 → 同步更新 specs/.../spec.md 和 tasks.md
任务拆得太粗/太细 → 调整 tasks.md

🪝 改一个工件后，依赖它的工件也要检查是否还一致。这就是 /opsx:update 比手动编辑更安全的地方------它会主动做这种一致性调和。

阶段 5：实现任务（/opsx:apply）

施工阶段。

/opsx:apply 读取 proposal.md / specs/.../spec.md / design.md / tasks.md，然后按 tasks.md 里的清单一步步实现代码，每完成一个任务就把 - [ ] 改成 - [x]。

apply 有两条铁律：

动手前必读四件套------先读全貌再动手；
遇到错误、阻塞、需求不清就暂停，别猜------宁可停下来问，也不能糊弄。

markdown 复制代码

- [x] 创建 Service 空壳与枚举
- [x] 搭建 Store 骨架
- [ ] 实现 UI 骨架
- [ ] 接入数据与轮询
- [ ] 注册路由

阶段 6：规格同步（/opsx:sync）

可选阶段，但很多人搞不清它和 archive 的区别。

/opsx:sync 的作用：把 change 里的 delta spec 合并到项目主规格 openspec/specs/<capability>/spec.md 中，但 change 仍然保持活跃。

什么时候用 sync？

一个变更还没做完，但它的需求规格已经稳定，团队其他人需要参考；
多个 change 同时修改同一个能力域，需要中途对齐主 specs；
你想在 archive 之前先 review 一下 delta 和主 specs 的差异。

💡 archive 会自动内联执行 sync 。所以如果你只是做一个简单 change，不需要单独调 /opsx:sync，等 archive 时一起处理即可。

阶段 7：归档变更（/opsx:archive）

生命周期闭环。

/opsx:archive 会：

检查规划工件是否齐全；
检查 tasks.md 是否还有未完成任务；
提示是否把 delta spec 同步到主 specs；
把 openspec/changes/<name>/ 移动到 openspec/changes/archive/YYYY-MM-DD-<name>/。

归档后：

openspec list 不再显示这个 change；
主 specs 里多了合并后的需求；
历史变更以日期前缀形式保存在 archive/ 下，可追溯。

四、生命周期状态流转图

把上面的 7 个阶段整理成一条带分支的链路，方便你记住整条流程：

项目配置 config.yaml
创建变更
生成 .openspec.yaml 标记
是否需要探索？
- 是：执行 /opsx:explore
- 否：直接进入下一步
执行 /opsx:propose，生成 proposal.md
生成 specs/.../spec.md
生成 design.md
生成 tasks.md
是否需要更新？
- 是：执行 /opsx:update，然后回到第 8 步
- 否：进入下一步
执行 /opsx:apply，产出代码实现
是否完成？
- 否：回到第 10 步
- 是：进入下一步
是否需要同步规格？
- 是：执行 /opsx:sync
- 否：直接进入下一步
执行 /opsx:archive
归档到 changes/archive/

这张图里有两个循环回路：

update 回路：规划阶段发现不对，改完规划再回来；
apply 回路：实现阶段发现任务没做完，继续施工。

这也是 OpenSpec 的核心设计思想：不是一条死板的直线，而是允许在规划和实现之间反复校准的循环。

五、Skill 与 CLI：到底怎么选？

最后再澄清一个最常见的困惑：每个阶段都有 Skill 和 CLI 两条路，我该用哪个？

场景	推荐方式	原因
在 Claude Code / AI 对话里用	`/opsx:xxx`	一句话就行，AI 自动读上下文、执行命令、管理进度
在 terminal 里手动精确控制	`openspec ...`	每一步自己确认，适合对流程熟悉的开发者
团队里做审计/查看状态	CLI	`openspec status --json` / `openspec validate` 输出稳定，适合脚本化
新手第一次跑通	Skill	AI 会带节奏，不容易漏步骤

💡 二者可以混用。比如先用 /opsx:propose 生成四件套，再手动执行 openspec status --change <name> --json 查看状态，完全没问题。

总结

一个 OpenSpec change 的完整生命周期有 7 个阶段：项目配置 → 创建变更 → 探索澄清 → 规划提案 → 审查更新 → 实现任务 → 规格同步 → 归档变更。
上一篇的 5 分钟最小路径是：0 → 1 → 2 → 3 → 5 → 7 ，跳过了 update 和 sync，因为它们在简单需求里不需要。
/opsx:explore 是可选的思考伙伴 ，需求不清时用它；/opsx:propose 是必须的标准化工件生成器。
/opsx:update 只改规划不改代码，负责一致性调和 ；/opsx:apply 只负责照 tasks 施工。
/opsx:sync 是中途把 delta 合并进主 specs ；/opsx:archive 是完工归档，会自动内联 sync。
Skill 是 CLI 的封装，二者功能等价，可根据场景混用。

下篇预告

跑通了 change，也看懂了生命周期地图，但你可能还在想：

specs 里那些 ADDED Requirements、SHALL、GIVEN / WHEN / THEN 到底是什么？为什么叫 delta？

下一篇我们来啃 OpenSpec 的核心概念 delta ，我会用 git 类比给你讲清楚：specs 是主分支、change 是 PR、delta 是 diff、sync 是 merge、archive 是 close。