AI AI 工具指南
AI 工具教程

AI agent 的 git commit 实践：规则、边界与配置

怎么定 commit 规范、划 commit 边界，以及绝不能让 Claude Code、Cursor、Codex commit 的东西。附真实配置。

发布于: 更新于: 作者: AI Productivity Guide Team 🌐 查看英文版本

现在 AI 编码 agent 会自己跑 git add、git commit，有些还会 git push。问题不在工具，而在信任边界：一次没看就批准的 commit，可能泄露 secret、覆盖同事的 history，或者把真实变更埋进一个 47 文件的大杂烩里，事后谁都没法 bisect。这篇给你一套现成的规则、配置和审查流程，让 agent 干活的同时，不把 git history 的最终控制权交出去。

适合用 Cursor agent 模式、Claude Code、Codex（任何自带 shell 的工具）的开发者。如果你曾经在没看暂存 diff 的情况下按过”是的，跑吧”，这篇就是写给你的。

一句话总结

  • 选一条信任边界并写下来：agent 暂存、人 commit，或者 agent commit、人 push。已经开了 PR 的分支上，永远不让 agent 拥有最后的 push。
  • 在 CLAUDE.md / AGENTS.md 写硬规则：不准 commit secret、不准 amend 已发布 commit、不准提交到 main、不准 git push --force。
  • 配一个 gitleaks pre-commit hook，人和 agent 都漏看时，secret 仍然出不去。它在暂存 diff 上跑完不到一秒。
  • 限制 commit 大小（一个逻辑变更、约 200 行），每次 agent commit 后用 git log -1 --stat 核对。
  • 显式配置署名：Claude Code 的 attribution 设置控制 Co-Authored-By 尾注；Cursor 的 onPreCommit hook 能拦下每一次 commit。

先把信任边界定下来

动任何设置之前，先决定人站在循环里的哪个位置。有两种清晰的选法，最糟的失败模式是哪个都不选、在两者之间漂移。

边界agent 做人做适合
只暂存git add、起草 message审 diff、跑 git commit、push共享分支、靠近 main 的一切
只到 commitgit add、git commit审 git log、跑 git push单人 feature 分支、快速迭代

绝不能越的那条线：在已经有 PR 的分支上，让 agent 拥有 git push。在那里一推可能触发 CI、通知 reviewer，并改写他们已经批过的内容。

开始前准备

  • 在 repo 根放 CLAUDE.md（Claude Code）或 AGENTS.md（Cursor、Codex 以及跨工具通用约定），写下面那套硬规则。两者都在 session 启动时读取、并随 repo 提交，所以每个同事的 agent 都会继承。
  • 确认 .gitignore 已经覆盖 .env*、凭证文件、以及 agent 可能溜进去的本地缓存。
  • 装一个 gitleaks pre-commit hook（见下文），把 secret 拦在最底层。

具体步骤

  1. 写规则。 在 CLAUDE.md / AGENTS.md：永远不 commit secret、永远不 amend 已发布 commit、永远不提交到 main、永远不 git push --force。用 agent 会照字面执行的祈使句来写。
  2. 用先审再提的流程。 让 agent 把文件暂存好、起草 message，然后你跑 git diff --cached 看一眼再确认。
  3. 要求用 conventional commit 格式（feat:、fix:、chore:），但 subject line 由你拍板。subject line 是跨 session 最容易漂的。
  4. 限制 commit 大小：一个逻辑变更一个 commit，最多约 200 行改动。AI 大 commit 是 review 疲劳无声失败的高发区。
  5. 提交后核对。 跑 git log -1 --stat，确认文件列表跟你预期一致。出现意外文件就用 git reset HEAD~1 撤回。

各工具真正要改的设置

各家默认值差得够多，“我在 Claude Code 里配过了”并不会带到 Cursor。下面是截至 2026 年 6 月各工具该设的项。

Claude Code

  • 署名（attribution）。 从 v2.0.62 起，attribution 设置（repo 级放 .claude/settings.json，全局放 ~/.claude/settings.json）同时控制 commit 的 Co-Authored-By 尾注和 PR footer。它接受一个带 commit 和 pr 键的对象，把任一个设成空字符串就去掉对应署名。它取代了旧的 includeCoAuthoredBy 布尔值——后者只管 commit 尾注，现在优先级更低。
  • 权限。 在 .claude/settings.json 的 permissions 里给 git 设门槛，让 agent 跑破坏性命令前必须问。放行 Bash(git add:*) 和 Bash(git commit:*)，同时把 git push 和 git reset --hard 留在需确认列表里，边界就由工具强制执行，而不是靠记忆。

Cursor

  • Hooks。 Cursor Hooks（2026）把脚本挂到编辑器事件上。onPreCommit hook 在 agent 暂存 commit 之前运行，从项目 .cursor 目录的 hooks.json 读取（想全项目生效就放 ~/.cursor）。用它来跑 gitleaks 或拦下对受保护分支的提交。
  • Worktrees。 Cursor 为并行 agent 创建隔离的 git worktree，每个 agent 在自己的工作副本里 commit。push 之前确认你审的是哪个 worktree。
  • Yolo 模式。 即便开了自动执行，Cursor 团队自己的建议也是：重要的 agent 运行前先 commit，让干净的 history 成为你的回滚路径。

Codex 等其他 agent

Codex 和大多数 CLI agent 读 AGENTS.md——这是 agent 指令的跨工具通用约定。把同样的硬规则写进去。它们没有可靠的 per-tool 署名开关，所以把 git push 留给人。

给 agent 的 commit message 模板

把这段贴进 AGENTS.md，agent 就不用每次重新发明格式：

type(scope): 60 字符以内的祈使句摘要

- 改了什么（1-3 个 bullet，文件 / 区域）
- 为什么（ticket 链接或简短理由）
- 跑了哪些测试 / 怎么验证的

期待输出形如 fix(auth): refresh token before retry on 401，加 2-3 行 bullet，而不是 200 字的小作文。这遵循 Conventional Commits 规范，agent 能从你已有的 git history 里可靠地认出这个格式。

配一个 gitleaks pre-commit hook

这是唯一一道在人和 agent 都漏看时还能拦住 secret 的网。用 pre-commit 框架，创建 .pre-commit-config.yaml：

repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks

然后跑 pre-commit install。这个 hook 用 --staged 跑 gitleaks，只检查 git diff --cached 即将提交的内容，在典型 diff 上远不到一秒就跑完。装好之后，每次 git commit（你的或 agent 的）都会自动扫描。

绝不能让 AI commit 的东西

  • 任何匹配 **/.env*、**/secrets.*、**/*.pem、**/credentials.json 的文件——哪怕 agent 坚持”只是本地用”。
  • 大于约 1MB 的二进制，没你确认不准提。*.sqlite、大 PNG 这类会永久撑大 history。
  • migration、schema 变更、infra/ 和 terraform/ 下的所有改动，必须人工 review。
  • 已经有 build 脚本生成的产物（dist/、build/、各种 *.lock 重建）。提交脚本变更，不提交产物。
  • 共享分支上的 merge commit。merge 编码意图，让人来定合并策略。

建议的操作流程

暂存 -> agent 提议 message -> 人读 diff -> 人 commit -> 人 push。已开 PR 的分支上，agent 永远不拥有最后的 git push。单人分支可以让它 push，但要求它先打印 remote 名和分支名，这样你能在落地前抓到打字错误。

FAQ

能让 agent 跑 git commit --amend 吗？ 只允许 amend 它本次 session 自己创建、且还没 push 的 commit。同事的 commit 一律不行，因为 amend 会改写 history。

git rebase 呢？ 本地 feature 分支允许；已经 push 共享过的禁止。把这条写进 AGENTS.md，让它每个 session 都被执行。

PR body 也让 agent 写吗？ 可以，但当草稿。agent 不知道哪个 reviewer 关心哪个细节。

不想要的 AI commit 怎么撤？ git reset --soft HEAD~1 把改动保留在暂存区；git reset --hard HEAD~1 全丢。只要遵守前面的规则，push 还没发生。

agent 需要自己的 git 身份吗？ 不需要。默认情况下 Claude Code 和 Cursor 以你的身份 commit，并为模型加一个 Co-Authored-By 尾注。用上面的 attribution 设置来配置或关掉这个尾注；除非你的 CI 需要，否则别另建一个 bot 作者。

会不会拖慢节奏？ 第一周会。第三周 agent 学会你的风格之后，每个 commit 的 review 大概 10-15 秒。

容易踩的坑

  • “改得很小”就让 agent 自动 commit 不审。小改动恰恰是最容易藏惊喜的地方。
  • 允许 git commit -am（自动暂存改动文件），会把无关 edit 也扫进来。
  • 让 agent amend 共享 commit”清理 history”，这是改写公共历史。
  • 没有 CLAUDE.md / AGENTS.md，agent 每个 session 都自己发明一套约定。
  • 只口头说”别动 X”。规则必须写进 repo，否则一个 session 内就遗忘。
  • 一个 session 一个超大 commit，bisect 不能用，回滚只能全有或全无。

相关阅读

标签: #AI 编程 #教程

相关文章