规范归档指南：变更提案归档与规范增量合并工作流程详解

openspec-archiving by forztf/open-skilled-sdd

137 周安装量

6 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/forztf/open-skilled-sdd --skill openspec-archiving

软件工程技术文档版本控制

🇨🇳中文介绍

规范归档

归档已完成的变更提案，并将其规范增量合并到现行规范文档中。

快速开始

归档涉及两个主要操作：

将变更文件夹移动到带时间戳的归档目录
将规范增量合并到现行规范中（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.md

# 检查 git 状态以查看未提交的工作
git status

询问用户：

所有任务都已完成并测试了吗？
此变更是否已部署到生产环境？
我应该继续归档吗？

步骤 2：审查要合并的规范增量

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 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: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session

目标文件 (spec/specs/authentication/spec.md)：

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

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session
EOF

步骤 5：将 MODIFIED 需求合并到现行规范中

对于每个 ## MODIFIED Requirements 部分：

在现行规范中找到现有需求
替换整个需求块（包括所有场景）
使用增量中的完整更新文本

使用 sed 的示例：

# 查找并替换需求块
# 这是概念性的 - 实际实现取决于结构

# 首先，确定旧需求的行范围
START_LINE=$(grep -n "### Requirement: User Login" 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: User must use email-based password reset -->
~~### Requirement: SMS Password Reset~~

步骤 7：将变更文件夹移动到归档目录

所有增量合并后：

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

验证移动是否成功：

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

# 检查变更目录是否已清理
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 requirements"
done

打开每个修改过的规范文件
验证 Markdown 格式是否正确
检查需求流程是否合乎逻辑
确保没有重复的需求

Action: Append to living spec
Location: End of file (before any footer/appendix)
Format: Copy requirement + all scenarios exactly as written

Action: Replace existing requirement
Location: Find by requirement name, replace entire block
Format: Use complete updated text from delta (don't merge, replace)
Note: Old version is preserved in archive

Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add <!-- Removed YYYY-MM-DD: reason -->

RENAMED 操作（不常见）

Action: Update requirement name, keep content
Location: Find by old name, update to new name
Format: Just change the header: ### Requirement: NewName
Note: Typically use MODIFIED instead

模式 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

冲突解决：如果多个变更修改了同一需求，则需要手动合并。

回滚策略：要回滚归档，请反转过程（将归档移回变更目录，从现行规范中移除合并的内容）。

模式 1：简单添加

Change adds 1 new requirement → Append to spec → Archive

模式 2：行为变更

Change modifies 1 requirement → Replace in spec → Archive

Change removes 1 requirement → Delete from spec with comment → Archive

模式 4：包含多个需求的功能

Change adds 5 requirements across 2 specs
→ Append each to respective spec
→ Verify all are merged
→ Archive

要避免的反模式

归档不完整的实现
在部署前合并增量
修改已归档的文件
合并后跳过验证
忘记 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 大约 480 行，低于推荐的 500 行限制。

🇺🇸English

Specification Archiving

Archives completed change proposals and merges their spec deltas into the living specification documentation.

Quick Start

Archiving involves two main operations:

Move change folder to archive with timestamp
Merge spec deltas into living specs (ADDED/MODIFIED/REMOVED operations)

Critical rule : Verify all tasks are complete before archiving. Archiving signifies deployment and completion.

Workflow

Copy this checklist and track progress:

Archive Progress:
- [ ] Step 1: Verify implementation is complete
- [ ] Step 2: Review spec deltas to merge
- [ ] Step 3: Create timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into living specs
- [ ] Step 5: Merge MODIFIED requirements into living specs
- [ ] Step 6: Merge REMOVED requirements into living specs
- [ ] Step 7: Move change folder to archive
- [ ] Step 8: Validate living spec structure

Step 1: Verify implementation is complete

Before archiving, confirm all work is done:

# Check for IMPLEMENTED marker
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ Implemented" || echo "✗ Not implemented"

# Review tasks
cat spec/changes/{change-id}/tasks.md

# Check git status for uncommitted work
git status

Ask the user :

Are all tasks complete and tested?
Has this change been deployed to production?
Should I proceed with archiving?

Step 2: Review spec deltas to merge

Understand what will be merged:

# List all spec delta files
find spec/changes/{change-id}/specs -name "*.md" -type f

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

Identify :

Which capabilities are affected
How many requirements are ADDED/MODIFIED/REMOVED
Where in living specs these changes belong

Step 3: Create timestamped archive directory

# Create archive with today's date
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}

Example :

# For change "add-user-auth" archived on Oct 26, 2025
mkdir -p spec/archive/2025-10-26-add-user-auth

Step 4: Merge ADDED requirements into living specs

For each ## ADDED Requirements section:

Process :

Locate the target living spec file
Append the new requirements to the end of the file
Maintain proper markdown formatting

Example :

Source (spec/changes/add-user-auth/specs/authentication/spec-delta.md):

## ADDED Requirements

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session

Target (spec/specs/authentication/spec.md):

# Append to living spec
cat >> spec/specs/authentication/spec.md << 'EOF'

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session
EOF

Step 5: Merge MODIFIED requirements into living specs

For each ## MODIFIED Requirements section:

Process :

Locate the existing requirement in the living spec
Replace the ENTIRE requirement block (including all scenarios)
Use the complete updated text from the delta

Example using sed :

# Find and replace requirement block
# This is conceptual - actual implementation depends on structure

# First, identify the line range of the old requirement
START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)

# Find the end (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)

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

# Insert new requirement at same position
# (Extract from delta and insert)

Manual approach (recommended for safety):

1. Open living spec in editor
2. Find the requirement by name
3. Delete entire block (requirement + all scenarios)
4. Paste updated requirement from delta
5. Save

Step 6: Merge REMOVED requirements into living specs

For each ## REMOVED Requirements section:

Process :

Locate the requirement in the living spec
Delete the entire requirement block
Add a comment documenting the removal

Example :

# Option 1: Delete with comment
# 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

# Delete the requirement block manually or with sed

Pattern :

<!-- Removed 2025-10-26: User must use email-based password reset -->
~~### Requirement: SMS Password Reset~~

Step 7: Move change folder to archive

After all deltas are merged:

# Move entire change folder to archive
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

Verify move succeeded :

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

# Check changes directory is clean
ls spec/changes/ | grep "{change-id}"  # Should return nothing

Step 8: Validate living spec structure

After merging, validate the living specs are well-formed:

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

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

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

Manual review :

Open each modified spec file
Verify markdown formatting is correct
Check requirements flow logically
Ensure no duplicate requirements exist

Merge Logic Reference

ADDED Operation

Action: Append to living spec
Location: End of file (before any footer/appendix)
Format: Copy requirement + all scenarios exactly as written

MODIFIED Operation

Action: Replace existing requirement
Location: Find by requirement name, replace entire block
Format: Use complete updated text from delta (don't merge, replace)
Note: Old version is preserved in archive

REMOVED Operation

Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add <!-- Removed YYYY-MM-DD: reason -->

RENAMED Operation (uncommon)

Action: Update requirement name, keep content
Location: Find by old name, update to new name
Format: Just change the header: ### Requirement: NewName
Note: Typically use MODIFIED instead

Best Practices

Pattern 1: Verify Before Moving

Always verify delta merges before moving to archive:

# After merging, check diff
git diff spec/specs/

# Review changes
git diff spec/specs/authentication/spec.md

# If correct, commit
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

Pattern 2: Atomic Archiving

Archive entire changes, not individual files:

Good :

# Move complete change folder
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

Bad :

# Don't cherry-pick files
mv spec/changes/add-user-auth/proposal.md spec/archive/
# (leaves orphaned files)

Pattern 3: Archive Preservation

The archive is a historical record. Never modify archived files:

❌ Don't: Edit files in spec/archive/
✓ Do: Treat archive as read-only history

Pattern 4: Git Commit Strategy

Recommended commit workflow:

# Commit 1: Merge deltas
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
git add spec/archive/ spec/changes/
git commit -m "Archive add-user-auth change"

Advanced Topics

For complex deltas : See reference/MERGE_LOGIC.md

Conflict resolution : If multiple changes modified the same requirement, manual merge is required.

Rollback strategy : To rollback an archive, reverse the process (move from archive back to changes, remove merged content from living specs).

Common Patterns

Pattern 1: Simple Addition

Change adds 1 new requirement → Append to spec → Archive

Pattern 2: Behavioral Change

Change modifies 1 requirement → Replace in spec → Archive

Pattern 3: Deprecation

Change removes 1 requirement → Delete from spec with comment → Archive

Pattern 4: Feature with Multiple Requirements

Change adds 5 requirements across 2 specs
→ Append each to respective spec
→ Verify all are merged
→ Archive

Anti-Patterns to Avoid

Don't :

Archive incomplete implementations
Merge deltas before deployment
Modify archived files
Skip validation after merging
Forget to git commit merged specs

Do :

Verify all tasks complete before archiving
Merge deltas carefully and completely
Treat archive as immutable history
Validate merged specs structure
Commit merged specs before archiving move

Troubleshooting

Issue: Merge conflict (requirement exists in living spec)

Solution :

1. If names match but content differs → Use MODIFIED pattern
2. If truly different requirements → Rename one
3. If duplicate by mistake → Use whichever is correct

Issue: Can't find requirement to modify/remove

Solution :

1. Search by partial name: grep -i "login" spec/specs/**/*.md
2. Check if already removed
3. Check if in different capability file

Issue: Living spec has formatting errors after merge

Solution :

1. Fix formatting manually
2. Re-run validation: grep -n "###" spec/specs/**/*.md
3. Ensure consistent heading levels

Reference Materials

MERGE_LOGIC.md - Detailed merge operation rules

Token budget : This SKILL.md is approximately 480 lines, under the 500-line recommended limit.

Weekly Installs

137

Repository

forztf/open-skilled-sdd

GitHub Stars

First Seen

Jan 20, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode128

gemini-cli123

github-copilot122

codex122

cursor117

kimi-cli107

文档查找工具：实时获取库、框架和API最新文档，替代训练数据

926 周安装

规范归档指南：变更提案归档与规范增量合并工作流程详解

🇨🇳中文介绍

规范归档

快速开始

工作流程

步骤 1：验证实现是否完成

步骤 2：审查要合并的规范增量

相关 Skills

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

步骤 4：将 ADDED 需求合并到现行规范中

步骤 5：将 MODIFIED 需求合并到现行规范中

步骤 6：将 REMOVED 需求合并到现行规范中

步骤 7：将变更文件夹移动到归档目录

步骤 8：验证现行规范结构

合并逻辑参考

ADDED 操作

MODIFIED 操作

REMOVED 操作

RENAMED 操作（不常见）

最佳实践

模式 1：移动前验证

模式 2：原子归档

模式 3：归档保存

模式 4：Git 提交策略

高级主题

常见模式

模式 1：简单添加

模式 2：行为变更

模式 3：弃用

模式 4：包含多个需求的功能

要避免的反模式

故障排除

问题：合并冲突（需求已存在于现行规范中）

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

问题：合并后现行规范存在格式错误

参考资料

🇺🇸English

Specification Archiving

Quick Start

Workflow

Step 1: Verify implementation is complete

Step 2: Review spec deltas to merge

Step 3: Create timestamped archive directory

Step 4: Merge ADDED requirements into living specs

Step 5: Merge MODIFIED requirements into living specs

Step 6: Merge REMOVED requirements into living specs

Step 7: Move change folder to archive

Step 8: Validate living spec structure

Merge Logic Reference

ADDED Operation

MODIFIED Operation

REMOVED Operation

RENAMED Operation (uncommon)

Best Practices

Pattern 1: Verify Before Moving

Pattern 2: Atomic Archiving

Pattern 3: Archive Preservation

Pattern 4: Git Commit Strategy

Advanced Topics

Common Patterns

Pattern 1: Simple Addition

Pattern 2: Behavioral Change

Pattern 3: Deprecation

Pattern 4: Feature with Multiple Requirements

Anti-Patterns to Avoid

Troubleshooting

Issue: Merge conflict (requirement exists in living spec)

Issue: Can't find requirement to modify/remove

Issue: Living spec has formatting errors after merge

Reference Materials

最新 Skills