Git worktree로 Claude Code를 안전하게 병렬로 실행하기 — 1개 리포지토리 내 다중 작업 시 브랜치 충돌 방지 및 실무 절차

Claude Code를 여러 개 동시에 실행하려고 하다가 다음과 같은 경험을 한 적은 없으신가요?

• 하나의 리포지토리(Repo)에서 2개의 세션을 돌렸더니, 한쪽이 편집 중인 파일을 다른 쪽이 덮어씌웠다
• 기능 A를 구현하던 중 "급하게 버그 수정 좀 해줘"라는 요청을 받아, 작업을 중단하고 git stash를 해야 하는 상황이 발생했다
• 브랜치를 전환하는 순간, 다른 세션의 Claude Code가 "방금 전까지 있던 파일이 사라졌다"며 혼란을 겪기 시작했다
• 결국 안전을 위해 항상 1개의 세션만 실행할 수밖에 없어, 대기 시간이 아깝다

원인은 "Claude Code가 똑똑하지 않아서"도, "병렬 실행이 위험해서"도 아닙니다. 동일한 작업 디렉토리(Same Working Directory, 동일한 브랜치)를 여러 세션이 공유하고 있다는 점이 문제입니다.

이를 해결하는 것이 바로 git worktree입니다. 하나의 리포지토리로부터 물리적으로 다른 폴더와 다른 브랜치를 분리하여, Claude Code 세션마다 완전히 독립된 작업 공간을 부여합니다.

이 기사에서는 worktree를 "명령어는 알지만 평소에는 쓰지 않는" 상태에서 "Claude Code 병렬 운용의 표준 장비"로 만들기 위한 구체적인 절차를 실무적인 관점에서 정리합니다. 모두 오늘 바로 사용 중인 리포지토리에서 테스트할 수 있습니다.

먼저 오해를 풀어두겠습니다. "브랜치를 나누고 있으니 병렬로 실행해도 괜찮지 않을까?"라는 의문입니다.

답은 No입니다. 이유는 간단합니다. git checkout (git switch)은 작업 디렉토리 자체를 변경하기 때문입니다.

리포지토리 /myapp (작업 디렉토리는 1개)
├─ Claude 세션 A: feature/login 작업 중
└─ Claude 세션 B: "fix/bug를 봐줘"라고 checkout
...

브랜치는 "이력의 가지"이지만, 그 가지를 투영하는 작업 디렉토리는 1개 리포지토리당 1개입니다. 여기에 여러 세션이 공존하면, 브랜치를 전환할 때마다 서로의 기반이 무너집니다.

git worktree는 이 "작업 디렉토리는 1개"라는 제약을 해제합니다. 하나의 .git을 공유하면서도, 브랜치마다 독립된 물리적 폴더를 가질 수 있게 됩니다.

리포지토리 본체 /myapp → main
worktree /myapp-login → feature/login
worktree /myapp-bugfix → fix/bug

각각 별도의 폴더이므로, 별도의 폴더에서 다른 Claude Code를 실행하면 서로 전혀 간섭하지 않습니다. 이것이 병렬 운용의 토대입니다.

worktree는 명령어가 많아 보이지만, 실무에서 사용하는 것은 사실상 3가지입니다.

# 1. 새로운 브랜치 + worktree를 동시에 생성
git worktree add ../myapp-login -b feature/login
# 2. 현재 있는 worktree 목록 확인
...

git worktree add ../myapp-login -b feature/login의 의미는 다음과 같습니다.

부분	의미
../myapp-login	worktree를 배치할 물리적 폴더 경로 (리포지토리 외부, 상위 계층에 두는 것이 정석)
-b feature/login	신규 브랜치 feature/login을 생성하여 해당 위치에 연결

기존 브랜치에 대해 worktree를 만들고 싶을 때는 -b를 제외합니다.

# 기존의 fix/bug 브랜치를 별도 폴더에 체크아웃
git worktree add ../myapp-bugfix fix/bug

git worktree list의 출력 결과는 다음과 같습니다. 현재 어떤 폴더가 어떤 브랜치에 연결되어 있는지 한눈에 알 수 있습니다.

/myapp a1b2c3d [main]
/myapp-login e4f5g6h [feature/login]
/myapp-bugfix i7j8k9l [fix/bug]

기억할 것은 "add로 만들고, list로 확인하고, remove로 정리한다"뿐입니다.

worktree의 위력을 가장 잘 알 수 있는 것이 바로 이 "끼어들기" 시나리오입니다.

Before (worktree 없음 · stash 지옥):

1. feature/login 구현 중 (Claude Code가 3개 파일 편집 완료 · 미커밋)
2. "운영 환경에 버그 발생. 지금 바로 수정해"라며 작업 중단 요청
3. git stash로 작업 내용 임시 저장
...

이는 작업 디렉터리(Working Directory)가 하나뿐이기 때문에 발생하는 전형적인 소모적 상황입니다. Claude Code를 실행 중일 때는 stash 전후로 컨텍스트(Context)도 어긋나기 때문에 더욱 혼란스러워집니다.

After (worktree로 개입을 물리적으로 분리):

# feature/login 작업은 그대로 둔 채로 OK (건드리지 않음)
# 개입(Hotfix)을 위해 별도 폴더에 worktree 생성
git worktree add ../myapp-hotfix -b fix/login-crash main

그 후 새로운 폴더 ../myapp-hotfix에서 별도의 Claude Code 세션(Session)을 실행하기만 하면 됩니다.

# 별도의 터미널에서
cd ../myapp-hotfix
claude

기존 feature/login 폴더와 세션은 전혀 건드리지 않으므로, stash나 충돌 해결(Conflict Resolution)이 발생하지 않습니다. 버그 수정이 끝나면 worktree를 삭제하고 원래 작업으로 돌아가기만 하면 됩니다.

# hotfix가 끝나고 머지(Merge) 완료되었다면 정리
git worktree remove ../myapp-hotfix

관점	Before (stash 운용)	After (worktree 운용)
원래 작업	퇴피(Stash)가 필요함	그대로 둔 채로 OK
...	...	...

여기서부터가 본론인 '병렬 운용'입니다. 하는 방법은 어렵지 않습니다. worktree마다 1개의 세션을 할당하기만 하면 됩니다.

# 기능 개발용
git worktree add ../myapp-feature -b feature/dashboard main
# 테스트 정비용
...

# 터미널 1
cd ../myapp-feature
claude
...

두 세션은 별도의 폴더와 별도의 브랜치(Branch)에서 동작하므로, 동일한 파일을 동시에 편집하는 사고가 원리적으로 발생하지 않습니다. 한쪽에서 커밋을 하든 브랜치를 전환하든, 다른 한쪽에는 영향을 주지 않습니다.

# 메인 리포지토리로 복귀
cd ../myapp
# 각각의 성과를 머지
...

핵심은, 병렬로 진행해도 되는 것은 '독립된 태스크(Task)'뿐이라는 점입니다. 판단 기준은 다음과 같습니다.

상황	worktree로 병렬 운용 가능 여부
기능 A와 테스트 정비 (수정하는 파일이 다름)	◯ 병렬 가능
...	...

"별도 폴더라면 충돌하지 않는다"는 것은 어디까지나 작업 디렉터리의 이야기입니다. 최종적으로 머지해야 하는 이상, 논리적으로 동일한 코드를 건드리는 태스크는 worktree를 나누더라도 결국 머지 과정에서 충돌하게 됩니다. 물리적 분리와 논리적 분리는 별개라는 점을 의식해야 합니다.

worktree를 3개, 4개로 늘리다 보면 이번에는 "어느 폴더에서 무엇을 하고 있었는지" 알 수 없게 됩니다. 이를 방지하려면, 폴더명에 역할을 부여하여 고정적으로 운용하는 것을 추천합니다.

myapp/ ← main 전용 (여기서는 작업하지 않음 · 통합과 머지만 수행) 
myapp-feat/ ← 기능 개발 상설 worktree
myapp-fix/ ← 버그 수정 상설 worktree
...

각 폴더에 용도에 특화된 CLAUDE.md를 배치해 두면, 실행된 Claude Code가 즉시 "자신이 무엇을 담당하고 있는지" 파악할 수 있습니다.

<!-- myapp-fix/CLAUDE.md 예시 -->
# 이 worktree의 역할
- 여기는 "버그 수정 전용" worktree입니다
...

포인트: worktree마다 역할을 고정하면 Claude Code에 대한 지시(Instruction)도 짧아집니다. 매번 "이것은 수정 태스크이며..."라고 설명할 필요가 없어지며, 폴더에 들어가는 순간 문맥(Context)이 결정됩니다.

의외로 효과적인 것은, 메인 리포지토리(main 브랜치가 있는 폴더)에서는 직접 작업하지 않는다는 규칙입니다. 메인 리포지토리를 "각 worktree의 성과를 머지하는 통합 전용 장소"로 정해 두면, main을 실수로 더럽히는 사고를 줄일 수 있습니다. Claude Code 세션 역시 원칙적으로 worktree 측에서만 실행합니다. worktree는 편리하지만 몇 가지 전형적인 함정이 있습니다. 미리 알아두면 회피할 수 있습니다.

git worktree add ../myapp-2 main
# fatal: 'main' is already checked out at '/myapp'

Git은 사양으로서, 하나의 브랜치는 하나의 worktree에만 연결될 수 있습니다. 이는 오히려 안전장치입니다. 동일한 브랜치를 서로 다른 폴더에서 동시에 편집할 수 있게 된다면, 그것이야말로 충돌의 온상이 될 것입니다. 병렬로 작업하고 싶다면 반드시 브랜치도 나누어야 합니다.

worktree는 작업 디렉토리 (Working Directory)의 복사본이므로, .gitignore에 등록된 파일(node_modules/, .env, 빌드 결과물 등)은 새로운 폴더에 존재하지 않습니다. 새로운 worktree를 만들었다면 의존성(dependency) 설치가 별도로 필요합니다.

cd ../myapp-feature
npm install # worktree마다 필요
cp ../myapp/.env . # gitignore된 설정은 수동으로 복사

이를 Claude Code의 설정 절차로서 worktree의 CLAUDE.md에 작성해 두면, 실행 직후 자동으로 환경을 정돈해 줍니다.

폴더만 수동으로 삭제하면 Git의 관리 정보에 '깨진 worktree'가 계속 남게 됩니다.

# NG: 폴더만 삭제
rm -rf ../myapp-feature # 관리 정보가 남아 list에 유령이 나타남
# OK: 반드시 remove로 삭제
...

정리는 반드시 git worktree remove를 사용하고, 만약 수동으로 삭제해 버렸다면 git worktree prune으로 참조를 정리한다고 기억해 두면 안전합니다.

여러 개의 worktree를 나란히 두고 있으면, Claude Code가 친절을 베풀어 옆 폴더(../myapp-fix 등)까지 읽으러 가거나 편집하려고 할 때가 있습니다. 이는 병렬 분리의 의미를 퇴색시킵니다. 각 worktree의 CLAUDE.md에 한 줄을 추가해 두세요.

- 이 폴더 외부(../의 다른 worktree)의 파일은 읽지 않음·편집하지 않음

원칙	요점
1. 작업은 worktree로 물리적 분리	브랜치 전환이 아닌 별도 폴더로 구분
...

git worktree는 기능 자체로 이미 오래전부터 존재했지만, Claude Code와 같이 "작업 디렉토리를 전제로 동작하는 AI 에이전트"와 조합했을 때 비로소 진가가 발휘됩니다. 하나의 리포지토리에서 2개, 3개의 태스크를 안전하게 병행할 수 있게 되면, "중간에 작업이 들어와서 중단해야 하는" 소모적인 상황이 사라지고 대기 시간도 단축할 수 있습니다.

우선 "중간에 들어온 버그 수정을 worktree로 분리하기"라는 한 가지 방법부터 시도해 보세요. git stash 지옥에서 벗어나는 감각을 즉시 체감할 수 있을 것입니다.

본 기사의 내용을 실제 프로젝트에서 시도하려면, 토대가 되는 CLAUDE.md와 폴더 구성이 있어야 원활합니다. 제가 사용 중인 스타터 구성을 무료로 공개하고 있습니다.

무료 스타터 (GitHub):

더 나아가 워크플로우나 서브 에이전트 설계를 "실행 가능한 스킬 파일"로 정리한 패키지도 준비되어 있습니다. 로컬에서 /명령어 형태로 호출할 수 있는 형태입니다.

스타터 팩 (¥1,980): CLAUDE.md 템플릿 7종 · Hooks · MCP 설정
https://streamsolty.gumroad.com/l/gliwz

워크플로우 OS (¥9,800): 79개의 스킬 + 워크플로우 3개 + 프롬프트 10종

먼저 무료 리포지토리부터 시도해 보시고, 더 체계적으로 사용하고 싶어지면 그때 검토해 주셔도 충분합니다. 기사의 내용만으로도 효과는 나타납니다.

최신 팁은 X에서도 발신하고 있습니다: @k___n___t_1125