Claude Code：生成可读的提交信息和变更日志

为什么 diff 不够\n\ndiff 显示了发生了什么改动，但不会说明为什么要改。它可以告诉你某个函数被重命名、某个标志被添加，或某条查询被改写；却很少能说明改动背后的意图、对用户的影响或权衡。\n\ndiff 还会把故事拆散到各个文件里。一处小改动可能在别处引起行为的大幅变化，审查者只能猜测：这是修复 bug 还是行为变更？能否安全回溯？是否需要迁移或 feature flag？\n\n这就是为什么需要提交信息和变更日志。它们把原始编辑转成以后能被信赖的决策记录——无论是代码审查的队友、几个月后调试事故的开发者，还是你自己在追踪某个回归时。\n\n单靠 diff 通常无法回答这些问题：\n\n- 解决了什么问题（症状是什么）\n- 谁会受影响（用户、管理员、API 客户端、内部工具）\n- 风险与回滚计划（什么可能坏，如何恢复）\n- 迁移步骤（数据变更、配置更新、版本升级）\n- 如何测试（或还需要测试什么）\n\n像 Claude Code 这样的工具能读取 diff 并起草清晰措辞，但它们仍然需要你的上下文。一个“移除字段”的 diff 可能只是安全的清理，也可能会破坏广泛使用的集成。正确的说明取决于代码之外的信息。\n\n目标是把 diff 转成说明影响、风险和迁移步骤的文字，并为日常提交和发布说明提供可复用的提示模板。\n\n## 什么样的提交信息和发布说明是“好”的\n\n一条好的提交信息应该让人不用重读 diff 就能理解改动。它应说明改了什么、为什么改、以及实际意味着什么。\n\n大多数优秀的提交信息涵盖三点：\n\n- 改了什么（与 diff 对应的一句清晰陈述）\n- 为什么改（问题、bug 或目标）\n- 会有什么影响（面向用户的行为、性能、数据或 API）\n\n实现细节没问题，但只有在有助于审查或调试时才写。“改为参数化查询以防止 SQL 注入”是有意义的。“重构服务”则不够具体。\n\n发布说明则不同。它们针对的是使用产品的人，而不是写代码的人。目的是帮助读者决定：我应该升级吗？会有哪些感觉上的变化？我需要做什么？\n\n好的发布说明按结果分组（修复、改进、破坏性变更）。避免使用内部术语如“重构”、“重命名文件”或“移动处理器”，除非这些直接影响用户。\n\n风险和迁移在两者都很重要，但只在相关时出现。在提交信息中，一段简短的风险说明能提醒审查者关注。在发布说明中，同样的风险应用通俗语言并给出明确操作。\n\n迁移细节在保持实用时最有帮助：\n\n- 谁会受影响\n- 他们必须修改什么\n- 何时生效\n- 如何回滚或恢复（若有安全路径）\n\n当 diff 中有重命名端点、移除标志或模式变更时，Claude Code 可以快速起草这些迁移步骤。但你仍需判断用户会注意到什么、什么可能坏掉。\n\n## Claude Code 能帮忙的地方，以及仍需人工判断的地方\n\nClaude Code 擅长把原始 diff 变成可读文字。给它一个聚焦的变更集和一点上下文，它可以总结改动、指出可能的用户影响，并起草自然的提交信息或发布说明。\n\n它通常在以下方面表现良好：\n\n- 将分散的修改归成一个故事\n- 把代码术语翻译为面向用户的语言\n- 提示风险（配置变更、数据变更、行为变更）\n- 在看到重命名端点、移除标志或模式变更时起草迁移步骤\n\n但它无法知道 diff 之外的信息：产品意图、发布计划（flag、分阶段发布、金丝雀）、或隐藏约束（支持承诺、法律要求、特定客户行为）。如果改动“安全”仅仅依赖代码外的因素，模型是看不到的。\n\n在发布前，人类仍需核实：\n\n- 正确性：摘要是否与代码实际行为一致？\n- 范围：是否有未修改文件之外的副作用（缓存、后台任务、权限）？\n- 安全与隐私：是否更改了认证、日志或数据暴露？\n- 措辞：措辞是否匹配受众（用户 vs 开发者），并避免过度承诺？\n\n举个简单例子：diff 移除数据库列并添加新的 enum 值。Claude Code 可以起草“移除遗留列；新增 status 值”，但只有你能说明这是否破坏性变更、如何回填现有行，以及是否需要两步部署。\n\n## 在提示前准备 diff 与上下文\n\n原始 diff 显示了改动，但很少解释为什么改、用户会注意到什么、或什么可能会坏。花两分钟收集上下文，提交信息和发布说明会更清晰。\n\n收集几个能回答“问题是什么、行为怎样改变、你如何验证它”的信息。把你的提示当作交接给没写过这一改动的队友。\n\n通常最重要的输入有：\n\n- diff（或关键文件/块）\n- PR 描述或意图摘要（即便粗略）\n- 工单备注：验收条件、边缘情况、截图、错误日志\n- 变更前后的预期行为（1–2 句）\n- 风险说明：flag、迁移、配置变更、发布计划\n\n然后决定你想要的输出。小而聚焦的更适合单条提交信息；当 diff 混合了重构、行为变更和测试时，可以用多个提交。发布说明则应关注用户影响、管理员影响和升级后必须做的事。\n\n在粘贴内容前先划定边界。删除敏感信息和你不想放在公共仓库里的内容：API 密钥、私有令牌、客户名、个人数据、内部主机名和不应传播的事故细节。如果不能共享完整上下文，请用安全术语概述。\n\n示例：diff 为 PostgreSQL 表新增必需字段并更新 Go API 处理器。包括迁移文件、处理器变更和一句话说明：“旧客户端如果省略该字段会收到 400。我们会先发布客户端，然后执行迁移。” 这句通常能让消息从误导变成安全说明。\n\n## 能产出更清晰提交信息的提示模式\n\n输出质量取决于你的提问。好的提示会把模型当作把 diff 当作证据，并把信息与影响和风险紧密绑定。\n\n### 实用的提示模板\n\n粘贴 diff（或短摘录），然后补充 diff 看不到的一小段上下文。保持简短但具体：\n\n- 范围：组件或区域（认证、计费、移动端、API）\n- 意图：解决的问题或改变的行为\n- 约束：兼容性、截止时间或“不做模式变更”\n- 受众：谁会读（未来的你、审查者、值班）\n- 输出规则：长度、语气、提交格式（例如 Conventional Commits）\n\n请求结构化答案，便于快速浏览并在粘贴到 Git 之前发现错误。\n\n### 要求多个选项而非“唯一答案”\n\n同一个 diff 可以根据侧重点生成不同的提交信息。要求 2–3 个版本以便选择：\n\n- 保守型：最小化、精确、不做额外推断\n- 面向用户：突出可见行为变化\n- 面向工程：指出重构、性能和后续工作\n\n判断标准是摘要是否与 diff 实际行为一致。如果某个版本提到代码中没有的功能或修复，就删掉它。\n\n### 强制包含明确分段（允许写 “Unknown”）\n\n一种可靠的模式是要求标题，并允许在 diff 无法证明时写“Unknown”。\n\n例如： “返回最终提交信息，包含这些部分：Summary、Motivation、Impact、Risk、Tests。如果看不到 tests，就写 ‘Tests: not shown’ 并建议要运行哪些测试。”\n\n它能让信息保持诚实，并加快审查，尤其在变更需要迁移或谨慎发布时。\n\n## 用于变更日志和发布说明的提示模式\n\n发布说明失败的原因常是它们读起来像 git 日志。如果要从多条提交或一个大 diff 生成有用的发布说明，先说明读者是谁，然后仅在会影响他们的地方保留技术细节。\n\n### 模式：从一批变更中生成发布说明\n\n给出简短的产品上下文（谁在用、应用的哪个区域），然后粘贴 diffs 或摘要。要求结构化输出，区分用户感受与工程变更。\n\ntext\nYou are writing release notes for [product/app]. Audience: [end users/admins/developers].\nInput: the following diffs/commit summaries.\n\nWrite release notes with these sections:\n1) User-visible changes (what’s new or different)\n2) Fixes (symptoms users had, now resolved)\n3) Breaking changes (if none, say “None”)\n4) Migration steps (numbered, short, actionable)\n5) Deprecations (what, when it will be removed, replacement)\n6) Risk and rollout notes (what could go wrong, how to verify)\n\nRules: do not list internal refactors unless they affect behavior. Use plain language.\n\n\n这会把用户影响与内部清理分开，让重命名不会淹没真正的行为变化。\n\n### 模式：明确指出迁移和破坏性变更\n\n即便谨慎的模型也会漏掉迁移，除非你提出明确问题：\n\n- 是否改变了任何 API 返回、配置键、环境变量或数据库模式？\n- 升级后现有用户会发生什么故障，如何察觉？\n- 修复的确切步骤是什么，按顺序写明？\n- QA 应该验证哪些点以确认发布安全？\n\n习惯上总是要求“它为何重要”和“下一步该做什么”，而不是只问“改了什么”。\n\n## 逐步操作：把 diff 变成最终信息\n\n像审查者那样阅读 diff，而不是像写它的人。你的工作是把代码改动变成以后可以信赖的记录：改了什么、为什么改、意味着什么。\n\n1. 先写一句话总结。 用明确的动词并指明影响面。“修复 iOS 上保存草稿时的崩溃”要优于“更新保存逻辑”。\n2. 把变更按稳定结构排序。 一个简单顺序适用于大多数提交：什么、为什么、影响、风险、迁移。如果某项为空就写 “None”，让读者知道不是遗漏。\n3. 补充验证步骤。 包含简短的“如何验证”，确保别人能按步骤复现，而不是看内部实现。\n4. 有风险时写发布及回滚说明。 指出 feature flag、分阶段发布、监控和回滚触发器。如有已知边缘情况，明确说明。\n5. 根据受众润色。 提交信息可包含一些内部上下文；发布说明应为通俗语言。\n\n如果使用 Claude Code，粘贴 diff 加上 2–3 句意图（谁受影响、出了什么问题、你测试了什么），并要求按该结构输出。然后像编辑人类写的文本那样修订它。\n\n快速措辞优化建议：\n\n- 用“用户可以…”或“管理员必须…”代替“我们重构了…”\n- 把模糊的“改进”换成具体结果\n- 若有迁移，明确地说出在何时（部署前或后）以及要做什么\n\n一条稳妥的信息会回答：改了什么？为什么现在改？可能坏什么？如何判断是否生效？如何安全采用？\n\n## 一个现实示例：从 diff 到提交与发布说明\n\n想象一个看似无害但会破坏客户端的小 diff。\n\ndiff\n- type UserResponse struct {\n- FullName string `json:\"fullName\"`\n- }\n+ type UserResponse struct {\n+ Name string `json:\"name\"`\n+ }\n\n+ if req.Name == \"\" {\n+ return errors.New(\"name is required\")\n+ }\n\n\n发生了两件事：响应字段被重命名（fullName -> name），并添加了校验（name 为必填）。在询问影响、风险和下一步时效果最好。\n\n下面是一条包含 diff 无法提供关键上下文的示例提交信息草稿：\n\ntext\nRename user response field to `name` and require `name` on create\n\nWhy:\n- Align API with updated domain naming\n\nImpact:\n- Breaking change: clients reading `fullName` must switch to `name`\n- Requests without `name` now fail validation\n\nTests:\n- Updated API tests for response payload\n- Added validation test for missing name\n\n\n以及为用户撰写的发布说明条目：\n\ntext\nBreaking: User API field rename and stricter validation\n\n- Response field `fullName` is now `name`\n- Create/update requests now require `name`\n\nMigration:\n- Update JSON parsing to read `name`\n- If you send `fullName`, map it to `name` before calling the API\n\n\n把措辞收紧，去掉推测。比如“Align API with updated domain naming” 很模糊；如果你不知道原因，就写你所知道的，例如“标准化端点命名”。同样避免宣称你没跑过的测试，把“Updated API tests”换成测试套件名，或诚实写成“手动检查：通过 API 创建用户并验证响应负载”。\n\n## 常见错误与陷阱\n\n让 AI 写的提交失去信任的最快方式是让消息承诺超出 diff 本身。Claude Code 能把原始改动写得清楚，但也可能把内部重构推断为面向用户的功能，除非你让输出保持有据可查。\n\n常见错误包括夸大影响：重命名、添加帮助函数或在文件间移动逻辑很容易被写成“新特性”。当发布说明声称“提升性能”而没有测量或用户症状时，人们会注意到。\n\n另一常见问题是忽略破坏性变更和迁移。diff 常把它们藏在小处：默认配置变了、环境变量被重命名、数据库列变为 NOT NULL，或返回字段被移除。如果提交信息和变更日志没有说明升级后需要做什么，干净的发布就会变成支持工单。\n\n模糊措辞也很危险。“小幅改进”和“若干修复”会隐藏风险而非传达它。\n\n粘贴 diff 到提示时要注意的陷阱：\n\n- 把内部重构写成面向用户的声明\n- 忽略破坏性变更和迁移步骤\n- 用通用语言掩盖风险\n- 发明不在 diff 或上下文里的原因\n\n修正方法是强制“证据”思维。如果 diff 改了 API 字段名，发布说明必须写清客户端应如何重命名，以及旧客户端是否会中断。\n\n在接受模型输出前，再做一次请求：让它\n\n- 区分用户影响和内部改动\n- 把破坏性变更列出并给出具体迁移操作\n- 用通俗语言指出风险（以及不确定性）\n- 符合你仓库的提交风格规则\n\n## 合并或发布前的快速核对清单\n\n合并前，把提交信息当作外行人来读。如果它不能用通俗的话解释改动，就不会在紧急修复时帮你。如果用了 Claude Code，再快速核对是否与实际改动一致。\n\n### 提交信息快速检查\n\n- 改了什么、在哪里：指明功能/区域，不要只写“重构”。\n- 为什么改：一句话概括原因。\n- 影响：谁或什么会受影响。\n- 证据：说明你运行了哪些测试（或写明“未测试”及原因）。\n- 范围：信息是否与 diff 的大小和行为变更相符？\n\n若消息包含不在 diff 或工单里的细节，请删掉。一个简洁的“为什么”胜过冗长的故事。\n\n### 发布说明快速检查\n\n发布说明是给没看 PR 的读者的。\n\n- 面向用户：描述结果，不谈实现细节。\n- 风险明确：可能出什么问题，如何发现。\n- 包含迁移：配置变更、新的环境变量、数据回填或一次性操作。\n- 回滚说明：如果回退会发生什么，以及是否需要清理。\n\n### 禁止项清单\n\n发布前删除或重写：\n\n- 秘密或私有数据（令牌、密钥、客户信息）\n- 无测量支持的推测（“应该提升性能”）\n- 带有指责意味的语言（“ops 弄错了”、“前端搞砸了”）\n\n如果无法在不猜测的情况下解释改动，就暂停并补充上下文。\n\n## 下一步：在工作流程中养成习惯\n\n一致性胜过完美。选一个轻量格式，全队都在每次变更中遵守，即便在忙碌时也不例外。大家都按同一结构写，审查会更快，发布说明也不会像破案。\n\n一个经得起考验的轻量格式：\n\n- 改动（用户影响）：一句话，通俗说明\n- 为什么：原因或要修复的问题\n- 风险：可能坏什么，以及如何降低风险\n- 迁移：所需步骤（如有）\n\n用 Claude Code 起草，然后人工快速校对事实与上下文。它在你给出 diff 加上 2–3 句意图（目标受众、改进目标、刻意不改的内容）时最有用。\n\n要在不增加会议的情况下扩展这个流程，把它内置到你常用的位置：在 commit 或 PR 模板中加入这些字段、勾选迁移与风险复选框，以及把审查重点从措辞转到缺失的影响上。\n\n如果你在 Koder.ai (koder.ai) 中构建，使用同样的结构也很自然：先写意图（影响、风险、迁移），然后按计划实现，这样“为什么”就不会随着代码变化而丢失。