让 AI 写提交信息前先跑这三条命令：把 diff 变成可审的记录

让 AI 写提交信息前先跑这三条命令：把 diff 变成可审的记录

上周四下午，AI 帮我改完了导出模块的 6 个文件。它顺手写了一条提交信息：修复若干问题，优化代码结构。

我信了，直接提交。

第二天早会，同事在 review 里问了一句「这 6 个文件到底动了什么」。我打开提交记录，只有那 11 个字。要回答这个问题，得把 diff 从头翻一遍——我花了 20 分钟，最后写的回答还不如机器生成的准。

后来我把顺序倒过来：先跑三条命令拿到材料，再让 AI 照着材料写提交信息。它写不准的地方，基本上都是因为没看过 diff。

一、三条命令，各管一件事

# 1. 改了哪些文件、每个文件加减多少行
git diff –cached –stat

# 2. 每个文件的真实改动片段（去掉三行上下文，只留改动行）
git diff –cached -U0

# 3. 团队最近怎么写的，用来对齐风格
git log –oneline -8

第 1 条解决「范围」，第 2 条解决「内容」，第 3 条解决「格式」。

昨天那次提交，–stat 的输出是这样的：

src/export/task.py | 118 ++++++++++++++++++++++++—-
src/export/queue.py | 42 +++++++++++—–
src/api/export_view.py | 31 +++++++—
tests/test_export.py | 23 +++++++++
docs/export.md | 9 +++-
5 files changed, 214 insertions(+), 88 deletions(-)

看到这五行，提交信息的主语就定了：导出任务、队列、接口视图、测试、文档。而不是笼统的「若干问题」。

第 2 条要配一个数量控制，不然改动上千行时人是看不完的：

git diff –cached -U0 | wc -l

超过 300 行，我会把它拆成两次提交再写信息。提交信息写不清楚，多半是这次提交本身就该拆。

第 3 条经常被跳过，但它决定了写出来的信息能不能被搜到。团队里有人写 feat: 支持批量导出，有人写 feat(export): 批量导出支持按日期过滤，后者在 git log –grep 里才找得回来。

二、把三条命令的输出直接喂给 AI

我现在给 AI 的指令是这样一段：

不要直接 commit。先执行下面三条命令，把输出原样贴出来：
1) git diff –cached –stat
2) git diff –cached -U0
3) git log –oneline -8

然后按这个格式写提交信息，只输出文本，不要执行提交：
首行：type(scope): 动词 + 对象 + 结果，不超过 50 字
空行
正文三行：为什么改 / 改了哪几处 / 怎么验证的

「不要执行提交」这句必须写死。少这一句，它会自己 git commit -m，你连改的机会都没有。

另外两句我常加：

正文里出现的文件名必须来自 –stat 的输出，不要编。
不确定的改动不要写进提交信息，宁可少写。

第二条很关键。AI 会为了让句子完整，补一些「顺便优化了性能」之类没发生过的事。这种信息进了提交记录，以后查问题会被误导。

三、对照表：同一份 diff，两种写法

下面这张表是我从自己仓库的提交记录里抄出来的，左边是改之前的写法，右边是跑完三条命令后重写的。

右边这一列有个共同点：每个都能在 diff 里找到对应的那几行。找不到的，就说明这条信息是编的。

四、一条自查：提交信息能不能当索引用

写完我会用这条命令试一次：

git log –oneline –grep="导出" -5

如果这次提交能被搜出来，说明信息里带了对象名；搜不出来，就是写得太抽象。

再补一条更直接的：

git show –stat HEAD

提交信息和这次改动对不对得上，一眼就能看出来。信息说改了队列，–stat 里却没有 queue.py，那就是写错了。

五、这套做法的边界

它管的是「这次改动怎么描述」，不管「这次改动该不该做」。改动本身合不合理，还得靠 diff 预览那一步（前面写过，git add -N + git diff -w）。

另外，AI 写的提交信息我一般会改两处：动词和范围。动词决定以后能不能搜到，范围决定别人敢不敢直接合并。这两处改完，剩下的话术其实无所谓，团队内部能看懂就行。

回到开头那次提交。如果当时先跑 –stat，我会看到 5 个文件、214 行新增，其中 tests/test_export.py 多了 23 行——这一条就足以让我在提交信息里写清「补了测试」，而不是一句「优化结构」。

这是 AI 协作实战系列的第 16 篇。前面写过 diff 预览、改动台账、验收命令、回滚判据，都是同一件事：让 AI 的每次改动留下能核对的痕迹。

作者：信可维，做软件著作权申请材料的辅助整理与格式规范。你们团队的提交信息有统一格式吗，–stat 这一步是人工看还是写进 AI 指令里？