SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsopenspec-archiving-cn

openspec-archiving-cn

Office & productivity

View repository

Updated 10-15 11:52

About this skill

Spec archiving

Archive completed change proposals and merge their spec deltas into the permanent spec documents.

Quick start

Archiving contains two main operations:

  1. Move the change directoryto a timestamped archive location
  2. Merge spec deltasinto the permanent spec (ADDED/MODIFIED/REMOVED)

Key rule: Verify that all tasks are complete before archiving. Archiving means deployed and complete.

Workflow

Copy this checklist and track progress:

归档进度:
- [ ] 第 1 步：验证实施完成
- [ ] 第 2 步：审阅待合并的规范差异
- [ ] 第 3 步：创建带时间戳的归档目录
- [ ] 第 4 步：合并 ADDED 需求到常驻规范
- [ ] 第 5 步：合并 MODIFIED 需求到常驻规范
- [ ] 第 6 步：合并 REMOVED 需求到常驻规范
- [ ] 第 7 步：移动变更目录到归档
- [ ] 第 8 步：验证常驻规范结构

Step 1: Verify implementation is complete

Confirm that all work is complete before archiving:

# 检查 IMPLEMENTED 标记
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ 已实施" || echo "✗ 未实施"

# 查看任务
cat spec/changes/{change-id}/tasks.json

# 使用 git 检查未提交工作
git status

Ask the user：

所有任务是否已完成并通过测试？
该变更是否已部署到生产？
是否继续归档？

Step 2: Review the spec deltas to be merged

Understand what needs to be merged:

# 列出所有规范差异文件
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

Identify：

  • which capabilities are affected
  • how many requirements are in each of ADDED/MODIFIED/REMOVED
  • where these changes belong in the permanent spec

Step 3: Create a timestamped archive directory

# 以当天日期创建归档目录
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}

Example：

# 对 2025-10-26 归档的 "add-user-auth" 变更
mkdir -p spec/archive/2025-10-26-add-user-auth

Step 4: Merge ADDED requirements into the permanent spec

For each ## ADDED Requirements section:

Process：

  1. Locate the target permanent spec file
  2. Append the new requirements to the end of the file
  3. Maintain correct Markdown formatting

Example：

Source（spec/changes/add-user-auth/specs/authentication/spec-delta.md）：

## ADDED Requirements

### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。

#### Scenario: 登录成功
GIVEN 有效的凭据
WHEN 用户提交登录表单
THEN 系统创建会话

Target（spec/specs/authentication/spec.md）：

# 追加到常驻规范
cat >> spec/specs/authentication/spec.md << 'EOF'

### Requirement: 用户登录
WHEN 用户提交有效凭据,
系统 SHALL 认证用户并创建会话。

#### Scenario: 登录成功
GIVEN 有效的凭据
WHEN 用户提交登录表单
THEN 系统创建会话
EOF

Step 5: Merge MODIFIED requirements into the permanent spec

For each ## MODIFIED Requirements section:

Process：

  1. Locate the existing requirement in the permanent spec
  2. Replacethe entirerequirement block (including all scenarios)
  3. Use the complete updated text from the delta file

Example (using 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

# 在相同位置插入新需求
#（从差异文件提取并插入）

Manual method(recommended for safety):

1. 在编辑器中打开常驻规范
2. 通过名称查找目标需求
3. 删除整个块（需求 + 所有场景）
4. 将差异文件中的更新需求粘贴到该处
5. 保存

Step 6: Merge REMOVED requirements into the permanent spec

For each ## REMOVED Requirements section:

Process：

  1. Locate the requirement in the permanent spec
  2. Delete the entire requirement block
  3. Add a comment recording the removal

Example：

# 方案 1：带注释删除
# 手动编辑 spec/specs/authentication/spec.md

# 添加弃用注释
echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md

# 通过手动或 sed 删除该需求块

Pattern：

<!-- Removed 2025-10-26: 用户需使用基于邮件的密码重置 -->
~~### Requirement: SMS Password Reset~~

Step 7: Move the change directory to the archive

After all deltas are merged:

# 将完整的变更目录移动到归档
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

Verify the move succeeded：

# 检查归档是否存在
ls -la spec/archive/${TIMESTAMP}-{change-id}

# 检查 changes 目录是否干净
ls spec/changes/ | grep "{change-id}"  # 应无结果

Step 8: Verify the permanent spec structure

After merging, verify the integrity of the permanent spec:

# 检查需求格式
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

Manual review：

  • Open each modified spec file
  • Verify the Markdown formatting is correct
  • Check whether the requirements are logically coherent
  • Ensure there are no duplicate requirements

Merge logic reference

ADDED operation

动作：追加到常驻规范
位置：文件末尾（任何页脚/附录之前）
格式：按原文复制需求与全部场景

MODIFIED operation

动作：替换现有需求
位置：通过需求名称定位，替换整个块
格式：使用差异文件的完整更新文本（不拼接，直接替换）
说明：旧版本保留在归档中

REMOVED operation

动作：删除需求，并添加弃用注释
位置：通过需求名称定位
格式：删除整个块，可选添加 <!-- Removed YYYY-MM-DD: reason -->

RENAMED operation (uncommon)

动作：更新需求名称，保留内容
位置：通过旧名称定位，更新为新名称
格式：仅修改标题：### Requirement: 新名称
说明：通常使用 MODIFIED 更为常见

Best practices

Pattern 1: Verify before moving

AlwaysVerify diff merge before moving to archive:

# 合并后查看差异
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

Pattern 2: Atomic Archiving

Archive the entire change, not individual files:

Good：

# 移动完整变更目录
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

Bad：

# 不要挑拣文件
mv spec/changes/add-user-auth/proposal.md spec/archive/
#（会留下孤儿文件）

Pattern 3: Archive Preservation

Archives are historical records. Never modify archived files:

❌ 不要：编辑 spec/archive/
✓ 要：将归档视为只读历史

Pattern 4: Git Commit Strategy

Recommended commit flow:

# 提交 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"

Advanced Topics

Complex Diffs: See reference/MERGE_LOGIC.md

Conflict Resolution: If multiple changes modify the same requirement, manual merging is required.

Rollback Strategy: If an archive needs to be rolled back, execute the process in reverse (move from archive back to changes, and remove merged content from the permanent specs).

Common Patterns

Pattern 1: Simple Addition

变更新增 1 条需求 → 追加到规范 → 归档

Pattern 2: Behavior Change

变更修改 1 条需求 → 在规范中替换 → 归档

Pattern 3: Deprecation

变更移除 1 条需求 → 删除并添加注释 → 归档

Pattern 4: Multi-Requirement Feature

变更在 2 个规范中新增 5 条需求
→ 分别追加到相应规范
→ 验证全部已合并
→ 归档

Anti-Patterns to Avoid

Don't：

  • Archive incomplete implementations
  • Merge diffs before deployment
  • Modify archived files
  • Skip post-merge verification
  • Forget to make a git commit after merging specs

Do：

  • Verify all tasks are complete before archiving
  • Merge diffs carefully and completely
  • Treat archives as immutable history
  • Verify the spec structure after merging
  • Commit the merged specs before the archive move

Troubleshooting

Problem: Merge conflict (the permanent spec already has this requirement)

Solution：

1. 若名称相同但内容不同 → 使用 MODIFIED 模式
2. 若确实是不同需求 → 重命名其中之一
3. 若属重复错误 → 选择正确版本

Problem: Cannot find the requirement to modify/remove

Solution：

1. 按部分名称搜索：grep -i "login" spec/specs/**/*.md
2. 检查是否已被移除
3. 检查是否位于其他能力文件

Problem: Malformed permanent spec after merging

Solution：

1. 手动修复格式
2. 重新运行验证：grep -n "###" spec/specs/**/*.md
3. 确保标题层级一致

References

Token Budget: This SKILL.md is about 430 lines, below the recommended 500-line limit.