SuperAPI AI 工具集

openspec-archiving-cn

办公与效率

查看项目

更新于 10-15 11:52

技能介绍

用途

本技能用于在规范驱动开发流程中归档已完成的变更提案,并把变更内的规范差异(spec delta)合并到常驻规范文档中。它强调归档意味着变更已经部署且完成,因此归档前需要先验证所有任务已完成。

主要能力

归档过程包含两项主要操作:一是将变更目录移动到带时间戳的归档位置,二是把规范差异合并到常驻规范,涵盖 ADDED、MODIFIED、REMOVED 三类操作(资料还提及不常见的 RENAMED)。

工作流分为八个步骤:

  1. 验证实施完成:检查 IMPLEMENTED 标记、查看 tasks.json、用 git status 检查未提交工作,并向用户确认任务是否完成、是否已部署、是否继续归档。
  2. 审阅待合并的规范差异:列出并读取 spec/changes/{change-id}/specs 下的差异文件,识别受影响能力、各类需求数量及归属位置。
  3. 创建带时间戳的归档目录:如 spec/archive/2025-10-26-add-user-auth。
  4. 合并 ADDED 需求:定位目标常驻规范文件,将新增需求追加到文件末尾,保持 Markdown 格式。
  5. 合并 MODIFIED 需求:定位现有需求,替换整个需求块(含全部场景),使用差异文件中的完整更新文本;资料提供了 sed 概念示例并建议手动编辑更安全。
  6. 合并 REMOVED 需求:定位并删除整个需求块,可添加弃用注释记录移除日期与原因。
  7. 移动变更目录到归档:将完整变更目录移动至归档,并验证移动成功、原 changes 目录干净。
  8. 验证常驻规范结构:检查 Requirement 与 Scenario 格式,统计需求数量,手动审阅格式、逻辑连贯性与重复情况。

资料还给出合并逻辑参考(ADDED 追加、MODIFIED 替换、REMOVED 删除并加注释、RENAMED 仅改标题)、最佳实践(合并前验证、原子化归档、归档只读、Git 提交策略,建议先提交合并后的规范再提交归档)、常见模式、反模式与故障排查指引,以及参考文件 reference/MERGE_LOGIC.md 用于复杂差异。

使用方式

资料提供的是基于命令行的操作清单,包含 git、mkdir、mv、grep、sed 等命令示例,以及“复制清单并跟踪进度”的工作流。使用时应按八步清单执行,并在归档前向用户确认关键问题。

适用场景

适用于变更已部署、准备归档,或实施完成后需要将规范差异更新到常驻规范文档的场景。

限制

资料明确指出:归档前必须验证所有任务完成;归档应视为不可变历史,不应修改归档文件;多个变更修改同一需求时需手动合并;若需回滚归档,需反向执行流程。部分步骤(如 MODIFIED 的 sed 处理)属于概念示例,实际实现取决于规范结构,资料建议采用手动编辑方式。关于官方价格、平台或支持范围等信息,资料暂未提供。