Commit 与 PR 日常协作 SOP
系列入口：如何使用 Agent。M12 第 3 篇。
一、为什么这件小事值得做规范
提交说明和 PR 描述看似微不足道，却是团队知识的时间胶囊：几个月后排查问题、做代码考古、写发布说明时，人们依赖的正是这些文字。糟糕的说明（"fix"、"update"）让历史几乎不可读，而好的说明能回答"为什么改、改了什么、影响哪些地方"。
这件事高频、重复、且有明确格式，非常适合交给 Agent 起草——它能从 diff 准确归纳变更，让人从"写说明"的琐碎中解放。但它也可能夸大改动或总结错误，因此正确用法是"让它起草、你来核对"，而非盲贴。
二、让 commit message 准确反映 diff
让 Agent 基于本次实际 diff 生成提交说明，而非凭你的一句话臆测。采用团队约定的格式（如 Conventional Commits：feat:、fix:、refactor: 等），一行简洁标题 + 必要时的正文说明动机和边界影响。
关键是核对：它是否准确区分了类型、有没有遗漏破坏性变更、是否提到了其实没改的东西。Agent 有时会"脑补"出一个听起来合理但与 diff 不符的描述，这类虚构必须在提交前纠正。对一次提交混入多件事的情况，让它如实概括，或更好的做法是拆成多个聚焦的提交。
三、PR 描述：为评审者组织上下文
PR 描述比单条 commit 更需要"面向读者"。让 Agent 起草一套清晰结构：动机（为什么要改、关联什么需求/issue）、方案（怎么实现的、关键取舍）、影响面（改了哪些接口、是否涉及迁移或配置）、测试（怎么验证的、有无自动化测试）、以及需要评审者特别关注的点。
好的 PR 描述本质是在帮评审者快速建立上下文，与上下文工程的思想一致（见上下文工程入门）。让它把 diff 归纳成评审者视角的"这次改动该怎么看"，而不是流水账。
四、防止夸大与虚构
AI 写说明时的典型偏差是过度包装：把一个小修说成"重构并优化了整个模块"，或加上 diff 里并不存在的"提升了性能/增强了安全性"。这会误导评审者和未来的读者。
应对：要求它只陈述 diff 中能被证实的内容、区分"事实"与"推测"、不使用无依据的褒义词；性能、安全等结论必须有对应证据。把它的输出当草稿，由最了解改动的你做事实核对。准确克制，比华丽夸张更有长期价值。
五、把 SOP 固化进工作流
既然是每天都做的事，就值得固化成斜杠命令或 hooks：一键让 Agent 总结暂存区改动生成提交说明，或在创建 PR 时自动填充描述模板（实现方式见自定义斜杠命令与 Hooks 指南）。
把团队的提交/PR 规范写进规则文件，让 Agent 默认遵守（见共享约定与模板）。当"生成规范说明"变成零摩擦的默认动作，协作历史的质量会整体抬升，而不依赖某个人的自觉。
六、与评审、发布的衔接
规范的 commit/PR 历史还能向上游传导价值：一致的提交类型让发布说明和变更日志可以自动生成，清晰的 PR 描述减轻评审负担，准确的动机记录帮助事后回溯。这与自动化代码审查机器人构成完整的日常协作闭环。
七、一组好与差的说明对照
最直观的方式，是把同一段改动交给不同方式描述，看差距在哪。
假设改动是"给登录接口加了连续失败 5 次后锁定 15 分钟的逻辑，并补了单元测试"。差的说明：fix login（看不出改了什么、为什么、影响面）。稍好但仍虚的："优化登录功能，增强安全性"（说了动机，却没说具体规则，还贴上了"增强安全"的标签却无细节）。
好的说明：feat(auth): 登录连续失败 5 次锁定账户 15 分钟，正文写明动机（防暴力破解）、规则（计数窗口、锁定时长、成功后清零）、影响（新增一张失败计数表）、测试（覆盖锁定/解锁/正常登录三条路径）。对比可见，好说明的特征是具体、可验证、交代了影响面。让 Agent 生成时，应要求它对齐第三档，并在你核对时确认每条规则都与 diff 相符，尤其防止它把"加锁定"夸大成"重构了认证体系"。
八、让说明服务于"未来的读者"
写说明时容易只想着"赶紧提交"，换个视角能提升质量：想象半年后一个完全不了解背景的人，正在凌晨排查一个回归，他会希望这条提交告诉他什么。
他想知道的是：为什么当时要做这个改动（关联的需求或故障）、改动的关键规则是什么、有没有需要特别注意的副作用。把这个"未来读者"作为对象，你就会主动让 Agent 补上动机和影响面，而不满足于一行标题。好的提交历史是写给未来团队的信，而非给当下自己的便签。 当每个人都带着这种时间视角写作，整个代码库的可追溯性会显著提高，代码考古、版本回退、问题定位都会顺畅得多——这是一个小习惯带来的长期系统性收益。
九、回滚提交也要写清楚
协作中有一类提交特别需要好说明，却常被忽视：回滚（revert）的提交。
回滚时要让 Agent 协助写清：回滚的是哪次提交、为什么回滚（引发了什么问题）、是否有数据需要一并处理、后续打算怎么修。否则几个月后人们看到一个"revert"会一头雾水，甚至可能把当初回滚掉的问题改动又重新引入。回滚提交记录的是"这个方向踩过坑"，是极其宝贵的负经验。 把这类提交也写规范，团队就能避免在同一个地方反复摔跤。
十、把"为什么"和"是什么"分开写
好的说明里，"改了什么"和"为什么改"是两类信息，分别服务不同目的，值得有意识地区分。
"是什么"帮助理解改动本身（规则、影响面），要客观、可对照 diff；"为什么"帮助理解决策背景（动机、关联需求/故障），常要引用外部上下文。让 Agent 分别归纳、你分别核对，能避免它把两者混在一起、或用"为什么"的修辞掩盖"是什么"的空洞。当这两类信息都清晰，未来读者既能看懂代码、也能理解决策，提交记录的信息密度才真正够。
十一、把规范做成"不需要意志力"
任何依赖人"记得做"的规范都会随忙碌而失守，真正可靠的方式是让好行为成为阻力最小的默认。
把生成提交说明、填充 PR 模板绑到 git hook 或斜杠命令上，让规范的动作一键完成、而违规反而更麻烦；把格式约定写进规则文件让 Agent 默认遵守。当"写好说明"不额外消耗意志力，质量才能在压力大、赶工时依然保持。最好的规范不是写在墙上的要求，而是融进工具里的默认。 这与把安全护栏默认开启是同一个思路——靠制度约束人，不如靠流程托举人。
十二、在"快"与"留痕"之间
紧急修复时，人容易跳过流程直接改、事后补一个模糊提交，结果丢失了宝贵的上下文；即使在赶工时，也值得用最低成本留痕。
让 Agent 在紧急修复后迅速补一条哪怕简短但准确的说明：什么问题、怎么处理的，稍后再补充细节。紧急不是放弃记录的理由——恰恰是这类改动未来最需要回溯。用工具把"快"和"留痕"统一起来，让你既能立即止血、又不必牺牲可追溯性，这也是成熟工程团队在压力下依然保持纪律的体现。
十三、用一致格式换来自动化
坚持统一的提交类型和 PR 结构，还有一个常被忽视的回报：让下游自动化成为可能。
当类型标签一致，发布说明、变更日志、甚至贡献统计都能自动生成；当 PR 描述结构统一，评审机器人和度量工具也能可靠解析。今天多守的一点格式，是明天自动化的数据基础。 反之，格式混乱会让所有想在其上做自动化的尝试失效。让 Agent 把一致性默认化，团队就能以极小成本解锁一整条自动化链——从提交、评审、到发布，信息以统一格式顺畅流动，这是规范化协作最实际的复利。
十四、让"写好说明"成为团队共同的好习惯
最终，提交与 PR 的质量取决于是否成为团队默认的共同习惯，而个人的坚持会带动整体氛围。
当每个人都认真写、并能从他人的清晰说明中受益，团队会自然形成正向规范；让 Agent 降低每个人做到的成本，规范就不再依赖少数自觉者。好习惯一旦在团队里默认化，协作的整体质量会被集体抬高。 而这一切的起点很朴素：把每一次提交、每一个 PR，都当作一次清晰沟通的机会，认真对待。
十五、常见问题
Q：让它直接 commit 不行吗？ 不建议。生成文字后由你核对再提交，避免虚构描述或误提交无关改动。
Q：一次改了很多事怎么写？ 优先拆分提交；实在无法拆时，让它如实列出各部分，而不是用一个模糊标题糊弄。
Q：团队没有统一格式怎么办？ 先在规则文件里定下最小约定（类型 + 标题 + 动机），让 Agent 统一执行，格式很快会趋同。
Q：英文/中文仓库怎么处理？ 让它遵循仓库历史的语言习惯，保持一致性比语言本身更重要。
八、检查清单
- 提交说明基于实际 diff、遵循团队格式。
- 已核对类型、破坏性变更，剔除虚构内容。
- PR 描述含动机、方案、影响面、测试、评审重点。
- 已防止夸大与无依据的性能/安全结论。
- 已用斜杠命令/hooks 把流程固化为默认动作。
总结
Commit 和 PR 是每天都在写的团队时间胶囊，适合让 Agent 基于真实 diff 起草、由你核对后定稿：提交说明遵循 Conventional Commits 等约定、准确反映改动而不虚构，PR 描述按"动机—方案—影响面—测试—评审重点"为评审者组织上下文，同时要警惕它过度包装、给小修贴金，要求只陈述可证实的事实；最后用斜杠命令或 hooks 把这套动作固化成零摩擦默认、让规范写进规则文件，协作历史的质量就能整体抬升，并顺畅衔接自动审查与发布说明——关键始终是"AI 起草、人把关"，让准确克制成为代码协作记录的底色。