changelog-craft

维护项目根的 CHANGELOG.md：提交时逐笔补 Unreleased，发版时归段成版本。格式规范：Keep a Changelog 1.1.0（中文版），细则与模板见 references/format.md。

设计原则

模式判定（入口）

模式 A — 逐笔（核心）

判定基于 staged diff（还没 stage 就先看工作区改动）：

流程：

1. 无条目 → 报告"本次无可写条目"，结束（默认不吵）
2. 有条目 → 按模式 B Step 4 的撰写规则起草 1-3 条，追加进 Unreleased 段对应大类
3. 项目还没有 CHANGELOG.md → 问一次"要初始化吗"：初始化 = references/format.md 的骨架 + SemVer 声明 + 本次条目；不主动全量回溯历史（用户要才转模式 B）
4. CHANGELOG.md 加入本次 commit 的 staged 文件一起提交（不另起提交）；报告写了哪些条目

触发机制是提示层约定：建议用户在常维护项目的 AGENTS.md / CLAUDE.md 里加一行"commit 前按 changelog-craft 检查"。git hook 硬自动化不在本技能范围。

模式 B — 成段（发版时）

Step 1 — 摸底

git tag 列表 + 最新 tag；manifest（package.json / pyproject.toml 等）的 version；已有 CHANGELOG.md 读出覆盖到哪个版本、什么语言、什么分组风格；抽样最近 20 条提交判断语言习惯（中文仓库 entries 用中文写）。

Step 2 — 范围判定

用户明确要求修正 / 补漏历史段落时可以改写（规范允许），先备份。

Step 3 — 素材归类

• Unreleased 现有条目为主，git log 兜底补漏
• 按 references/format.md 的判定树分组；Merge / chore / typo 噪音丢弃或归 Internal Changes
• 提交信息看不出用户价值的：看 diff / 文件路径推断；仍判断不了的合并为一句话，实在不行兜底问一次 highlights（一次问完，不逐条追问）

Step 4 — 撰写（两模式共用）

• 每条 entry 写"使用者可感知的变化"，不复述 commit message——规范反模式第一条就是 commit log dump（fix bug → 修了什么、影响谁）
• 面向使用者写，不面向协作者写：纯内部重构归 Internal Changes 一笔带过
• 条目带 short-hash 链接（文件底部引用区）
• 反 AI 味：破折号节制、不堆形容词、每条是完整的句子

Step 5 — 自检写入

• 版本号与 tag / manifest 一致（只读，不猜 semver、不建议升版本）
• Merge / release 前缀已清洗，日期 YYYY-MM-DD，新版本在上
• 六大类名称同文件内统一（类名英文，不中英混用）
• 无占位符，链接有效
• 已有文件先备份（.bak 已存在改用 <file>.<YYYYMMDD-HHMMSS>.bak，绝不覆盖旧备份）

语言策略

单语言，跟随主 README 的语言（读 README.md 判断；读不出问一次）。不做多语言 CHANGELOG。

Failure handling

与相邻 skill 的边界

Windows (win32) platform notes

git tag / log / remote 只读命令 + Read / Write / Grep 工具，跨平台通用，无需适配；.bak 备份用 Write 复制内容而非 shell copy。