openspec-archiving-cn
归档已完成的变更并将规范差异合并到常驻文档。用于变更已部署、准备归档或实施后需要更新规范时。触发词包括 "openspec归档", "归档", "归档提案", "合并规范", "完成提案", "更新文档", "定稿规范", "标记完成"。
By forztf · 363 installs
npx skills add forztf/open-skilled-sdd --skill openspec-archiving-cn
Source repository · Upstream listing
规范归档
归档已完成的变更提案，并将其规范差异合并到常驻规范文档中。
快速开始
归档包含两项主要操作：
1. 移动变更目录 至带时间戳的归档位置
2. 合并规范差异 到常驻规范（ADDED/MODIFIED/REMOVED）
关键规则 ：在归档前验证所有任务已完成。归档意味着已部署且完成。
工作流
复制此清单并跟踪进度：
第 1 步：验证实施完成
在归档前确认所有工作已完成：
询问用户 ：
第 2 步：审阅待合并的规范差异
了解需要合并的内容：
识别 ：
哪些能力受到影响
ADDED/MODIFIED/REMOVED 各有多少需求
这些变更在常驻规范中的归属位置
第 3 步：创建带时间戳的归档目录
示例 ：
第 4 步：合并 ADDED 需求到常驻规范
对每个 ADDED Requirements 部分：
流程 ：
1. 定位目标常驻规范文件
2. 将新增需求追加到文件末尾
3. 保持正确的 Markdown 格式
示例 ：
来源 （ spec/changes/add user auth/specs/authentication/spec delta.md ）：
目标 （ spec/specs/authentication/spec.md ）：
第 5 步：合并 MODIFIED 需求到常驻规范
对每个 MODIFIED Requirements 部分：
流程 ：
1. 在常驻规范中定位现有需求
2. 替换 整个 需求块（包括全部场景）
3. 使用差异文件中的完整更新文本
示例（使用 sed） ：
手动方式 （出于安全建议）：
第 6 步：合并 REMOVED 需求到常驻规范
对每个 REMOVED Requirements 部分：
流程 ：
1. 在常驻规范中定位该需求
2. 删除整个需求块
3. 添加一条注释记录移除
示例 ：
模式 ：
第 7 步：将变更目录移动到归档
在所有差异合并后：
验证移动成功 ：
第 8 步：验证常驻规范结构
在合并后，验证常驻规范的完整性：
手动审阅 ：
打开每个被修改的规范文件
验证 Markdown 格式正确
检查需求逻辑是否连贯
确保不存在重复需求
合并逻辑参考
ADDED 操作
MODIFIED 操作
REMOVED 操作
RENAMED 操作（不常见）
最佳实践
模式 1：移动前先验证
务必 在移动到归档前验证差异合并：
模式 2：原子化归档
归档整个变更，而非单个文件：
好 ：
坏 ：
模式 3：归档保全
归档是历史记录。切勿修改归档文件：
模式 4：Git 提交策略
推荐提交流程：
进阶主题
复杂差异 ：见 [reference/MERGE LOGIC.md](reference/MERGE LOGIC.md)
冲突解决 ：若多个变更修改同一需求，需手动合并。
回滚策略 ：若需回滚归档，反向执行流程（从归档移回 changes，并从常驻规范移除已合并内容）。
常见模式
模式 1：简单新增
模式 2：行为变更
模式 3：弃用
模式 4：多需求的功能
反模式避免
不要 ：
归档未完成的实施
在部署前合并差异
修改归档文件
跳过合并后的验证
忘记在合并规范后进行 git 提交
要 ：
在归档前验证所有任务完成
小心且完整地合并差异
将归档视为不可变历史
验证合并后规范结构
在归档移动前提交合并后的规范
故障排查
问题：合并冲突（常驻规范已有该需求）
解决方案 ：
问题：找不到需要修改/移除的需求
解决方案 ：
问题：合并后常驻规范格式错误
解决方案 ：
参考资料
[MERGE LOGIC.md](reference/MERGE LOGIC.md) 详细的合并操作规则
Token 预算 ：此 SKILL.md 约 430 行，低于建议的 500 行上限。