在人工智能（AI）时代之前，我会为主要变更写较长的提交说明，花 5 到 10 分钟起草并重读。我想把有用信息集中起来，让读者不用多处查找；要解释改了什么，更要说明为什么改。有时我会用第一人称写，像在给别人留言。写的过程也促使我重读代码、总结改动、重新评估决策，有时因此改成更好的方案。如今到了智能体编程（agentic coding）时代，代码和提交说明都由 AI 写。

在 AI 时代之前，我习惯为较大的改动写很长的提交说明（或提交正文）。每次起草加重读大概要花五到十分钟，确认没漏掉重要信息。这么做有几个原因。

我想把所有有用信息都写进去，免得读者去各处翻找。也想说明改了什么，更重要的是为什么。改了什么通常不言自明，但做个总结能为解释原因提供起点。

有时我用第一人称写，像在给某人留言：“我这么做是因为……”“在做这个直到我们……”。接着解释原因，好让他人尤其是未来的自己，明白当初为何改动。

写的过程本身助我反思代码：重读并总结改动，往往会重新评估决定，有时就引出更好方案。

如今到了智能体编程时代，代码和提交说明都由 AI 写。我觉得最难的是读懂 AI 写的提交说明。智能体能为改动写提交信息，但可能缺少散落在各类沟通、项目管理工具里的完整背景，有些还是离线的。AI 不知道“为什么”时，会自己编理由，这很危险。日后回看会发现说不通，因为真实原因完全不同。

一个明显办法是通过对话或工具把背景全给智能体，让它清楚解释原因。但这没解决另一问题：背景对了，智能体写的提交信息很可信，但只有我能核实代码是否如描述所写。所以我的做法是自己写提交信息和说明。

自己写说明帮我反思 AI 的改动，也检查是否一切符合预期。如果我说不清“为什么”，就等于在发布自己没搞懂的东西，日后出问题时难以解释或修复。老话说，讲不明白就是没懂。提交说明在此再次成为思考工具。

像“在做这个直到我们……”这类属于带退出条件的临时决定。我们设的退出条件往往因显而易见而没写下来，AI 无法推断。但写提交信息逼我把这句话补完，帮未来读者决定是否保留改动。

智能体能写代码和说明，但写“为什么”才能检验你到底懂不懂要发布的东西。

社区普遍认为提交信息应解释“为什么”而非仅“是什么”，多数人质疑AI代写常脱离真实意图且冗长；少数观点认为AI对厌写者有益，或怀疑厂商故意制造不友好文本谋利。

认为提交信息必须解释“为什么”而非仅“是什么”

• 任何迭代过程都需要清晰记录步骤动机以指导维护，写码快过解释会累积技术债，此问题早于生成式AI时代（较多人）
• 写作即思考，不限于提交信息，担心人们遗忘这点（较多人）
• 有开发者长期用“为什么/怎么做”模板甚至写极长信息未出问题，也有人提倡先写提交信息再写代码以理清思路（少数人） > 任何迭代过程的记录都需清晰回答“为什么”，写码快于消化解释必将欠下失控的技术债（@sublinear）

质疑AI生成的提交信息常只叙述变更且易虚构理由

• Claude等默认只复述代码变动的“是什么”，真正有价值的是“为什么”；当AI不知真实原因会编造看似合理的解释，即便文字通顺也脱离现实，后续维护危险（高赞）
• 通过强制AI先搜集变动、日志、追溯等证据并标注声明来源，可提升消息质量并帮助发现误解，但仍需人工把关长度与真实性（较多人）
• AI还会把易过时实现细节跨服务乱拷贝，使注释比无用更误导（少数人） > AI不知真实原因时会编出自己的推理，更危险的是它写的理由看似合理却脱离现实（@evnp）

认为AI代写提交信息对厌写者有益或可用于自我理清

• 许多人视写提交信息为负担，对他们而言AI生成文本总比空白好（少数人）
• 另有开发者用向AI提问来理清自身思路，类似写邮件迫使大脑进入状态（少数人）
• 有人用不同模型家族互审提交并写描述，不匹配则转人工（少数人）

怀疑AI公司故意制造冗长不友好文本以谋利

• 此前人类因写不好消息而倾向压缩提交，如今AI产出海量难速读的消息，怀疑是刻意让过程不人性以利替换人类，并借反复处理这些文本收费，如同排碳机器排碳（少数人） > 人工智能公司在客户流程中注入海量文本，这些文本又变成需付费反复处理的令牌，犹如排放二氧化碳的洗涤器（@dkarl）

偏好用文档或git-notes承载上下文

• 纠结解释放提交信息还是架构决策文档，倾向文档因其普遍可见，提交信息优势仅在不可篡改和直接关联提交（少数人）
• 推荐使用git-notes附加上下文，不污染历史且便于引导AI（少数人）

有价值的补充

• 实测极长提交信息不会破坏git系统，无需担心长度上限（@kccqzy）
• 写代码前先起草提交信息能帮助开发者理清变更内容与原因，可作为工作流（@arialdomartini）
• 训练AI写提交时令其先写简要报告收集证据、分类主张来源，可大幅减少虚构并助捕捉逻辑漏洞（@cerved）