DESKTOP-368IV5S\Kris
55b053346d
- 新增 11 个技能文档，指导 AI 完成特定开发任务 - 新增参考代码文件，用于代码分析和重构 - 优化 DataiIntegrationBatchServiceImpl.java，提取常量到 SalesforceConstants.java - 移动 SessionManager.java 到 auth 模块 - 更新 docs/index.md，添加技能文档索引 主要变更： - 新增技能文档：Bootstrap、SSOT Hub、信息架构、需求定义、架构决策、提示词资产化、上下文锚定、执行记录、变更归档、闭环复盘、测试提交 - 提取常量：批次处理、状态值、字段名、日志消息等 - 优化代码：改进代码结构和可读性 Related: - Prompts: docs/prompts/03-创建工作流提示词.md - Prompts: docs/prompts/07生成技能书提示词.md
427 lines
9.7 KiB
Markdown
427 lines
9.7 KiB
Markdown
---
|
||
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/)
|