AI 辅助提交整理流程：从零散改动到可审查 Diff

AI 工具让写代码的速度变快了，但也更容易把一次变更做散：修 bug 的同时改了格式，补测试时顺手调整了命名，生成文档时又夹带了配置变动。最后 git diff 看起来很长，真正要审查的行为变化反而被淹没。

提交整理的目标不是把历史包装得漂亮，而是让每次变更都能被理解、被验证、被回滚。AI 很适合参与这件事：它可以帮助归类 diff、提炼意图、检查遗漏路径，并把提交说明写得更接近工程事实。

一、先把工作区变成可阅读状态

提交前不要急着写 commit message，先确认工作区里到底有什么。最基本的三条命令是：

1
2
3

git status --short
git diff --stat
git diff

如果改动很多，可以先让 AI 帮忙做一次结构化总结：

请阅读当前 diff，按文件分组总结：
1. 每个文件的主要变化。
2. 哪些变化是功能逻辑。
3. 哪些变化是测试、文档、格式或配置。
4. 是否存在看起来无关的修改。
先不要写提交说明。

这一步的重点是发现“混在一起”的内容。比如一次 Android loading 修复里，如果同时出现主题颜色调整、依赖升级和日志格式修改，就应该先停下来拆分，而不是把所有内容放进一个提交。

二、区分意图相同和文件相同

很多人拆提交时只按文件拆，但更可靠的方式是按意图拆。一个文件里可能同时包含两类变化：一类是修复逻辑，一类是格式整理。相反，一次完整的业务修复也可能跨越多个文件。

可以把变更意图写成几句话：

1
2
3

意图 A：保存失败后恢复 loading 状态，并显示错误提示。
意图 B：为保存成功、失败和重复点击补充测试。
意图 C：整理旧注释和空行。

然后再看 diff 是否能对应这些意图：

同一个意图可以跨多个文件。
一个文件内的无关意图应该尽量拆开。
纯格式化和行为变更不要混在一起。
配置变更要单独说明影响范围。

AI 在这里的价值，是帮助发现人眼容易忽略的“顺手改动”。尤其是批量格式化、自动 import、锁文件更新这类变化，很容易让评审者误以为行为变动比实际更大。

三、用暂存区表达提交边界

Git 的暂存区不只是提交前的中转站，也是一种表达边界的工具。整理提交时，可以用它来逐步构造一个清晰的 diff。

常用命令包括：

git add <file>
git add -p
git diff --cached
git restore --staged <file>

当一个文件里既有必要修改又有无关修改时，git add -p 很有用。它可以按 hunk 暂存，让一次提交只包含真正属于当前意图的片段。

暂存后不要直接提交，先检查已暂存内容：

1	git diff --cached

这时可以继续让 AI 审查暂存区：

1
2
3

请只审查 staged diff。
判断它是否构成一个单一、完整、可验证的提交。
如果发现无关变化、遗漏测试或提交边界不清楚，请指出具体文件和原因。

这个提示能把 AI 的注意力限定在即将提交的内容上，避免它被工作区里其他临时修改干扰。

四、提交说明要写事实，不写情绪

好的提交说明不需要夸张，也不需要复述每一行代码。它应该回答三个问题：

为什么需要这个变更。
这个变更具体做了什么。
怎么验证它是有效的。

例如：

fix settings save loading state

- clear loading state when save request fails
- keep duplicate save clicks ignored while request is running
- add ViewModel tests for success, timeout and repeated click paths

Verification:
- ./gradlew testDebugUnitTest

如果项目使用中文提交说明，也可以保持同样结构：

修复设置保存失败后的 loading 状态

- 请求失败时恢复 loading=false，并显示错误提示
- 保存进行中忽略重复点击
- 补充成功、超时和重复点击路径测试

验证：
- ./gradlew testDebugUnitTest

AI 可以帮忙起草提交说明，但不要让它写“优化代码”“完善逻辑”“提升体验”这种模糊表达。提交说明越接近事实，后续回溯问题时越有价值。

五、让 AI 检查缺失的验证路径

提交前最容易漏掉的是验证。代码看起来正确，测试也可能通过，但关键路径不一定都覆盖了。

可以给 AI 一个明确任务：

1
2
3

请根据 staged diff 推导这次变更的风险点。
按正常路径、失败路径、边界路径和回归路径列出验证清单。
只列和当前提交直接相关的验证项。

例如一次命令行脚本改动，验证清单可能是：

正常路径：输入合法参数时生成预期文件。
失败路径：缺少参数、路径不存在、权限不足时输出明确错误。
边界路径：空目录、已有输出文件、文件名包含空格时行为正确。
回归路径：旧参数仍然兼容，默认输出位置不变。

这类清单不一定都要自动化，但至少应该知道哪些路径已经跑过，哪些只是人工判断。提交说明里的 Verification 也应该诚实记录实际执行过的命令，不要把“应该能过”写成“已经验证”。

六、把无关改动留在下一次

AI 生成代码时经常会顺手做额外整理。有些整理本身是对的，但不应该挤进当前提交。

常见的无关改动包括：

重新排序 import。
改动大量格式但不影响行为。
重命名局部变量但没有必要。
调整日志文案但与当前 bug 无关。
升级依赖或修改锁文件。
删除看似无用但没有验证过的兼容逻辑。

发现这类改动时，可以有三种处理方式：

如果确实无用，撤回。
如果有价值，单独提交。
如果不确定，先保留在工作区，不进入当前提交。

关键是不要让评审者同时判断“这个 bug 是否修好”和“这批整理是否合理”。一次提交只承载一个清晰意图，沟通成本会低很多。

七、提交前做一次反向说明

除了写“我改了什么”，还可以让 AI 做一次反向说明：从 diff 推导外部行为变化。

提示可以这样写：

请站在评审者角度，根据 staged diff 回答：
1. 用户可见行为是否变化。
2. 对外接口或数据格式是否变化。
3. 失败路径是否变化。
4. 是否引入新依赖或新运行条件。
5. 如果要回滚，这个提交是否可以独立回滚。

这个检查能暴露很多隐藏风险。比如一个看似内部的重构，如果改变了错误码、排序规则或缓存时机，本质上就是外部行为变化。提交前发现这些问题，比评审时被问出来更好处理。

八、一个可复用流程

日常可以把 AI 辅助提交整理固定成一套流程：

1. 查看 git status、diff stat 和完整 diff。
2. 让 AI 按文件和意图总结变更。
3. 拆出无关修改，必要时用 git add -p 构造提交边界。
4. 检查 staged diff 是否单一、完整、可验证。
5. 根据 staged diff 生成验证清单。
6. 运行必要构建、测试或静态检查。
7. 写包含背景、改动和验证结果的提交说明。

对应提示词可以写成：

请协助整理这次提交。
要求：
1. 只基于当前 diff 或 staged diff 分析，不猜测未展示代码。
2. 先按意图归类变更，再判断是否需要拆提交。
3. 指出无关修改、缺失测试和潜在行为变化。
4. 最后生成一份简洁提交说明，包含验证结果。

这段提示的核心，是让 AI 参与工程判断，而不是只负责润色文字。

九、总结

AI 辅助开发越深入，提交整理越重要。因为生成速度越快，零散修改混入同一次提交的概率就越高。如果不整理，后续评审、排障和回滚都会变得困难。

一个可审查的提交，通常满足几个条件：

意图单一，范围清楚。
diff 能解释为什么需要这些文件变化。
测试和验证路径与风险匹配。
提交说明记录事实，而不是泛泛描述。
可以独立回滚，不依赖隐藏的无关修改。

把 AI 放进这套流程里，它能帮助我们更快地整理上下文、发现越界改动、补齐验证清单。最终交付出来的不是一堆看似完成的代码，而是一组更容易被团队理解和维护的工程变更。