(Git) git worktree로 Claude Code 병렬 세션 실행하기 - AI 코딩 생산성 높이는 실전 가이드

포스팅 목차

1. Git Worktree란? 왜 필요한가?
2. Worktree vs git stash vs branch 전환 비교
3. Git Worktree 기본 사용법 및 자주 쓰는 커맨드
4. 브랜치 병렬 작업 실전 활용
5. Claude Code + Worktree 연동하기
6. 공부하면서 생겼던 의문점
7. 참고 자료

---

1. Git Worktree란? 왜 필요한가?

개발하다 보면 이런 상황이 자주 생깁니다.

feature/payment 브랜치 작업 한창 중
  → 갑자기 긴급 버그 리포트 들어옴
  → git stash로 작업 임시 저장
  → main 브랜치로 전환
  → 버그 수정
  → 다시 feature/payment로 복귀
  → stash 꺼내기
  → 어디까지 했더라... 

이 문제를 해결하는 것이 바로 Git Worktree입니다.

Git Worktree는 하나의 Git 저장소에서 여러 브랜치를 서로 다른 디렉토리에 동시에 체크아웃할 수 있는 기능입니다.

# 기존 방식 — 한 번에 하나의 브랜치만 작업 가능
my-project/
└── (feature/payment 작업 중)
    → main으로 전환하려면 stash 필요

# Worktree 방식 — 여러 브랜치를 동시에 각각의 디렉토리에서 작업
my-project/          ← main 브랜치
my-project-payment/  ← feature/payment 브랜치 (동시 작업 가능)
my-project-hotfix/   ← hotfix/login 브랜치 (동시 작업 가능)

세 디렉토리는 모두 같은 .git 저장소를 공유하기 때문에 디스크 공간도 효율적입니다.

💡 한 줄 요약 : Worktree = 하나의 Git 저장소에서 여러 브랜치를 동시에 각각의 폴더에서 작업하는 기능

---

2. Worktree vs git stash vs branch 전환 비교

구분	git stash	branch 전환	git worktree
작업 방식	변경사항 임시 저장 후 전환	브랜치 전환 (작업 중 파일 변경됨)	별도 디렉토리에서 동시 작업
컨텍스트 유지	X 잃어버림	X 잃어버림	O 각 디렉토리에서 독립 유지
병렬 작업	X 불가능	X 불가능	O 가능
서버 병렬 실행	X 불가능	X 불가능	O 각 포트로 동시 실행 가능
디스크 사용량	적음	적음	워킹 파일만 추가 (.git 공유)
복잡도	낮음	낮음	중간

언제 뭘 써야 할까?

상황	추천
잠깐 다른 브랜치 확인 후 바로 돌아올 때	git stash 또는 branch 전환
긴급 버그 수정과 기능 개발을 동시에 진행할 때	O git worktree
여러 기능을 병렬로 개발할 때	O git worktree
Claude Code 등 AI 에이전트를 병렬로 실행할 때	O git worktree

---

3. Git Worktree 기본 사용법 및 자주 쓰는 커맨드

3-1. 새 브랜치로 Worktree 생성

# git worktree add <경로> -b <새 브랜치명>
git worktree add ../my-project-feature -b feature/new-dashboard

# 결과
# ../my-project-feature/ 폴더가 생성되고
# feature/new-dashboard 브랜치가 체크아웃된 상태로 시작

 

3-2. 기존 브랜치로 Worktree 생성

# git worktree add <경로> <기존 브랜치명>
git worktree add ../my-project-hotfix hotfix/login-bug

# 이미 존재하는 hotfix/login-bug 브랜치를
# ../my-project-hotfix 폴더에 체크아웃

 

3-3. 현재 Worktree 목록 확인

git worktree list

# 출력 예시
# /Users/user/my-project           abc1234 [main]
# /Users/user/my-project-feature   def5678 [feature/new-dashboard]
# /Users/user/my-project-hotfix    ghi9012 [hotfix/login-bug]

 

3-4. Worktree 삭제

# Worktree 제거 (브랜치는 유지)
git worktree remove ../my-project-hotfix

# 브랜치도 함께 삭제
git worktree remove ../my-project-hotfix
git branch -d hotfix/login-bug

# 이미 삭제된 디렉토리의 worktree 정보 정리
git worktree prune

 

3-5. 자주 쓰는 커맨드 한눈에 보기

커맨드	설명
git worktree add <경로> -b <브랜치>	새 브랜치로 worktree 생성
git worktree add <경로> <브랜치>	기존 브랜치로 worktree 생성
git worktree list	전체 worktree 목록 확인
git worktree remove <경로>	worktree 제거
git worktree prune	삭제된 디렉토리 참조 정리
git worktree move <기존경로> <새경로>	worktree 위치 이동
git worktree lock <경로>	worktree 실수로 삭제 방지

---

4. 브랜치 병렬 작업 실전 활용

4-1. 기능 개발 + 긴급 버그 수정 동시 진행

가장 흔하게 활용하는 시나리오입니다.

# 상황: feature/user-profile 작업 중 긴급 버그 리포트 접수

# 1. 긴급 버그용 worktree 생성 (기존 작업 그대로 유지)
git worktree add ../my-project-hotfix -b hotfix/payment-error

# 2. 버그 수정 디렉토리로 이동
cd ../my-project-hotfix

# 3. 버그 수정 작업
# ...

# 4. 커밋 및 푸시
git add .
git commit -m "fix: 결제 오류 수정"
git push origin hotfix/payment-error

# 5. 원래 작업하던 기능 개발 디렉토리로 복귀
cd ../my-project
# → stash 없이 feature/user-profile 작업 그대로 유지되어 있음 O

 

4-2. 여러 기능을 병렬로 개발

# 3개의 기능을 동시에 병렬 개발하는 경우
git worktree add ../project-auth    -b feature/auth-refactor
git worktree add ../project-search  -b feature/search-filter
git worktree add ../project-payment -b feature/payment-v2

# 각 디렉토리에서 독립적으로 개발 서버 실행
cd ../project-auth    && npm run dev -- --port 3001
cd ../project-search  && npm run dev -- --port 3002
cd ../project-payment && npm run dev -- --port 3003

 

4-3. 폴더 구조 권장 방식

Worktree 디렉토리를 프로젝트 상위에 모아두는 방식을 권장합니다.

# 권장 구조
projects/
├── my-project/          ← 메인 저장소 (main 브랜치)
│   └── .git/            ← 공유 Git 데이터베이스
├── my-project-auth/     ← feature/auth worktree
├── my-project-search/   ← feature/search worktree
└── my-project-hotfix/   ← hotfix worktree

.gitignore에 worktree 폴더가 잡히지 않도록 주의가 필요합니다.

# .gitignore
# worktree 내부에 생성되는 .claude/worktrees/ 경로 무시
.claude/worktrees/

---

5. Claude Code + Worktree 연동하기

Git Worktree의 진가는 Claude Code와 함께 사용할 때 발휘됩니다.

기존에는 Claude Code가 작업 중에 브랜치를 전환하면 컨텍스트가 초기화되는 문제가 있었습니다.
Worktree를 활용하면 각 디렉토리에서 독립적인 Claude Code 세션을 유지할 수 있습니다.

5-1. --worktree 플래그로 자동 생성

Claude Code v2.1.49 이상에서는 --worktree 플래그를 지원합니다.

# Claude Code가 자동으로 worktree 생성 + 세션 시작
claude --worktree feature-auth

# 축약형
claude -w feature-auth

# 이름 없이 실행하면 자동으로 랜덤 이름 생성
claude --worktree

위 명령어를 실행하면 Claude Code가 자동으로 아래 작업을 처리합니다.

1. .claude/worktrees/feature-auth/ 경로에 worktree 생성
2. feature-auth 브랜치 생성 및 체크아웃
3. 해당 디렉토리에서 Claude Code 세션 시작

 

5-2. 터미널 2개로 병렬 Claude Code 세션 실행

# 터미널 1 — 기능 개발
cd my-project
claude -w feature/new-dashboard

# 터미널 2 — 버그 수정 (동시에 실행)
cd my-project
claude -w bugfix/login-error

# 두 세션이 완전히 독립적으로 동작
# → 서로의 파일 변경에 영향 없음 
# → 각각 독립적인 컨텍스트 유지

 

5-3. 세션 종료 시 자동 정리

Claude Code 세션을 종료하면 변경 여부에 따라 자동으로 처리됩니다.

변경사항 없음 → worktree와 브랜치 자동 삭제
변경사항 있음 → "worktree를 유지할까요?" 프롬프트 표시
  → 유지: 디렉토리와 브랜치 보존 (나중에 재개 가능)
  → 삭제: 디렉토리와 브랜치 모두 삭제

 

5-4. .claude/commands/와 함께 활용하기

Worktree 생성과 Claude Code 세션 시작을 커스텀 슬래시 커맨드로 자동화할 수 있습니다.

# .claude/commands/git/worktree.md

## /git:worktree - Worktree 생성 및 작업 시작

$ARGUMENTS 이름으로 새 worktree를 생성하고 작업을 시작합니다.

## 실행 순서

1. `git worktree add ../{프로젝트명}-$ARGUMENTS -b feature/$ARGUMENTS` 실행
2. 해당 디렉토리로 이동
3. `npm install` 실행 (의존성 설치)
4. 작업 준비 완료 메시지 출력

# 사용법
/git:worktree new-dashboard
# → ../my-project-new-dashboard 생성
# → feature/new-dashboard 브랜치 체크아웃
# → npm install 자동 실행

---

6. 공부하면서 생겼던 의문점

Q. Worktree를 생성할 때 npm install 매번 다시 해야 하나요?

네, 해야 합니다. node_modules 는 워킹 디렉토리에 속하기 때문에 worktree마다 독립적으로 존재합니다.
새 worktree를 생성하면 반드시 해당 디렉토리에서 의존성을 다시 설치해야 합니다.

git worktree add ../my-project-feature -b feature/new-dashboard
cd ../my-project-feature
npm install  # ← 반드시 실행 필요

---

Q. 같은 브랜치를 두 개의 Worktree에서 동시에 열 수 있나요?

안됩니다. 하나의 브랜치는 하나의 worktree에서만 체크아웃할 수 있습니다.
같은 브랜치를 두 곳에서 동시에 열려고 하면 아래 에러가 발생합니다.

fatal: 'feature/auth' is already checked out at '/Users/user/my-project-auth'

---

Q. Worktree와 일반 저장소 clone의 차이가 뭔가요?

구분	git clone	git worktree
.git 폴더	각각 독립적으로 생성	하나를 공유
디스크 사용량	많음 (전체 Git 이력 복제)	적음 (워킹 파일만 추가)
브랜치 공유	각자 독립적	모두 같은 저장소 브랜치 공유
권장 상황	완전히 독립적인 작업	같은 저장소에서 병렬 작업

---

Q. Worktree에서 작업한 내용을 main에 병합하는 방법은 동일한가요?

동일합니다. 각 worktree는 독립적인 브랜치를 가지고 있으므로,
작업 완료 후 PR을 열거나 git merge를 사용하는 방식이 일반 브랜치 작업과 동일합니다.

# worktree에서 작업 완료 후
cd ../my-project-feature
git add .
git commit -m "feat: 새 대시보드 추가"
git push origin feature/new-dashboard

# GitHub에서 PR 생성 → 리뷰 → merge
# merge 후 worktree 정리
cd ../my-project
git worktree remove ../my-project-feature
git branch -d feature/new-dashboard

---

Q. "git worktree prune"을 꼭 실행해야 하나요? 안 하면 참조가 영원히 남아있나요?

결론부터 말씀드리면, 반드시 수동으로 실행할 필요는 없습니다.
하지만 상황에 따라 직접 실행해줘야 하는 경우가 있습니다.

prune이 필요한 상황 vs 불필요한 상황

삭제 방식	prune 필요 여부	이유
git worktree remove 사용	X 불필요	Git이 참조까지 자동으로 정리함
rm -rf로 디렉토리 직접 삭제	O 필요	디렉토리만 삭제되고 Git 내부 참조는 남음

 

prune을 안 하면 어떻게 되나요?

rm -rf 로 worktree 디렉토리를 직접 삭제했을 때 prune을 실행하지 않으면,
.git/worktrees/ 폴더 안에 해당 worktree의 메타데이터 파일들이 그대로 남아있게 됩니다.

.git/
└── worktrees/
    └── feature-auth/     ← 디렉토리는 삭제됐지만 이 참조가 남아있음
        ├── HEAD
        ├── commondir
        └── gitdir

이 상태에서 git worktree list를 실행하면 존재하지 않는 worktree가 계속 목록에 표시됩니다.
실제 개발에 큰 지장은 없지만 목록이 지저분해지고 브랜치 충돌 감지가 오작동할 수 있습니다.

 

그럼 참조가 영원히 남아있나요?

Git 공식 문서에 따르면, 시간이 지나면 자동으로 정리됩니다.
Git은 내부적으로 worktree 참조에 만료 시간을 두고 있어서, 일정 기간이 지난 stale 참조는 git gc(가비지 컬렉션) 실행 시 자동으로 제거됩니다.

하지만 언제 자동 정리될지 보장이 없기 때문에 직접 삭제했다면 명시적으로 prune을 실행하는 것이 좋습니다.

 

prune 사용법

# 현재 stale 참조 확인 (실제로 삭제하지 않고 미리 보기)
git worktree prune --dry-run -v

# stale 참조 정리 실행
git worktree prune

# 정리 결과 확인
git worktree list

 

7. 참고 자료

• Git 공식 문서 - git worktree: https://git-scm.com/docs/git-worktree
• Claude Code 공식 문서 - Common Workflows: https://code.claude.com/docs/en/common-workflows
• Claude Code --worktree 플래그 문서: https://code.claude.com/docs/en/slash-commands