用 Claude Code 安全解决 Git 合并冲突实战指南

Git 冲突不是把 <<<<<<<、=======、>>>>>>> 删除掉就结束。真正难的是理解两边改动的意图：一边可能修了权限漏洞，另一边可能新增了页面和测试；如果只是机械地保留某一边，代码也许能编译，却会丢掉业务规则。

Claude Code 很适合处理这类工作，因为它可以读取冲突文件、查看相邻代码、运行 Git 命令、修正测试并解释最终差异。但它不能替你做产品判断。最安全的方式是：人先写清楚优先级和边界，让 Claude Code 做编辑，再由人检查 diff 和测试结果。

本文整理的是 ClaudeCodeLab 项目中使用的流程。它适合初学者直接复制，也适合团队把冲突处理变成可复用的规范。

流程图

main 或 release 分支的新改动
        |
        v
Git 报告未合并文件
        |
        v
带着策略让 Claude Code 解决
        |
        v
人工检查 diff、测试和业务行为
        |
        v
提交已解决的状态

Claude Code 的非交互用法可以参考官方 Claude Code CLI reference。如果要自动运行检查，请看 Claude Code hooks reference 和 Claude Code settings。Git 侧重复利用历史解决方案的功能是 Git rerere。

先确认仓库状态

在调用 Claude Code 之前，先确认当前仓库没有混入无关改动。

git status --short
git branch --show-current
git diff --name-only --diff-filter=U

git diff --name-only --diff-filter=U 只列出未解决冲突的文件。这个列表你自己也要先看一遍。如果出现不认识的文件，不要急着让 AI 修改，先弄清楚它为什么参与了冲突。

建议在提示词里写清楚四件事：

项目	例子
优先级	保留 main 的安全修复，也保留 feature 的新 UI
编辑范围	只改未解决文件和直接相关测试
生成文件	lockfile 和生成代码不要手工合并，先解决源文件再重新生成
完成条件	没有 conflict marker，git diff --check 通过，测试通过，说明决策

这里的 conflict marker 指 Git 插入的冲突标记，也就是 <<<<<<<、=======、>>>>>>>。

用例1: feature 分支合并 main

最常见的场景是 feature 分支开发了几天后，需要合并最新的 main。

git fetch origin
git merge origin/main

cat > /tmp/claude-conflict-plan.md <<'PROMPT'
请解决当前 Git merge conflict。

上下文:
- 当前分支是 feature 分支。
- origin/main 的安全修复和类型定义必须保留。
- feature 分支新增的页面、API 调用和测试也必须保留。
- 只处理 git diff --name-only --diff-filter=U 列出的文件。

任务:
1. 简要说明每个文件为什么冲突。
2. 删除 conflict marker，并整合两边意图。
3. 只在必要时更新直接相关测试。
4. 运行 git diff --check。
5. 最后总结做了哪些决定、运行了哪些命令。

禁止:
- 做无关重构。
- 不说明原因就丢弃任意一边。
- 手工编辑 package-lock.json。
PROMPT

claude -p "$(cat /tmp/claude-conflict-plan.md)"
git diff --check
npm test

这个提示词的重点是策略，而不是语气。你告诉 Claude Code 哪些修改必须保留、哪些文件可以碰、怎样才算完成，它的输出就更容易审查。

Masa 的一次失败经验是：main 加强了授权判断，feature 分支新增了页面分支。只说“保留两边”时，页面显示了，但 API 仍然返回 403。后来我们在提示词里明确写上“安全和授权改动优先保留，并检查 UI 与 API 是否一致”。

用例2: rebase 中逐个提交解决

git rebase 的冲突比普通 merge 更需要谨慎，因为 Git 会在每个提交上暂停。rebase 中的 ours 和 theirs 很容易让人误解，所以不要在没看 diff 的情况下直接使用 git checkout --ours。

git rebase origin/main

cat > /tmp/claude-rebase-step.md <<'PROMPT'
只解决当前 rebase 步骤里的冲突。

请先:
- 用 git status 确认当前处于 rebase。
- 用 git diff --name-only --diff-filter=U 列出未解决文件。
- 从最近的 git log 推测当前正在重放的提交意图。
- 把该提交的意图与 main 的最新行为整合。

限制:
- 不要执行 git rebase --continue。
- 解决并 git add 后停止。
- 不要编辑无关文件。
- 如果判断不明确，请说明选项，而不是直接猜。
PROMPT

claude -p "$(cat /tmp/claude-rebase-step.md)"
git diff --check
npm test
git rebase --continue

让 Claude Code 自动继续 rebase 也可以，但初学者最好每一步都停下来检查。这样即使解决方案不合适，也能知道问题出在哪个提交。

用例3: lockfile 和生成代码

package-lock.json、pnpm-lock.yaml、OpenAPI 生成文件、Prisma 生成物都不适合手工合并。正确顺序是先解决源文件，再重新生成。

cat > /tmp/claude-lockfile-policy.md <<'PROMPT'
请解决 lockfile 或生成文件冲突。

策略:
- 先解决 package.json、schema、OpenAPI 定义等人工维护的源文件。
- 不要手工合并 package-lock.json。
- 依赖确定后运行 npm install 重新生成 lockfile。
- 生成代码要从源 schema 重新生成。
- 解释为什么重新生成后的 diff 是合理的。

允许执行:
- npm install
- npm test
- npm run lint
PROMPT

claude -p "$(cat /tmp/claude-lockfile-policy.md)"
npm install
npm test
git add package.json package-lock.json

常见坑是 package.json 保留了两边依赖，但 lockfile 只采用其中一边。这样本地可能能跑，CI 却会解析出不同依赖。把“源文件优先，生成文件再生成”写进规则，可以减少这类问题。

用例4: 分析冲突原因

冲突刚解决完，是做复盘的最好时机。路由表、权限映射、schema、依赖文件如果反复冲突，通常说明团队的改动边界太大。

cat > /tmp/claude-conflict-retro.md <<'PROMPT'
请分析这次 Git conflict 为什么发生。

调查:
- 用 git diff --name-only --diff-filter=U 查看对象文件。
- 用 git log --oneline --all -- <file> 查看两边历史。
- 判断原因是共享所有权、PR 太大、生成文件噪声，还是缺少项目规则。

输出:
- 三行以内总结原因。
- 建议写进 CLAUDE.md 的规则。
- 判断最有效的改进是拆 PR、协调负责人，还是补测试。
PROMPT

claude -p "$(cat /tmp/claude-conflict-retro.md)"

例如 src/routes.ts 每周冲突，就该考虑按功能拆分路由注册。package.json 经常冲突，就把依赖升级拆成独立 PR。Claude Code 可以快速看历史，但真正的改进通常来自团队流程。

自动检查和团队规则

解决后至少运行这些检查：

git diff --check
git diff --name-only --diff-filter=U
npm test

如果项目有类型检查、lint、E2E，也要加上。还可以用 hooks 自动执行基础检查。更多设置可参考站内的 Claude Code Hooks 指南。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(git merge*)|Bash(git rebase*)",
        "hooks": [
          {
            "type": "command",
            "command": "git diff --check && npm test"
          }
        ]
      }
    ]
  }
}

同时，把冲突策略写进 CLAUDE.md。它是 Claude Code 读取项目规则的入口。写法可以参考 CLAUDE.md best practices 和 团队协作指南。

## Git conflict policy
- 默认保留安全修复、权限检查和防止数据丢失的改动。
- 同时检查 UI、API、schema 和测试。
- lockfile 与生成代码不要手工合并，必须重新生成。
- rebase 中执行 git rebase --continue 前，由人检查 diff。
- 判断不明确时列出选项，不要擅自丢弃一边。

常见坑与验证结果

第一，不要死记 ours 和 theirs。在 rebase 中它们的含义很容易让人误判。第二，“两边都保留”不一定正确，两个校验、两个 redirect、两个 feature flag 可能造成重复逻辑。第三，测试通过不代表业务正确，认证、计费、迁移、数据删除都需要额外人工检查。

Masa 的实测结果是：在一个约 15 个冲突文件的 TypeScript 项目里，模糊提示能修掉语法问题，但漏改了相关测试；加上本文这种优先级、范围、再生成方针和完成条件后，diff 更小，审查也更快。

建议从一个小 feature 分支开始练习：先列出未解决文件，再给 Claude Code 清晰策略，最后运行测试并人工看 diff。等流程稳定后，把规则沉淀到 hooks 和 CLAUDE.md，让冲突解决从临场判断变成团队可复用的流程。