Back to Details

openspec-archiving-cn

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

规范归档

Specification Archiving

归档已完成的变更提案，并将其规范差异合并到常驻规范文档中。
Archive completed change proposals and merge their specification differences into permanent specification documents.

快速开始

Quick Start

归档包含两项主要操作：
  1. 移动变更目录至带时间戳的归档位置
  2. 合并规范差异到常驻规范（ADDED/MODIFIED/REMOVED）
关键规则：在归档前验证所有任务已完成。归档意味着已部署且完成。
Archiving includes two main operations:
  1. Move the change directory to a timestamped archive location
  2. Merge specification differences into permanent specifications (ADDED/MODIFIED/REMOVED)
Key Rule: Verify all tasks are completed before archiving. Archiving means the change has been deployed and completed.

工作流

Workflow

复制此清单并跟踪进度：
归档进度:
- [ ] 第 1 步：验证实施完成
- [ ] 第 2 步：审阅待合并的规范差异
- [ ] 第 3 步：创建带时间戳的归档目录
- [ ] 第 4 步：合并 ADDED 需求到常驻规范
- [ ] 第 5 步：合并 MODIFIED 需求到常驻规范
- [ ] 第 6 步：合并 REMOVED 需求到常驻规范
- [ ] 第 7 步：移动变更目录到归档
- [ ] 第 8 步：验证常驻规范结构
Copy this checklist to track progress:
Archiving Progress:
- [ ] Step 1: Verify implementation completion
- [ ] Step 2: Review specification differences to be merged
- [ ] Step 3: Create a timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into permanent specifications
- [ ] Step 5: Merge MODIFIED requirements into permanent specifications
- [ ] Step 6: Merge REMOVED requirements into permanent specifications
- [ ] Step 7: Move the change directory to archive
- [ ] Step 8: Verify permanent specification structure

第 1 步：验证实施完成

Step 1: Verify Implementation Completion

在归档前确认所有工作已完成：
bash
undefined
Confirm all work is completed before archiving:
bash
undefined

检查 IMPLEMENTED 标记

Check IMPLEMENTED marker

test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ 已实施" || echo "✗ 未实施"
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ Implemented" || echo "✗ Not implemented"

查看任务

View tasks

cat spec/changes/{change-id}/tasks.json
cat spec/changes/{change-id}/tasks.json

使用 git 检查未提交工作

Check uncommitted work using git

git status

**询问用户**：
```markdown
所有任务是否已完成并通过测试？
该变更是否已部署到生产？
是否继续归档？
git status

**Ask User**:
```markdown
Have all tasks been completed and passed testing?
Has this change been deployed to production?
Proceed with archiving?

第 2 步：审阅待合并的规范差异

Step 2: Review Specification Differences to Be Merged

了解需要合并的内容：
bash
undefined
Understand what needs to be merged:
bash
undefined

列出所有规范差异文件

List all specification difference files

find spec/changes/{change-id}/specs -name "*.md" -type f
find spec/changes/{change-id}/specs -name "*.md" -type f

读取每个差异文件

Read each difference file

for file in spec/changes/{change-id}/specs/**/*.md; do echo "=== $file ===" cat "$file" done

**识别**：
- 哪些能力受到影响
- ADDED/MODIFIED/REMOVED 各有多少需求
- 这些变更在常驻规范中的归属位置
for file in spec/changes/{change-id}/specs/**/*.md; do echo "=== $file ===" cat "$file" done

**Identify**:
- Which capabilities are affected
- Number of ADDED/MODIFIED/REMOVED requirements
- Where these changes belong in the permanent specifications

第 3 步：创建带时间戳的归档目录

Step 3: Create a Timestamped Archive Directory

bash
undefined
bash
undefined

以当天日期创建归档目录

Create archive directory with today's date

TIMESTAMP=$(date +%Y-%m-%d) mkdir -p spec/archive/${TIMESTAMP}-{change-id}

**示例**：
```bash
TIMESTAMP=$(date +%Y-%m-%d) mkdir -p spec/archive/${TIMESTAMP}-{change-id}

**Example**:
```bash

对 2025-10-26 归档的 "add-user-auth" 变更

For "add-user-auth" change archived on 2025-10-26

mkdir -p spec/archive/2025-10-26-add-user-auth
undefined
mkdir -p spec/archive/2025-10-26-add-user-auth
undefined

第 4 步：合并 ADDED 需求到常驻规范

Step 4: Merge ADDED Requirements into Permanent Specifications

对每个 
## ADDED Requirements
部分：
流程：
  1. 定位目标常驻规范文件
  2. 将新增需求追加到文件末尾
  3. 保持正确的 Markdown 格式
示例：
来源（
spec/changes/add-user-auth/specs/authentication/spec-delta.md
）：
markdown
undefined
For each 
## ADDED Requirements
section:
Process:
  1. Locate the target permanent specification 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
):
markdown
undefined

ADDED Requirements

ADDED Requirements

Requirement: 用户登录

Requirement: User Login

WHEN 用户提交有效凭据, 系统 SHALL 认证用户并创建会话。
WHEN a user submits valid credentials, the system SHALL authenticate the user and create a session.

Scenario: 登录成功

Scenario: Successful Login

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

**目标**（`spec/specs/authentication/spec.md`）：
```bash
GIVEN valid credentials WHEN the user submits the login form THEN the system creates a session

**Target** (`spec/specs/authentication/spec.md`):
```bash

追加到常驻规范

Append to permanent specification

cat >> spec/specs/authentication/spec.md << 'EOF'
cat >> spec/specs/authentication/spec.md << 'EOF'

Requirement: 用户登录

Requirement: User Login

WHEN 用户提交有效凭据, 系统 SHALL 认证用户并创建会话。
WHEN a user submits valid credentials, the system SHALL authenticate the user and create a session.

Scenario: 登录成功

Scenario: Successful Login

GIVEN 有效的凭据 WHEN 用户提交登录表单 THEN 系统创建会话 EOF
undefined
GIVEN valid credentials WHEN the user submits the login form THEN the system creates a session EOF
undefined

第 5 步：合并 MODIFIED 需求到常驻规范

Step 5: Merge MODIFIED Requirements into Permanent Specifications

对每个 
## MODIFIED Requirements
部分：
流程：
  1. 在常驻规范中定位现有需求
  2. 替换整个需求块（包括全部场景）
  3. 使用差异文件中的完整更新文本
示例（使用 sed）：
bash
undefined
For each 
## MODIFIED Requirements
section:
Process:
  1. Locate the existing requirement in the permanent specification
  2. Replace the entire requirement block (including all scenarios)
  3. Use the complete updated text from the difference file
Example (using sed):
bash
undefined

查找并替换需求块

Find and replace requirement block

这是概念示例——实际实现取决于结构

This is a conceptual example - actual implementation depends on structure

首先，确定旧需求的起始行

First, determine the start line of the old requirement

START_LINE=$(grep -n "### Requirement: 用户登录" spec/specs/authentication/spec.md | cut -d: -f1)
START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)

查找结束位置（下一个需求或文件末尾）

Find the end position (next requirement or end of file)

END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md |
grep -n "^### Requirement:" | head -1 | cut -d: -f1)
END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md |
grep -n "^### Requirement:" | head -1 | cut -d: -f1)

删除旧需求

Delete the old requirement

sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md

在相同位置插入新需求

Insert the new requirement at the same position

—

(Extract from difference file and insert)

#（从差异文件提取并插入）

**手动方式**（出于安全建议）：
```markdown
1. 在编辑器中打开常驻规范
2. 通过名称查找目标需求
3. 删除整个块（需求 + 所有场景）
4. 将差异文件中的更新需求粘贴到该处
5. 保存

**Manual Method** (recommended for safety):
```markdown
1. Open the permanent specification in an editor
2. Locate the target requirement by name
3. Delete the entire block (requirement + all scenarios)
4. Paste the updated requirement from the difference file in its place
5. Save

第 6 步：合并 REMOVED 需求到常驻规范

Step 6: Merge REMOVED Requirements into Permanent Specifications

对每个 
## REMOVED Requirements
部分：
流程：
  1. 在常驻规范中定位该需求
  2. 删除整个需求块
  3. 添加一条注释记录移除
示例：
bash
undefined
For each 
## REMOVED Requirements
section:
Process:
  1. Locate the requirement in the permanent specification
  2. Delete the entire requirement block
  3. Add a comment to record the removal
Example:
bash
undefined

方案 1：带注释删除

Option 1: Delete with comment

手动编辑 spec/specs/authentication/spec.md

Manually edit spec/specs/authentication/spec.md

添加弃用注释

Add deprecation comment

echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md
echo "<!-- Requirement 'Legacy Password Reset' removed $(date +%Y-%m-%d) -->" >> spec/specs/authentication/spec.md

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

Delete the requirement block manually or via sed


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

**Pattern**:
```markdown
<!-- Removed 2025-10-26: Users must use email-based password reset -->
~~### Requirement: SMS Password Reset~~

第 7 步：将变更目录移动到归档

Step 7: Move the Change Directory to Archive

在所有差异合并后：
bash
undefined
After merging all differences:
bash
undefined

将完整的变更目录移动到归档

Move the complete change directory to archive

mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

**验证移动成功**：
```bash
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

**Verify Successful Move**:
```bash

检查归档是否存在

Check if archive exists

ls -la spec/archive/${TIMESTAMP}-{change-id}
ls -la spec/archive/${TIMESTAMP}-{change-id}

检查 changes 目录是否干净

Check if changes directory is clean

ls spec/changes/ | grep "{change-id}" # 应无结果
undefined
ls spec/changes/ | grep "{change-id}" # Should return no results
undefined

第 8 步：验证常驻规范结构

Step 8: Verify Permanent Specification Structure

在合并后，验证常驻规范的完整性：
bash
undefined
After merging, verify the integrity of the permanent specifications:
bash
undefined

检查需求格式

Check requirement formatting

grep -n "### Requirement:" spec/specs/**/*.md
grep -n "### Requirement:" spec/specs/**/*.md

检查场景格式

Check scenario formatting

grep -n "#### Scenario:" spec/specs/**/*.md
grep -n "#### Scenario:" spec/specs/**/*.md

统计每个规范中的需求数量

Count number of requirements in each specification

for spec in spec/specs/**/spec.md; do count=$(grep -c "### Requirement:" "$spec") echo "$spec: $count 条需求" done

**手动审阅**：
- 打开每个被修改的规范文件
- 验证 Markdown 格式正确
- 检查需求逻辑是否连贯
- 确保不存在重复需求
for spec in spec/specs/**/spec.md; do count=$(grep -c "### Requirement:" "$spec") echo "$spec: $count requirements" done

**Manual Review**:
- Open each modified specification file
- Verify correct Markdown formatting
- Check that requirement logic is consistent
- Ensure no duplicate requirements exist

合并逻辑参考

Merge Logic Reference

ADDED 操作

ADDED Operation

动作：追加到常驻规范
位置：文件末尾（任何页脚/附录之前）
格式：按原文复制需求与全部场景
Action: Append to permanent specification
Location: End of file (before any footnotes/appendices)
Format: Copy requirements and all scenarios exactly as written

MODIFIED 操作

MODIFIED Operation

动作：替换现有需求
位置：通过需求名称定位，替换整个块
格式：使用差异文件的完整更新文本（不拼接，直接替换）
说明：旧版本保留在归档中
Action: Replace existing requirement
Location: Locate by requirement name, replace entire block
Format: Use complete updated text from difference file (no splicing, direct replacement)
Note: Old version is preserved in archive

REMOVED 操作

REMOVED Operation

动作：删除需求，并添加弃用注释
位置：通过需求名称定位
格式：删除整个块，可选添加 <!-- Removed YYYY-MM-DD: reason -->
Action: Delete requirement and add deprecation comment
Location: Locate by requirement name
Format: Delete entire block, optionally add <!-- Removed YYYY-MM-DD: reason -->

RENAMED 操作（不常见）

RENAMED Operation (Uncommon)

动作：更新需求名称，保留内容
位置：通过旧名称定位，更新为新名称
格式：仅修改标题：### Requirement: 新名称
说明：通常使用 MODIFIED 更为常见
Action: Update requirement name, retain content
Location: Locate by old name, update to new name
Format: Only modify the title: ### Requirement: New Name
Note: MODIFIED is typically used more often

最佳实践

Best Practices

模式 1：移动前先验证

Pattern 1: Validate Before Moving

务必在移动到归档前验证差异合并：
bash
undefined
Always verify difference merging before moving to archive:
bash
undefined

合并后查看差异

View differences after merging

git diff spec/specs/
git diff spec/specs/

审阅变更

Review changes

git diff spec/specs/authentication/spec.md
git diff spec/specs/authentication/spec.md

若正确则提交

Commit if correct

git add spec/specs/ git commit -m "Merge spec deltas from add-user-auth"
git add spec/specs/ git commit -m "Merge spec deltas from add-user-auth"

然后再归档

Then archive

mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth
undefined
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth
undefined

模式 2：原子化归档

Pattern 2: Atomic Archiving

归档整个变更，而非单个文件：
好：
bash
undefined
Archive the entire change, not individual files:
Good:
bash
undefined

移动完整变更目录

Move complete change directory

mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

**坏**：
```bash
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

**Bad**:
```bash

不要挑拣文件

Don't pick individual files

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

模式 3：归档保全

(Leaves orphaned files)

归档是历史记录。切勿修改归档文件：
markdown
❌ 不要：编辑 spec/archive/
✓ 要：将归档视为只读历史
undefined

模式 4：Git 提交策略

Pattern 3: Archive Preservation

推荐提交流程：
bash
undefined
Archives are historical records. Never modify archived files:
markdown
❌ Don't: Edit spec/archive/
✓ Do: Treat archives as read-only history

提交 1：合并差异

Pattern 4: Git Commit Strategy

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"
Recommended commit flow:
bash
undefined

提交 2：归档变更

Commit 1: Merge differences

git add spec/archive/ spec/changes/ git commit -m "Archive add-user-auth change"
undefined
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"

进阶主题

Commit 2: Archive change

复杂差异：见 reference/MERGE_LOGIC.md
冲突解决：若多个变更修改同一需求，需手动合并。
回滚策略：若需回滚归档，反向执行流程（从归档移回 changes，并从常驻规范移除已合并内容）。
git add spec/archive/ spec/changes/ git commit -m "Archive add-user-auth change"
undefined

常见模式

Advanced Topics

模式 1：简单新增

—
markdown
变更新增 1 条需求 → 追加到规范 → 归档
Complex Differences: See reference/MERGE_LOGIC.md
Conflict Resolution: If multiple changes modify the same requirement, manual merging is required.
Rollback Strategy: If archiving needs to be rolled back, reverse the process (move from archive back to changes, and remove merged content from permanent specifications).

模式 2：行为变更

Common Patterns

—

Pattern 1: Simple Addition

markdown
变更修改 1 条需求 → 在规范中替换 → 归档
markdown
Change adds 1 requirement → Append to specification → Archive

模式 3：弃用

Pattern 2: Behavior Change

markdown
变更移除 1 条需求 → 删除并添加注释 → 归档
markdown
Change modifies 1 requirement → Replace in specification → Archive

模式 4：多需求的功能

Pattern 3: Deprecation

markdown
变更在 2 个规范中新增 5 条需求
→ 分别追加到相应规范
→ 验证全部已合并
→ 归档
markdown
Change removes 1 requirement → Delete and add comment → Archive

反模式避免

Pattern 4: Multi-Requirement Feature

不要：
  • 归档未完成的实施
  • 在部署前合并差异
  • 修改归档文件
  • 跳过合并后的验证
  • 忘记在合并规范后进行 git 提交
要：
  • 在归档前验证所有任务完成
  • 小心且完整地合并差异
  • 将归档视为不可变历史
  • 验证合并后规范结构
  • 在归档移动前提交合并后的规范
markdown
Change adds 5 requirements across 2 specifications
→ Append to respective specifications
→ Verify all are merged
→ Archive

故障排查

Anti-Patterns to Avoid

问题：合并冲突（常驻规范已有该需求）

—
解决方案：
markdown
1. 若名称相同但内容不同 → 使用 MODIFIED 模式
2. 若确实是不同需求 → 重命名其中之一
3. 若属重复错误 → 选择正确版本
Don't:
  • Archive incomplete implementations
  • Merge differences before deployment
  • Modify archived files
  • Skip post-merge verification
  • Forget to git commit after merging specifications
Do:
  • Verify all tasks are completed before archiving
  • Merge differences carefully and completely
  • Treat archives as immutable history
  • Verify merged specification structure
  • Commit merged specifications before moving to archive

问题：找不到需要修改/移除的需求

Troubleshooting

—

Issue: Merge Conflict (Requirement already exists in permanent specification)

解决方案：
markdown
1. 按部分名称搜索：grep -i "login" spec/specs/**/*.md
2. 检查是否已被移除
3. 检查是否位于其他能力文件
Solution:
markdown
1. If same name but different content → Use MODIFIED mode
2. If truly different requirements → Rename one of them
3. If it's a duplication error → Select the correct version

问题：合并后常驻规范格式错误

Issue: Cannot find requirement to modify/remove

解决方案：
markdown
1. 手动修复格式
2. 重新运行验证：grep -n "###" spec/specs/**/*.md
3. 确保标题层级一致
Solution:
markdown
1. Search by partial name: grep -i "login" spec/specs/**/*.md
2. Check if it was already removed
3. Check if it's located in another capability file

参考资料

Issue: Permanent specification formatting is incorrect after merging

  • MERGE_LOGIC.md - 详细的合并操作规则
Token 预算：此 SKILL.md 约 430 行，低于建议的 500 行上限。
Solution:
markdown
1. Fix formatting manually
2. Re-run verification: grep -n "###" spec/specs/**/*.md
3. Ensure consistent heading levels
—

References

—
  • MERGE_LOGIC.md - Detailed merge operation rules
Token Budget: This SKILL.md is approximately 430 lines, below the recommended 500-line limit.