ccg-workflow 的 OpenSpec 变更归档指南:从 `openspec-archive-change` Skill 看完整归档流程
ccg-workflow 的 OpenSpec 变更归档指南:从 openspec-archive-change Skill 看完整归档流程
导读
本文围绕本仓库 .agents/skills/openspec-archive-change/SKILL.md 这一 Agent Skill 展开,系统讲解在多模型协作开发流程(spec-driven 工作流)中,如何把一项已完成实现的变更(change)安全地归档到 openspec/changes/archive/ 目录。读完本文,你将掌握归档前的四道检查关卡(变更选择、产物完成度、任务完成度、delta spec 同步评估)、归档执行命令与命名规则、以及归档成功后的标准输出格式;同时结合仓库内 openspec-sync-specs、openspec-verify-change 等关联 Skill 与 templates/commands/spec-impl.md 的实现,理解归档动作在完整生命周期中的位置与底层逻辑。
一、归档在 OpenSpec 工作流中的位置
本仓库的 .agents/skills/ 目录下维护了一整套 OpenSpec 生命周期 Skill,归档只是其中一环:
openspec-new-change:新建变更,产出openspec/changes/<name>/脚手架openspec-continue-change/openspec-apply-change:按tasks.md逐任务实现openspec-verify-change:归档前校验实现与产物的一致性openspec-archive-change:归档已完成变更(本文主题)openspec-sync-specs:把变更的 delta spec 合并回主 spec(归档时可能联动执行)- 另有
openspec-explore、openspec-ff-change、openspec-bulk-archive-change、openspec-onboard等配套 Skill
在 templates/commands/spec-impl.md 中,归档是整个 spec 工作流的收尾动作:当 tasks.md 中所有任务都被标记为 - <a href="https://link.gitcode.com/i/9ea6741ee0b3b7f9a198a1dc8f011170" target="_blank">x] 后,内部调用 /opsx:archive,该动作会「将 spec deltas 合并到 openspec/specs/,并把变更移动到 archive」(见 [templates/commands/spec-impl.md)。这与 openspec-archive-change 的第 4、5 步(delta 同步评估 + 目录移动)一一对应,可见归档并非简单移动文件,而是「同步 + 归档」的组合操作。
前置约束:本 Skill 标注
compatibility: Requires openspec CLI,即所有命令依赖 OpenSpec CLI 的list/status子命令输出,操作前需确保 CLI 已就绪。
二、第一步:变更选择——绝不自动猜测
归档的输入是可选的变更名。Skill 明确规定:
- 如果用户提供了变更名,直接使用;
- 如果省略,先从对话上下文中推断;
- 如果推断结果模糊或产生歧义,必须通过
openspec list --json获取可选变更列表,并用 AskUserQuestion 工具让用户选择; - 列表中只展示活跃(active)变更(即尚未归档的变更),并尽量附带每个变更使用的 schema;
- 硬性红线:不要猜测或自动选中某个变更,永远让用户自己选择。
openspec list --json
这条规则与 openspec-new-change、openspec-sync-specs、openspec-verify-change 等 Skill 的选择逻辑完全一致:所有「作用于某个变更」的动作,都坚持「先确认变更身份,再执行操作」,避免 Agent 把归档作用到错误的变更目录上。
三、第二、三步:双重完成度检查——产物与任务
归档前需要确认变更确实「做完」了,检查分两层:
3.1 产物(artifact)完成度检查
openspec status --change "<name>" --json
解析返回的 JSON,重点读取两个字段:
schemaName:当前变更使用的工作流(例如spec-driven);artifacts:产物列表,每项带状态(done或其他)。
若存在任何未处于 done 状态的产物:
- 向用户展示警告,列出所有未完成的产物;
- 用 AskUserQuestion 工具确认用户是否仍要继续归档;
- 用户确认后,才继续下一步。
3.2 任务(task)完成度检查
读取变更目录下的任务文件(通常是 tasks.md),统计勾选框:
- [ ]:未完成任务;- [x]:已完成任务。
若存在未完成任务:
- 展示警告,说明未完成任务的数量;
- 用 AskUserQuestion 工具确认是否继续;
- 用户确认后继续。
若不存在任务文件: 直接跳过任务相关警告,继续流程。
关于任务文件的格式,templates/commands/spec-impl.md 有一条重要提醒:所有任务必须使用 checkbox 格式(- [ ] X.Y description),标题加项目符号的写法会导致 OpenSpec CLI 解析出 0 个任务并阻塞工作流。这意味着「统计 - [ ] / - [x]」这一归档检查依赖的正是规范化的 checkbox 格式,二者环环相扣。
检查策略要点:这两层检查的目的都是「告知并确认」,而不是「阻止」。Skill 的 Guardrails 明确写了 Don't block archive on warnings - just inform and confirm——警告只负责透明呈现,最终是否继续由用户拍板。
四、第四步:delta spec 同步状态评估
归档前的关键决策点:变更目录中可能带有 delta specs(增量规格),它们描述了实现过程中对规格的增删改,需要决定是否合并回主 spec。
4.1 发现 delta specs
检查目录 openspec/changes/<name>/specs/。若不存在任何 delta spec,跳过同步提示,直接进入归档。
4.2 逐项对比 delta spec 与主 spec
若存在 delta specs,对每个 delta spec 与其对应的主 spec 对比:
- delta spec 位置:
openspec/changes/<name>/specs/<capability>/spec.md - 主 spec 位置:
openspec/specs/<capability>/spec.md
判定将要应用的变化类型(新增、修改、删除、重命名),并在询问用户之前展示一份合并摘要(combined summary)。
4.3 提示选项
根据同步状态给出不同选项:
| 场景 | 提示选项 |
|---|---|
| 需要同步(存在未合并的变化) | "Sync now (recommended)" / "Archive without syncing" |
| 已经同步 | "Archive now" / "Sync anyway" / "Cancel" |
若用户选择同步,则执行 /opsx:sync 逻辑(即使用 openspec-sync-specs Skill 的 agent-driven 方式),无论用户是否选择同步,最终都继续执行归档。
4.4 同步动作的内部逻辑(openspec-sync-specs)
.agents/skills/openspec-sync-specs/SKILL.md 定义了同步的细节:这是一个 agent-driven(智能合并) 操作——Agent 读取 delta spec 后直接编辑主 spec,而非程序化整体替换。delta spec 采用四段式结构:
## ADDED Requirements
### Requirement: New Feature
The system SHALL do something new.
#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y
## MODIFIED Requirements
### Requirement: Existing Feature
#### Scenario: New scenario to add
- **WHEN** user does A
- **THEN** system does B
## REMOVED Requirements
### Requirement: Deprecated Feature
## RENAMED Requirements
- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`
智能合并的核心原则:delta 表达的是**意图(intent)**而非整体替换——新增场景时只需在 MODIFIED 段列出该场景,不必复制既有场景;主 spec 中未提及的内容必须原样保留。这保证了归档时同步上来的规格既完整又不丢失历史内容。
五、第五步:执行归档
5.1 创建归档目录
mkdir -p openspec/changes/archive
5.2 生成目标名称
目标名使用当前日期 + 变更名:
YYYY-MM-DD-<change-name>
例如变更 add-user-auth 在 2026-10-05 归档,目标目录为 2026-10-05-add-user-auth。
5.3 冲突检查
- 若目标已存在:以错误终止,建议重命名既有归档或改用其他日期;
- 若目标不存在:执行移动:
mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
5.4 关键保真点:.openspec.yaml
Skill 的 Guardrails 特别强调 Preserve .openspec.yaml when moving to archive (it moves with the directory)——变更目录内的 .openspec.yaml 会随目录一起移动,归档后该变更的元信息(schema、生成信息等)依然完整,便于日后回溯。因此不要单独拷贝或删除目录中的文件,直接整体移动即可。
六、第六步:输出归档摘要
归档完成后,展示标准摘要,包含:变更名、使用的 schema、归档位置、spec 是否已同步、以及警告说明(如有未完成产物/任务)。
Skill 提供的标准成功输出模板:
## Archive Complete
**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
All artifacts complete. All tasks complete.
注意 **Specs:** 行的三种取值——✓ Synced to main specs(已同步)、No delta specs(无 delta spec)、Sync skipped(用户选择跳过同步),对应第 4 步的三种分支,确保输出与用户的实际选择一致。
七、Guardrails 全量清单与设计意图
原 Skill 末尾的 Guardrails 是归档动作的行为约束,也是理解其设计意图的钥匙:
| Guardrail | 设计意图 |
|---|---|
| Always prompt for change selection if not provided | 防止归档错对象;选择权永远在用户 |
Use artifact graph (openspec status --json) for completion checking |
完成度检查以 CLI 的产物图为准,不靠猜测 |
| Don't block archive on warnings - just inform and confirm | 警告只透明化,不充当硬性拦截 |
Preserve .openspec.yaml when moving to archive |
保持归档目录元信息完整、可回溯 |
| Show clear summary of what happened | 归档动作必须可审计、可复述 |
| If sync is requested, use openspec-sync-specs approach (agent-driven) | 同步走智能合并,不做无脑整体替换 |
| If delta specs exist, always run the sync assessment and show the combined summary before prompting | delta 同步评估是强制步骤,且必须先展示摘要再询问 |
八、归档前的可选防线:openspec-verify-change
归档 Skill 本身只做「检查 + 确认 + 移动」,但仓库还提供了一个前置质检 Skill——.agents/skills/openspec-verify-change/SKILL.md,用于在归档前把实现与产物做一次系统校验:
- Completeness(完整性):任务勾选数与 delta spec 需求覆盖度;
- Correctness(正确性):需求实现映射与场景覆盖;
- Coherence(一致性):design.md 决策遵循度与代码模式一致性。
每个维度产出 CRITICAL / WARNING / SUGGESTION 三级问题,并遵循「降级容错」策略:仅有 tasks.md 时只验任务;有 tasks + specs 时验完整性与正确性;产物齐全时三个维度全验。最终给出明确结论——X critical issue(s) found. Fix before archiving. 或 All checks passed. Ready for archive.。
因此在实际 spec 工作流(参见 templates/commands/spec-impl.md 的 Exit Criteria:所有任务 [x] 且多模型评审通过)中,推荐路径是:verify-change 通过 → archive-change 归档,前者负责「质量把关」,后者负责「干净收尾」。
九、完整归档流程速查
以 add-user-auth 变更为例,一次典型归档会话的命令与决策序列:
| 阶段 | 动作 |
|---|---|
| 1. 选变更 | openspec list --json → AskUserQuestion 让用户从活跃变更中选择 |
| 2. 查产物 | openspec status --change "add-user-auth" --json → 解析 schemaName 与 artifacts[].status |
| 3. 查任务 | 读 openspec/changes/add-user-auth/tasks.md,统计 - [ ] 与 - [x] |
| 4. 评估同步 | 检查 openspec/changes/add-user-auth/specs/;若有 delta spec,对比 openspec/specs/<capability>/spec.md 并展示合并摘要,询问用户 |
| 5. 执行归档 | mkdir -p openspec/changes/archive → 目标 2026-10-05-add-user-auth → 冲突检查 → mv |
| 6. 输出摘要 | 按 Archive Complete 模板汇报变更名、schema、归档位置、spec 同步状态 |
两个易错点请特别注意:
- 不要自动选择变更——所有 OpenSpec Skill 都强制用户确认,归档同样如此;
- 目标目录冲突即失败——日期重复或重名都会导致归档中止,应建议重命名既有归档或更换日期。
结语
openspec-archive-change 是本仓库 OpenSpec 实验工作流的收尾环节,它的设计围绕三条主线:用户决定权(变更选择与警告确认都交给用户)、状态可审计(产物图、任务勾选、标准输出摘要三处留痕)、同步不丢失(agent-driven 的 delta spec 智能合并 + .openspec.yaml 随目录保留)。理解这套归档 Skill,就等于掌握了整个 spec-driven 多模型协作流程的「最后一公里」——让每一次实现都能干净、可回溯地沉淀进仓库历史。
进一步阅读: