kris/datai

2026-01-28 18:23:25 +08:00

9.7 KiB

Raw Blame History

name	description
0009-changelog-archiving	变更记录与归档，更新 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 应当"觉醒"本技能：

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

定位范围 (Scope)

适用模块: 所有 Datai 项目模块
影响文件: CHANGELOG.md, docs/changelog/, docs/index.md
相关技能: skill-execution-logging, skill-retrospective

核心指令集 (Instructions)

架构约束 (Architecture Constraints)

CHANGELOG.md 规范:
- 基于 Keep a Changelog 格式
- 按版本组织变更记录
- 包含变更类型：Added, Changed, Deprecated, Removed, Fixed, Security
变更记录必须包含:
- 版本号（遵循语义化版本规范）
- 变更日期
- 变更类型
- 变更描述
- 相关需求或 Bug ID
- 相关 ADR ID
必须同步更新 docs/index.md:
- 在 docs/index.md 中标注该需求已完成
- 更新需求状态为 Completed
- 更新最后更新日期

业务逻辑 SOP (Business Logic SOP)

步骤 1: 分析代码变更

## 代码变更分析

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

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

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

步骤 2: 确定版本号

## 版本号确定

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

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

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

步骤 3: 更新 CHANGELOG.md

# 变更日志

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

格式基于 [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: 创建详细变更记录

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

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

工具调用 (Tool Usage)

文件读取工具:
- 使用 Read 工具读取 CHANGELOG.md
- 使用 Read 工具读取 docs/index.md
文件更新工具:
- 使用 SearchReplace 工具更新 CHANGELOG.md
- 使用 SearchReplace 工具更新 docs/index.md
文件创建工具:
- 使用 Write 工具创建详细变更记录

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

常见错误 (Anti-Patterns)

错误: CHANGELOG.md 格式不规范
- 后果: 难以追踪变更历史
- 修正: 使用 Keep a Changelog 格式
错误: 变更描述过于简单
- 后果: 无法理解变更的具体内容
- 修正: 必须详细描述变更内容、影响和相关文档
错误: 忘记更新 docs/index.md
- 后果: 需求状态未更新，违反 SSOT 原则
- 修正: 必须同步更新需求状态
错误: 版本号不符合语义化版本规范
- 后果: 版本管理混乱
- 修正: 必须遵循语义化版本规范
错误: 缺少相关文档链接
- 后果: 无法追溯变更的上下文
- 修正: 必须包含需求、ADR、Session 等相关文档链接

验收清单 (Acceptance Checklist)

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

Correct vs Incorrect 对比

Correct 示例

## [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 示例

## [1.1.0] - 2026-01-15

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

### Changed
- 优化查询性能

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

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

9.7 KiB Raw Blame History Unescape Escape

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

元数据 (Metadata)

触发与定位 (Triggers & Scope)

触发条件 (Triggers)

定位范围 (Scope)

核心指令集 (Instructions)

架构约束 (Architecture Constraints)

业务逻辑 SOP (Business Logic SOP)

步骤 1: 分析代码变更

步骤 2: 确定版本号

步骤 3: 更新 CHANGELOG.md

步骤 4: 创建详细变更记录

步骤 5: 更新 docs/index.md

工具调用 (Tool Usage)

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

常见错误 (Anti-Patterns)

验收清单 (Acceptance Checklist)

Correct vs Incorrect 对比

Correct 示例

Incorrect 示例

相关文档 (Related Documents)

9.7 KiB

Raw Blame History