datai/docs/archive/skill/0009-changelog-archiving.md

---
name: 0009-changelog-archiving
description: 变更记录与归档，更新 CHANGELOG.md 和 docs/changelog/
---

# 技能：变更记录与归档 (Changelog & Archiving)

## 元数据 (Metadata)

- **name**: changelog-archiving
- **description**: 变更记录与归档，更新 CHANGELOG.md 和 docs/changelog/
- **version**: 1.0.0
- **author**: SSOT Architect
- **lastUpdated**: 2026-01-15

## 触发与定位 (Triggers & Scope)

### 触发条件 (Triggers)
当以下情况发生时，AI 应当"觉醒"本技能：

1. **代码变更完成**: 完成代码编写后，需要记录变更
2. **功能发布**: 功能开发完成，准备发布
3. **Bug 修复**: 修复 Bug 后，需要记录变更
4. **代码重构**: 重构代码后，需要记录变更
5. **工作流阶段 6**: 用户进入工作流的"变更记录与归档"阶段

### 定位范围 (Scope)
- **适用模块**: 所有 Datai 项目模块
- **影响文件**: `CHANGELOG.md`, `docs/changelog/`, `docs/index.md`
- **相关技能**: skill-execution-logging, skill-retrospective

## 核心指令集 (Instructions)

### 架构约束 (Architecture Constraints)

1. **CHANGELOG.md 规范**:
   - 基于 [Keep a Changelog](https://keepachangelog.com/) 格式
   - 按版本组织变更记录
   - 包含变更类型：Added, Changed, Deprecated, Removed, Fixed, Security

2. **变更记录必须包含**:
   - 版本号（遵循语义化版本规范）
   - 变更日期
   - 变更类型
   - 变更描述
   - 相关需求或 Bug ID
   - 相关 ADR ID

3. **必须同步更新 docs/index.md**:
   - 在 `docs/index.md` 中标注该需求已完成
   - 更新需求状态为 Completed
   - 更新最后更新日期

### 业务逻辑 SOP (Business Logic SOP)

#### 步骤 1: 分析代码变更
```markdown
## 代码变更分析

### 变更类型
- [ ] Added - 新增功能
- [ ] Changed - 功能变更
- [ ] Deprecated - 废弃功能
- [ ] Removed - 移除功能
- [ ] Fixed - 修复 Bug
- [ ] Security - 安全修复

### 变更范围
- [ ] 前端变更
- [ ] 后端变更
- [ ] 数据库变更
- [ ] API 变更
- [ ] 文档变更

### 影响评估
- [ ] 向后兼容性
- [ ] 数据迁移
- [ ] 配置变更
- [ ] 依赖变更
```

#### 步骤 2: 确定版本号
```markdown
## 版本号确定

### 语义化版本规范
- 主版本号（MAJOR）：不兼容的 API 变更
- 次版本号（MINOR）：向下兼容的功能性新增
- 修订号（PATCH）：向下兼容的问题修正

### 版本号决策
**当前版本**: [当前版本号]
**新版本**: [新版本号]

**变更理由**:
[变更理由说明]
```

#### 步骤 3: 更新 CHANGELOG.md
```markdown
# 变更日志

所有项目重要变更都将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/)

## [Unreleased]

### Added
- 新增功能列表

### Changed
- 变更列表

### Deprecated
- 废弃的功能

### Removed
- 移除的功能

### Fixed
- 修复的问题

## [1.1.0] - 2026-01-15

### Added
- 新增用户批量导入功能 (REQ-001)
- 新增 CSV 文件解析功能 (REQ-001)
- 新增导入错误日志记录 (REQ-001)

### Changed
- 优化用户查询性能 (ADR-002)
- 改进错误处理机制 (ADR-002)

### Fixed
- 修复导入文件编码问题 (Bug-001)
- 修复用户数据验证问题 (Bug-002)

### Security
- 增强文件上传安全性 (Security-001)

### Related
- Requirements: [REQ-001](docs/requirements/REQ-001.md)
- ADR: [ADR-001](docs/decisions/adr/ADR-001.md)
- Session: [20260115-TaskName](docs/sessions/20260115-TaskName.md)

## [1.0.0] - 2026-01-10

### Added
- 初始版本发布
- 新增用户管理功能
- 新增权限管理功能
```

#### 步骤 4: 创建详细变更记录
```markdown
---
name: CHANGELOG-20260115
description: 详细变更记录
---

# 变更记录: 2026-01-15

## 元数据 (Metadata)

- **Date**: 2026-01-15
- **Version**: 1.1.0
- **Type**: [Feature Release/Bug Fix Release/Security Release]
- **Related Requirements**: [REQ-001](../requirements/REQ-001.md)
- **Related ADRs**: [ADR-001](../decisions/adr/ADR-001.md)
- **Session**: [20260115-TaskName](../sessions/20260115-TaskName.md)

## 变更摘要

### 新增功能
- [功能1]: [功能描述]
- [功能2]: [功能描述]

### 功能变更
- [变更1]: [变更描述]
- [变更2]: [变更描述]

### Bug 修复
- [Bug1]: [Bug 描述]
- [Bug2]: [Bug 描述]

## 详细变更

### 新增功能

#### 功能 1: [功能名称]
**需求**: [REQ-XXX](../requirements/REQ-XXX.md)
**ADR**: [ADR-XXX](../decisions/adr/ADR-XXX.md)

**描述**:
[功能详细描述]

**实现**:
- [实现细节1]
- [实现细节2]

**测试**:
- [测试用例1]
- [测试用例2]

**影响**:
- [影响范围]
- [向后兼容性]

### 功能变更

#### 变更 1: [变更名称]
**ADR**: [ADR-XXX](../decisions/adr/ADR-XXX.md)

**描述**:
[变更详细描述]

**变更前**:
[变更前的状态]

**变更后**:
[变更后的状态]

**影响**:
- [影响范围]
- [向后兼容性]
- [数据迁移]

### Bug 修复

#### Bug 1: [Bug 名称]
**Bug ID**: [Bug-XXX]
**Session**: [20260115-TaskName](../sessions/20260115-TaskName.md)

**描述**:
[Bug 详细描述]

**复现步骤**:
1. [步骤1]
2. [步骤2]
3. [步骤3]

**修复方案**:
[修复方案描述]

**验证**:
[验证方法]

## 代码变更

### 新增文件
- [文件1](../../path/to/file1.java) - [说明]
- [文件2](../../path/to/file2.java) - [说明]

### 修改文件
| 文件 | 变更类型 | 变更说明 |
|------|----------|----------|
| [文件1](../../path/to/file1.java) | [修改/重构] | [变更说明] |
| [文件2](../../path/to/file2.java) | [修改/重构] | [变更说明] |

### 删除文件
- [文件1](../../path/to/file1.java) - [说明]

## 数据库变更

### 新增表
- [表名] - [说明]

### 修改表
| 表名 | 变更类型 | 变更说明 |
|------|----------|----------|
| [表名] | [新增字段/修改字段/删除字段] | [变更说明] |

### 数据迁移
- [迁移脚本1] - [说明]
- [迁移脚本2] - [说明]

## 配置变更

### 新增配置
- [配置项] - [说明]

### 修改配置
| 配置项 | 旧值 | 新值 | 说明 |
|--------|------|------|------|
| [配置项] | [旧值] | [新值] | [说明] |

### 废弃配置
- [配置项] - [说明]

## 依赖变更

### 新增依赖
- [依赖1] - [说明]
- [依赖2] - [说明]

### 升级依赖
| 依赖 | 旧版本 | 新版本 | 说明 |
|------|--------|--------|------|
| [依赖] | [旧版本] | [新版本] | [说明] |

### 移除依赖
- [依赖1] - [说明]

## 相关文档 (Related Documents)

- [需求文档](../requirements/REQ-XXX.md)
- [ADR 文档](../decisions/adr/ADR-XXX.md)
- [会话记录](../sessions/20260115-TaskName.md)
- [复盘文档](../retros/20260115-Review.md)
```

#### 步骤 5: 更新 docs/index.md
```markdown
### 📝 需求文档 (Requirements)
| 文档 | 状态 | 描述 | 更新日期 |
|------|------|------|----------|
| [REQ-001](requirements/REQ-001.md) | ✅ Completed | [需求描述] | 2026-01-15 |
```

### 工具调用 (Tool Usage)

1. **文件读取工具**:
   - 使用 `Read` 工具读取 `CHANGELOG.md`
   - 使用 `Read` 工具读取 `docs/index.md`

2. **文件更新工具**:
   - 使用 `SearchReplace` 工具更新 `CHANGELOG.md`
   - 使用 `SearchReplace` 工具更新 `docs/index.md`

3. **文件创建工具**:
   - 使用 `Write` 工具创建详细变更记录

## 错误陷阱与验证 (Anti-Patterns & Checklist)

### 常见错误 (Anti-Patterns)

1. **错误**: CHANGELOG.md 格式不规范
   - **后果**: 难以追踪变更历史
   - **修正**: 使用 Keep a Changelog 格式

2. **错误**: 变更描述过于简单
   - **后果**: 无法理解变更的具体内容
   - **修正**: 必须详细描述变更内容、影响和相关文档

3. **错误**: 忘记更新 docs/index.md
   - **后果**: 需求状态未更新，违反 SSOT 原则
   - **修正**: 必须同步更新需求状态

4. **错误**: 版本号不符合语义化版本规范
   - **后果**: 版本管理混乱
   - **修正**: 必须遵循语义化版本规范

5. **错误**: 缺少相关文档链接
   - **后果**: 无法追溯变更的上下文
   - **修正**: 必须包含需求、ADR、Session 等相关文档链接

### 验收清单 (Acceptance Checklist)

- [ ] CHANGELOG.md 已更新
- [ ] 变更类型已明确
- [ ] 版本号已确定
- [ ] 变更描述已详细记录
- [ ] 相关文档已链接
- [ ] 详细变更记录已创建
- [ ] 代码变更已记录
- [ ] 数据库变更已记录
- [ ] 配置变更已记录
- [ ] 依赖变更已记录
- [ ] docs/index.md 已更新
- [ ] 需求状态已更新

### Correct vs Incorrect 对比

#### Correct 示例
```markdown
## [1.1.0] - 2026-01-15

### Added
- 新增用户批量导入功能 (REQ-001)
  - 支持 CSV 格式导入
  - 单次最多导入 1000 条记录
  - 提供详细的错误信息
- 新增导入错误日志记录 (REQ-001)
  - 记录导入失败的详细原因
  - 支持错误日志导出

### Changed
- 优化用户查询性能 (ADR-002)
  - 使用索引优化查询
  - 减少数据库查询次数

### Fixed
- 修复导入文件编码问题 (Bug-001)
  - 支持多种文件编码格式
  - 自动检测文件编码

### Related
- Requirements: [REQ-001](docs/requirements/REQ-001.md)
- ADR: [ADR-001](docs/decisions/adr/ADR-001.md)
- Session: [20260115-TaskName](docs/sessions/20260115-TaskName.md)
```

#### Incorrect 示例
```markdown
## [1.1.0] - 2026-01-15

### Added
- 新增批量导入功能
- 新增日志记录

### Changed
- 优化查询性能

### Fixed
- 修复文件编码问题
```

**问题**: 变更描述过于简单，缺少相关文档链接，无法追溯变更的上下文。

## 相关文档 (Related Documents)

- [工作流提示词](../prompts/03-创建工作流提示词.md#阶段-6-变更记录与归档-changelog)
- [执行与记录技能](./0008-execution-logging.md)
- [闭环复盘技能](./0010-retrospective.md)
- [Keep a Changelog](https://keepachangelog.com/)