Claude Code로 Git 병합 충돌을 안전하게 해결하는 실전 가이드

Git 충돌 해결은 <<<<<<<, =======, >>>>>>> 표시를 지우는 작업으로 끝나지 않습니다. 실제로는 두 브랜치가 바꾼 의도를 동시에 이해해야 합니다. 한쪽은 권한 검사를 강화했고, 다른 한쪽은 새 화면과 테스트를 추가했을 수 있습니다. 이때 한쪽만 고르면 코드가 컴파일되어도 중요한 동작이 사라질 수 있습니다.

Claude Code는 충돌 파일을 읽고, 주변 구현과 테스트를 확인하고, Git 명령을 실행하며, 최종 diff를 설명할 수 있어서 이 작업에 잘 맞습니다. 하지만 판단까지 모두 맡기면 위험합니다. 사람은 우선순위와 편집 범위를 정하고, Claude Code는 반복적인 편집을 담당하며, 마지막 diff와 테스트는 사람이 확인하는 방식이 안정적입니다.

이 글은 ClaudeCodeLab 프로젝트에서 사용하는 실전 흐름을 정리한 것입니다. 초보자도 그대로 복사해 쓸 수 있는 명령과 팀 규칙, 자주 만나는 함정을 함께 다룹니다.

전체 흐름

main 또는 release의 변경
        |
        v
Git이 미해결 파일을 보고
        |
        v
정책을 포함해 Claude Code에 해결 요청
        |
        v
사람이 diff, 테스트, 동작을 검토
        |
        v
해결된 상태를 커밋

비대화식 실행은 공식 Claude Code CLI reference의 claude -p "query" 형식을 참고하면 됩니다. 자동 검사를 구성할 때는 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

마지막 명령은 아직 해결되지 않은 파일만 보여줍니다. 이 목록을 먼저 읽고, 예상하지 못한 파일이 있으면 왜 충돌했는지 확인한 뒤 진행합니다.

프롬프트에는 다음 네 가지를 짧게 넣는 것이 좋습니다.

확인 항목	예시
우선순위	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의 UI 분기가 같은 파일에서 충돌한 경우였습니다. 단순히 “둘 다 보존”이라고 요청하자 UI는 남았지만 API는 403을 반환했습니다. 그 이후에는 보안과 권한 변경을 반드시 유지하고 UI/API 일관성을 확인하라고 명시합니다.

사례2: rebase 충돌을 한 단계씩 해결

git rebase 중 충돌은 일반 merge보다 조심해야 합니다. 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

자동으로 계속 진행하게 할 수도 있지만, 초보자에게는 각 단계에서 멈추는 방식이 더 안전합니다. 잘못된 해결이 여러 커밋을 지나간 뒤 발견되면 원인을 찾기 어렵습니다.

사례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, dependency 파일에서 같은 충돌이 반복된다면 변경 단위나 소유권이 너무 넓다는 신호입니다.

cat > /tmp/claude-conflict-retro.md <<'PROMPT'
이번 Git conflict가 왜 발생했는지 분석해 주세요.

조사:
- git diff --name-only --diff-filter=U로 대상 파일을 확인합니다.
- git log --oneline --all -- <file>로 양쪽 브랜치 이력을 봅니다.
- 원인이 공유 소유권, 큰 PR, 생성 파일 노이즈, 프로젝트 규칙 부재 중 무엇인지 분류합니다.

출력:
- 원인 요약 3줄.
- CLAUDE.md에 추가할 규칙.
- PR 분리, 담당자 조정, 테스트 추가 중 무엇이 가장 효과적인지.
PROMPT

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

예를 들어 src/routes.ts가 매주 충돌한다면 기능별 라우트 등록으로 나누는 편이 낫습니다. package.json이 자주 충돌하면 의존성 변경 PR을 분리하는 것이 효과적입니다.

자동 검사와 팀 규칙

해결 후에는 최소한 다음을 실행합니다.

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

프로젝트에 typecheck, 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, test를 함께 확인한다.
- lockfile과 생성 코드는 손으로 병합하지 않고 재생성한다.
- rebase 중에는 git rebase --continue 전에 사람이 diff를 확인한다.
- 판단이 불명확하면 한쪽을 버리지 말고 선택지를 제시한다.

함정과 검증 결과

첫째, ours와 theirs를 고정된 의미로 외우지 마세요. 둘째, “둘 다 보존”이 항상 정답은 아닙니다. 검증 로직이나 redirect가 중복되면 코드가 복잡해집니다. 셋째, 테스트 통과만으로 끝내지 마세요. 인증, 결제, 마이그레이션, 삭제 로직은 별도 리뷰가 필요합니다.

Masa의 검증에서는 약 15개 파일이 충돌한 TypeScript 프로젝트에서 모호한 프롬프트는 문법 문제만 해결하고 테스트 수정을 놓쳤습니다. 반대로 이 글처럼 우선순위, 범위, 재생성 정책, 완료 조건을 먼저 전달하자 diff가 작아지고 리뷰 시간이 줄었습니다.

작은 feature 브랜치부터 시작해 보세요. 미해결 파일을 확인하고, 정책 있는 프롬프트를 전달하고, 테스트와 diff를 사람이 검토합니다. 안정되면 hooks와 CLAUDE.md에 규칙을 옮겨 팀 전체의 반복 가능한 절차로 만들 수 있습니다.