maintain-changelog

name	maintain-changelog
description	Maintain project CHANGELOG.md after completed work. Use when Codex has completed an implementation, bug fix, refactor, documentation update, deployment/configuration change, or other project change and should update the changelog before the final user response. Also use when the user asks to update, create, consolidate, migrate, or normalize a changelog, release notes, history file, or 更新日志.

Maintain Changelog

在项目变更已经完成并经过合理验证后，维护项目根目录的 CHANGELOG.md。更新日志只记录用户或维护者能理解的行为变化，不记录文件流水账。

工作流程

1. 确认是否应该更新。

   • 如果用户明确说本次不要更新 changelog，跳过更新，并在最终回复中说明。
   • 只在实现、修复、重构、文档、部署、配置、API、数据结构、权限、依赖等项目变更完成后更新。
   • 纯问答、方案讨论、临时排查、格式化、只改注释、无行为影响的测试补充，默认不写。

2. 先收集证据。

   • 优先查看 git status、git diff --stat 和相关 git diff。
   • 如果当前不是 git 仓库，只有在能明确识别本轮创建或修改的文件时，才基于文件级证据更新。
   • 如果工作区存在无法归属的混杂改动，不要猜测，不要记录无关改动；暂停并询问用户。
   • 对话上下文只能辅助理解，不能替代真实 diff 或文件证据。

3. 确认变更已经合理验证。

   • 在实现和验证之后再写更新日志。
   • 验证可以是自动测试、构建、lint、静态检查、代码检查或手动确认。
   • 如果验证失败且变更是否成立依赖该验证，不要把它写成已交付变化。
   • 测试命令和结果写在最终回复里，默认不要写进 changelog。

4. 确定日志文件。

   • 目标统一为项目根目录 CHANGELOG.md。
   • 如果不存在 CHANGELOG.md，创建它。
   • 如果发现明显替代文件，如 RELEASE_NOTES.md、HISTORY.md、docs/更新日志.md，将其中有价值的历史记录整理迁移到根目录 CHANGELOG.md。
   • 迁移后不要删除旧文件，只在旧文件顶部加入迁移提示：

> 更新日志已统一迁移到根目录 CHANGELOG.md，本文件不再维护。

5. 保留现有结构。

   • 已有 CHANGELOG.md 时，严格保留现有历史版本、标题语言、条目措辞和格式。
   • 不重排、不翻译、不改写已有历史，除非用户明确要求整理。
   • 只在 未发布 / Unreleased 区块追加或补充本次条目。
   • 如果没有 未发布 / Unreleased 区块，在文件标题下、历史版本上方创建一个。
   • 不要把新条目写进最近的历史版本，除非用户明确要求发版整理。

6. 编写中文条目。

   • 条目使用中文，描述用户或维护者能理解的行为变化。
   • 一条 changelog 对应一个可说明的功能、修复、行为变化或移除项。
   • 不写“修改了某文件”“更新了某函数”“运行了某命令”这类流水账。
   • 轻量去重：同一变化不要重复写；跨多个提交但属于同一功能时合并成一条。
   • 多个独立用户可见或维护者相关变化可以拆成多条。

新建文件模板

如果项目没有任何可迁移日志，创建：

# 更新日志

## 未发布

### 新增

### 变更

### 修复

### 移除

按需添加 ### 安全 或 ### 文档，不要为了空分类额外增加标题。已有英文结构时，尊重原结构，新增条目仍然用中文。

分类规则

• 新增：新功能、新能力、新文档交付。
• 变更：用户行为调整、配置变化、部署变化、依赖升级、数据库迁移、维护者需要知道的重构影响。
• 修复：bug 修复、兼容性修复、回归修复。
• 移除：删除功能、移除旧接口、废弃文件真正下线。
• 安全：权限收紧、敏感信息处理、安全漏洞修复。
• 文档：重要使用说明、部署文档、接口文档、维护文档。

重构默认不写，除非它影响维护者理解、部署、扩展、排查，或改变模块边界和公共契约。不要写“做了重构”，要写重构带来的可理解维护影响。

迁移旧日志

迁移替代日志时保持保真：

• 有版本或日期的内容，按原版本或日期迁移。
• 没有日期但有明确条目的内容，可以放入 ## 未归档历史。
• 明显重复的条目可以合并。
• 不要编造版本号、日期或发布结论。
• 无法判断含义的内容保留原文或标为未整理。
• 旧历史不要混入 未发布。

示例

推荐：

### 新增
- 支持在面试开始前配置岗位、难度和重点考察方向。

### 修复
- 优化验证码发送失败时的错误提示，便于定位 SMTP 认证配置问题。

避免：

- 修改 InterviewServiceImpl.java。
- 更新三个 Vue 文件。
- 运行 npm build。

最后检查

更新后执行轻量自检：

• 标题层级合理：# 更新日志、## 未发布、### 分类。
• 条目使用 - 列表。
• 不留下重复的 ## 未发布。
• 不把同一条写到多个分类。
• 快速读一遍 CHANGELOG.md，确认插入位置和中文表达自然。
• 查看 git diff -- CHANGELOG.md，确认只改了预期位置。
• 如果迁移了旧日志，也查看旧文件 diff，确认只添加迁移提示或做了明确需要的最小整理。

不要自动 commit、打 tag、发布 release 或生成正式 release notes；这些只在用户明确要求时处理。

最终回复

最终回复必须说明更新日志处理结果：

• 已更新时，说明写入了 CHANGELOG.md 的哪个区块。
• 未更新时，说明原因。
• 做了迁移时，说明旧日志已汇总到 CHANGELOG.md，旧文件已加迁移提示。
• 有验证限制时，说明哪些验证未运行以及原因。