规范归档
归档已完成的变更提案，并将其规范差异合并到常驻规范文档中。
快速开始
归档包含两项主要操作：
- 移动变更目录至带时间戳的归档位置
- 合并规范差异到常驻规范（ADDED/MODIFIED/REMOVED）
关键规则：在归档前验证所有任务已完成。归档意味着已部署且完成。
工作流
复制此清单并跟踪进度：
归档进度:
- [ ] 第 1 步：验证实施完成
- [ ] 第 2 步：审阅待合并的规范差异
- [ ] 第 3 步：创建带时间戳的归档目录
- [ ] 第 4 步：合并 ADDED 需求到常驻规范
- [ ] 第 5 步：合并 MODIFIED 需求到常驻规范
- [ ] 第 6 步：合并 REMOVED 需求到常驻规范
- [ ] 第 7 步：移动变更目录到归档
- [ ] 第 8 步：验证常驻规范结构第 1 步：验证实施完成
在归档前确认所有工作已完成：
# 检查 IMPLEMENTED 标记
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ 已实施" || echo "✗ 未实施"
# 查看任务
cat spec/changes/{change-id}/tasks.json
# 使用 git 检查未提交工作
git status询问用户：
所有任务是否已完成并通过测试？
该变更是否已部署到生产？
是否继续归档？第 2 步：审阅待合并的规范差异
了解需要合并的内容：
# 列出所有规范差异文件
find spec/changes/{change-id}/specs -name "*.md" -type f
# 读取每个差异文件
for file in spec/changes/{change-id}/specs/**/*.md; do
echo "=== $file ==="
cat "$file"
done识别：
- 哪些能力受到影响
- ADDED/MODIFIED/REMOVED 各有多少需求
- 这些变更在常驻规范中的归属位置
第 3 步：创建带时间戳的归档目录
# 以当天日期创建归档目录
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}示例：
# 对 2025-10-26 归档的 "add-user-auth" 变更
mkdir -p spec/archive/2025-10-26-add-user-auth第 4 步：合并 ADDED 需求到常驻规范
对每个 ## ADDED Requirements 部分：
流程：
- 定位目标常驻规范文件
- 将新增需求追加到文件末尾
- 保持正确的 Markdown 格式
示例：
来源（spec/changes/add-user-auth/specs/authentication/spec-delta.md）：
## ADDED Requirements
### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。
#### Scenario: 登录成功
GIVEN 有效的凭据
WHEN 用户提交登录表单
THEN 系统创建会话目标（spec/specs/authentication/spec.md）：
# 追加到常驻规范
cat >> spec/specs/authentication/spec.md << 'EOF'
### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。
#### Scenario: 登录成功
GIVEN 有效的凭据
WHEN 用户提交登录表单
THEN 系统创建会话
EOF第 5 步：合并 MODIFIED 需求到常驻规范
对每个 ## MODIFIED Requirements 部分：
流程：
- 在常驻规范中定位现有需求
- 替换整个需求块（包括全部场景）
- 使用差异文件中的完整更新文本
示例（使用 sed）：
# 查找并替换需求块
# 这是概念示例——实际实现取决于结构
# 首先，确定旧需求的起始行
START_LINE=$(grep -n "### Requirement: 用户登录" spec/specs/authentication/spec.md | cut -d: -f1)
# 查找结束位置（下一个需求或文件末尾）
END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md | \
grep -n "^### Requirement:" | head -1 | cut -d: -f1)
# 删除旧需求
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md
# 在相同位置插入新需求
#（从差异文件提取并插入）手动方式（出于安全建议）：
1. 在编辑器中打开常驻规范
2. 通过名称查找目标需求
3. 删除整个块（需求 + 所有场景）
4. 将差异文件中的更新需求粘贴到该处
5. 保存第 6 步：合并 REMOVED 需求到常驻规范
对每个 ## REMOVED Requirements 部分：
流程：
- 在常驻规范中定位该需求
- 删除整个需求块
- 添加一条注释记录移除
示例：
# 方案 1：带注释删除
# 手动编辑 spec/specs/authentication/spec.md
# 添加弃用注释
echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md
# 通过手动或 sed 删除该需求块模式：
<!-- Removed 2025-10-26: 用户需使用基于邮件的密码重置 -->
~~### Requirement: SMS Password Reset~~第 7 步：将变更目录移动到归档
在所有差异合并后：
# 将完整的变更目录移动到归档
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}验证移动成功：
# 检查归档是否存在
ls -la spec/archive/${TIMESTAMP}-{change-id}
# 检查 changes 目录是否干净
ls spec/changes/ | grep "{change-id}" # 应无结果第 8 步：验证常驻规范结构
在合并后，验证常驻规范的完整性：
# 检查需求格式
grep -n "### Requirement:" spec/specs/**/*.md
# 检查场景格式
grep -n "#### Scenario:" spec/specs/**/*.md
# 统计每个规范中的需求数量
for spec in spec/specs/**/spec.md; do
count=$(grep -c "### Requirement:" "$spec")
echo "$spec: $count 条需求"
done手动审阅：
- 打开每个被修改的规范文件
- 验证 Markdown 格式正确
- 检查需求逻辑是否连贯
- 确保不存在重复需求
合并逻辑参考
ADDED 操作
动作：追加到常驻规范
位置：文件末尾（任何页脚/附录之前）
格式：按原文复制需求与全部场景MODIFIED 操作
动作：替换现有需求
位置：通过需求名称定位，替换整个块
格式：使用差异文件的完整更新文本（不拼接，直接替换）
说明：旧版本保留在归档中REMOVED 操作
动作：删除需求，并添加弃用注释
位置：通过需求名称定位
格式：删除整个块，可选添加 <!-- Removed YYYY-MM-DD: reason -->RENAMED 操作（不常见）
动作：更新需求名称，保留内容
位置：通过旧名称定位，更新为新名称
格式：仅修改标题：### Requirement: 新名称
说明：通常使用 MODIFIED 更为常见最佳实践
模式 1：移动前先验证
务必在移动到归档前验证差异合并：
# 合并后查看差异
git diff spec/specs/
# 审阅变更
git diff spec/specs/authentication/spec.md
# 若正确则提交
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth"
# 然后再归档
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth模式 2：原子化归档
归档整个变更，而非单个文件：
好：
# 移动完整变更目录
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth坏：
# 不要挑拣文件
mv spec/changes/add-user-auth/proposal.md spec/archive/
#（会留下孤儿文件）模式 3：归档保全
归档是历史记录。切勿修改归档文件：
❌ 不要：编辑 spec/archive/
✓ 要：将归档视为只读历史模式 4：Git 提交策略
推荐提交流程：
# 提交 1：合并差异
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth
- Added User Login requirement
- Modified Password Policy requirement
- Removed Legacy Auth requirement"
# 提交 2：归档变更
git add spec/archive/ spec/changes/
git commit -m "Archive add-user-auth change"进阶主题
复杂差异：见 reference/MERGE_LOGIC.md
冲突解决：若多个变更修改同一需求，需手动合并。
回滚策略：若需回滚归档，反向执行流程（从归档移回 changes，并从常驻规范移除已合并内容）。
常见模式
模式 1：简单新增
变更新增 1 条需求 → 追加到规范 → 归档模式 2：行为变更
变更修改 1 条需求 → 在规范中替换 → 归档模式 3：弃用
变更移除 1 条需求 → 删除并添加注释 → 归档模式 4：多需求的功能
变更在 2 个规范中新增 5 条需求
→ 分别追加到相应规范
→ 验证全部已合并
→ 归档反模式避免
不要：
- 归档未完成的实施
- 在部署前合并差异
- 修改归档文件
- 跳过合并后的验证
- 忘记在合并规范后进行 git 提交
要：
- 在归档前验证所有任务完成
- 小心且完整地合并差异
- 将归档视为不可变历史
- 验证合并后规范结构
- 在归档移动前提交合并后的规范
故障排查
问题：合并冲突（常驻规范已有该需求）
解决方案：
1. 若名称相同但内容不同 → 使用 MODIFIED 模式
2. 若确实是不同需求 → 重命名其中之一
3. 若属重复错误 → 选择正确版本问题：找不到需要修改/移除的需求
解决方案：
1. 按部分名称搜索：grep -i "login" spec/specs/**/*.md
2. 检查是否已被移除
3. 检查是否位于其他能力文件问题：合并后常驻规范格式错误
解决方案：
1. 手动修复格式
2. 重新运行验证：grep -n "###" spec/specs/**/*.md
3. 确保标题层级一致参考资料
- MERGE_LOGIC.md - 详细的合并操作规则
Token 预算：此 SKILL.md 约 430 行，低于建议的 500 行上限。