Claude CodeでGitコンフリクトを安全に解決する実践ガイド

Gitのコンフリクト解決は、単に <<<<<<< と >>>>>>> を消す作業ではありません。片方の変更を採用するだけなら数秒ですが、実際には「認証の仕様変更」「設定値の追加」「テストの期待値更新」など、別々の意図を壊さずに1つの状態へ戻す必要があります。

Claude Codeを使うと、衝突しているファイルを読み、関連する実装やテストを確認しながら解決案を作れます。ただし、丸投げすると危険です。AIが構文上きれいな解決をしても、業務ルールやチームの優先順位を間違えることがあります。

この記事では、Masaが実際のチーム開発で使っている「先に方針を渡し、Claude Codeに作業させ、人間が差分とテストで締める」流れを紹介します。初心者でもコピーして使えるコマンドを中心に、3つ以上のユースケース、具体的な落とし穴、検証手順までまとめます。

全体像

コンフリクト解決でClaude Codeに任せる範囲は「作業」までで、「判断」と「最終確認」は人間が持つと安定します。

main / release の変更
        |
        v
Gitが衝突を検出
        |
        v
Claude Codeに方針つきで解決を依頼
        |
        v
差分確認、テスト、lint、動作確認
        |
        v
人間が最終判断してコミット

公式情報として、Claude CodeのCLIは claude -p "query" のように非対話実行できます。詳しくは Claude Code CLI reference を確認してください。hooksや設定ファイルを組み合わせる場合は Claude Code hooks reference と Claude Code settings も参照します。Git側の再利用機能は Git rerere documentation が公式です。

先にやるべき3つの確認

Claude Codeを呼ぶ前に、まずリポジトリの状態を固定します。ここを省くと、コンフリクト解決中に別の未コミット変更を巻き込み、レビューしづらい差分になります。

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

git status --short で自分の作業途中のファイルが混ざっていないか確認します。git diff --name-only --diff-filter=U は、未解決の衝突ファイルだけを表示するコマンドです。Claude Codeに「対象ファイルを全部探して」と頼む前に、この一覧を自分でも見ておくと、あとで抜け漏れを判断できます。

作業前の方針は短くて構いません。たとえば次の4点だけでも結果はかなり変わります。

確認項目	Claude Codeに伝える内容
優先するブランチ	main のセキュリティ修正は残す、featureのUI変更も残す
触ってよい範囲	未解決ファイルと関連テストだけを編集する
生成物の扱い	lockfileやビルド生成物は手編集せず再生成する
完了条件	conflict markerが0件、テストが通る、差分を説明する

ここでいう conflict marker は <<<<<<<、=======、>>>>>>> の3種類です。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側の画面制御が同じファイルで衝突したとき、単純な「両方残して」指示では、UIは表示されるのにAPI側で403になる実装になりました。以後は「セキュリティ修正は必ず残す」「画面とAPIの整合性を確認する」と明示しています。

ユースケース2: rebase中の衝突を1コミットずつ解く

git rebase main の衝突は、mergeより慎重に扱います。rebase中の ours と theirs は直感と逆に感じる場面があるため、安易に git checkout --ours を使うと必要な変更を消すことがあります。

安全な進め方は、1回の衝突ごとにClaude Codeへ状況を渡し、解決後に git rebase --continue することです。

git rebase origin/main

cat > /tmp/claude-rebase-step.md <<'PROMPT'
rebase中の現在の衝突だけを解決してください。

確認してほしいこと:
- git statusでrebase中であることを確認する。
- git diff --name-only --diff-filter=Uで未解決ファイルを確認する。
- 現在適用中のコミットの意図をgit log --oneline -5で推測する。
- main側の変更とコミット側の変更を両立できる形に統合する。

制約:
- git rebase --continueは実行しない。解決とgit addまでで止める。
- unrelatedなファイルは触らない。
- 迷う場合は、採用した判断と代替案を説明する。
PROMPT

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

Claude Codeに git rebase --continue まで任せても動く場合はあります。ただ、初心者ほど一度止めて差分を見るほうが安全です。rebaseは履歴を書き換える操作なので、連続して自動実行させると、どのコミットで意味が変わったのか追いづらくなります。

ユースケース3: lockfileと生成ファイルの衝突を再生成で解く

package-lock.json、pnpm-lock.yaml、yarn.lock、OpenAPI生成物、Prismaクライアントのようなファイルは、手で整形して解くより、元になるファイルを正しく統合してから再生成するほうが安全です。

git diff --name-only --diff-filter=U

cat > /tmp/claude-lockfile-policy.md <<'PROMPT'
lockfileまたは生成ファイルの衝突を解決してください。

方針:
- package.jsonなど人間が編集する元ファイルを先に解決する。
- lockfileは手でマージしない。依存関係が確定した後にnpm installで再生成する。
- 生成コードは元のschema、OpenAPI定義、Prisma schemaを解決してから再生成する。
- 再生成後、差分が生成物として妥当か説明する。

実行してよい確認:
- 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

落とし穴は、lockfileだけを片方に寄せることです。たとえば package.json では両方の依存を残したのに、package-lock.json は main 側だけに戻すと、ローカルでは動いてもCIで依存解決が変わります。Claude Codeに任せる場合も、「元ファイルを先に」「lockfileは再生成」と必ず書きます。

ユースケース4: 衝突の原因を分析して次の衝突を減らす

コンフリクトを解いた直後は、再発防止のメモを作る良いタイミングです。特にルーティング、権限、スキーマ、設定ファイルは、毎回同じ人たちがぶつかりがちです。

cat > /tmp/claude-conflict-retro.md <<'PROMPT'
今回のGit conflictの原因を分析してください。

調べること:
- git diff --name-only --diff-filter=Uで対象ファイルを確認する。
- git log --oneline --all -- 対象ファイル で両ブランチの変更履歴を見る。
- 同じファイルに複数人の変更が集まった理由を分類する。

出力:
- 原因を3行以内で要約する。
- 次回からCLAUDE.mdに書くべきルールを提案する。
- PR分割、担当者調整、テスト追加のどれが効くか提案する。
PROMPT

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

たとえば src/routes.ts が毎週衝突するなら、ルート定義を機能別に分ける、feature flagの追加場所を決める、依存追加専用PRを作る、といった対策ができます。Claude Codeの使い方だけでなく、チームの変更単位を小さくすることが本質的な解決です。

コピペで使える衝突監査スクリプト

Claude Codeの作業後に、人間側でも conflict marker が残っていないか確認します。次のNode.jsスクリプトは外部パッケージなしで動きます。

// scripts/conflict-audit.mjs
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";

const output = execFileSync("git", ["diff", "--name-only", "--diff-filter=U"], {
  encoding: "utf8",
}).trim();

const files = output ? output.split(/\r?\n/) : [];
if (files.length === 0) {
  console.log("No unmerged files reported by git.");
}

let markerCount = 0;
for (const file of files) {
  const body = readFileSync(file, "utf8");
  const matches = body.match(/^(<<<<<<<|=======|>>>>>>>) /gm) ?? [];
  if (matches.length > 0) {
    markerCount += matches.length;
    console.log(`${file}: ${matches.length} conflict markers`);
  }
}

if (markerCount > 0) {
  process.exitCode = 1;
}

実行方法は次の通りです。

node scripts/conflict-audit.mjs
git diff --check
npm test

git diff --check は空白エラーや残った問題を検出するための基本コマンドです。アプリによっては npm run typecheck、npm run lint、E2Eテストも追加してください。

HooksとCLAUDE.mdで事故を減らす

毎回同じ注意を手で書くより、プロジェクトにルールを残したほうが安定します。Claude Codeの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.md はClaude Codeにプロジェクトの前提を渡すためのメモです。書き方は CLAUDE.mdベストプラクティス と Claude Codeチーム開発ガイド もあわせて読むと理解しやすいです。

## Git conflict policy
- セキュリティ修正、権限チェック、データ破壊防止の変更は原則として残す。
- UIだけでなくAPI、schema、testの整合性を確認する。
- package-lock.json、pnpm-lock.yaml、生成コードは手編集せず再生成する。
- rebase中はgit rebase --continueの前に差分を人間が確認する。
- 判断に迷う場合は、勝手に片方を捨てず、選択肢を提示する。

よくある落とし穴

1つ目は、ours と theirs を固定的に覚えることです。merge中とrebase中では見え方が変わるため、コマンドで片方を採用する前に git status と差分を見てください。

2つ目は、「両方残す」が常に正解だと思うことです。2つのバリデーション、2つのredirect、2つのfeature flagが同時に残ると、コードは動いても仕様が二重になります。Claude Codeには「同じ責務の実装が重複したら統合する」と明示します。

3つ目は、テストが通っただけで終わることです。衝突した領域が認可、課金、データ移行なら、ユニットテストに加えて手動確認やレビュー観点が必要です。

4つ目は、無関係なリファクタリングを混ぜることです。コンフリクト解決PRはレビュー負荷が高いので、命名変更やファイル移動は別PRに分けたほうが安全です。

実際に試した結果

Masaの検証では、15ファイル程度のTypeScriptプロジェクトの衝突で、方針なしに依頼した場合はテスト修正の抜けが出ました。一方で、この記事のように「優先順位」「触ってよい範囲」「再生成方針」「完了条件」を先に渡すと、差分レビューの時間がかなり短くなりました。Claude Codeはコンフリクト解決を自動化する道具として有効ですが、最後の git diff とテスト結果は必ず人間が確認する、という運用が一番安定します。

まずは小さなfeatureブランチで、git diff --name-only --diff-filter=U、方針つきプロンプト、npm test の3点セットから試してください。慣れてきたらhooksと CLAUDE.md にチームのルールを移し、毎回の衝突解決を「勘」ではなく「再現できる手順」に変えていきましょう。