이번 글에서는 git worktree로 Claude Code 세션을 여러 개 동시에 돌리는 방법에 대해 살펴보고자 합니다.
git worktree는 하나의 저장소를 물리적으로 다른 디렉토리에 추가로 체크아웃해주는 기능입니다. 같은 repo를 여러 폴더에 펼쳐둔 뒤, 각 폴더에서 서로 다른 브랜치를 독립적으로 작업할 수 있습니다. Claude Code와 조합하면 main 브랜치에서 직접 코드 리뷰를 보는 동안 feature 브랜치에서 Claude가 구현을 이어가는 식의 병렬 워크플로가 가능해집니다.
1. git worktree 기본 명령어
기본이 되는 3개 명령어만 알아두면 됩니다.
git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix bugfix-123
git worktree list
git worktree remove ../project-feature-a
첫 번째 명령은 feature-a 브랜치를 새로 만들면서 ../project-feature-a 경로에 체크아웃합니다. 두 번째 명령은 이미 존재하는 bugfix-123 브랜치를 별도 경로에 체크아웃하는 방식입니다. 물리적으로 분리된 디렉토리이기 때문에 브랜치를 바꿀 때 stash나 임시 커밋을 만들지 않아도 됩니다.
한 가지 제약이 있습니다. 같은 브랜치를 두 worktree에서 동시에 체크아웃할 수는 없습니다. 하나를 정리한 뒤에야 다른 쪽에서 같은 브랜치를 열 수 있습니다.
2. Claude Code 내장 --worktree 플래그
최근 업데이트로 Claude Code에도 worktree 옵션이 정식으로 들어왔습니다. 가장 간단한 사용법은 다음과 같습니다.
claude --worktree feature-auth
# 짧은 별칭
claude -w feature-auth
이 명령을 실행하면 <repo>/.claude/worktrees/feature-auth/ 경로에 새 worktree가 생성되고, worktree-feature-auth라는 브랜치가 함께 만들어집니다. base는 origin/HEAD를 기준으로 하므로, 원격 기본 브랜치가 바뀌었다면 git remote set-head origin -a로 먼저 재동기화해두는 편이 안전합니다.
이름을 생략하면 bright-running-fox 같은 랜덤 별칭이 자동으로 붙습니다. 세션 종료 시 변경 사항이 없으면 자동으로 삭제되고, 변경이 있는 경우 유지할지 여부를 물어봅니다.
.claude/worktrees/ 디렉토리는 저장소에 들어갈 필요가 없으니 .gitignore에 추가해두시길 권장합니다.
.claude/worktrees/
3. .worktreeinclude로 환경 파일 자동 복사
각 worktree는 fresh checkout이기 때문에 .env나 config/secrets.json 같은 gitignored 파일은 따로 복사해야 합니다. 매번 수동으로 복사하면 번거롭습니다. 프로젝트 루트에 .worktreeinclude 파일을 두면 Claude Code가 worktree를 만들 때 자동으로 복사해줍니다.
# .worktreeinclude
.env
.env.local
config/secrets.json
문법은 .gitignore와 동일합니다. 여기에 명시된 gitignored 파일만 복사 대상이 됩니다. tracked 파일은 이미 체크아웃으로 들어가기 때문에 중복 복사는 일어나지 않습니다.
node_modules나 Python 가상환경은 복사보다 재설치가 더 깔끔합니다. 각 worktree에서 npm install이나 uv sync를 한 번 돌려두는 방식이 경험상 문제가 적습니다.
4. Subagent 단위의 worktree isolation
Claude Code SDK에는 서브에이전트별로 독립된 worktree를 띄워주는 옵션이 있습니다. .claude/agents/<name>.md 프론트매터에 isolation: worktree를 추가하면 됩니다.
---
name: migration-agent
isolation: worktree
---
이 옵션을 켜두면 서브에이전트가 부모 세션과 물리적으로 분리된 디렉토리에서 돌아가므로, 같은 파일을 동시에 건드려도 충돌하지 않습니다. 파일 5개씩 나눠 마이그레이션하는 작업을 5개 병렬로 돌리는 식의 활용이 가능합니다. 변경 사항이 없으면 종료 시 자동으로 정리됩니다.
참고로 isolation: "worktree"가 조용히 비활성화되고 main repo에서 실행되는 버그가 보고된 적이 있습니다(anthropics/claude-code#39886). 중요한 파일을 수정하는 서브에이전트라면 첫 실행 때 실제 worktree 경로에서 동작하는지 pwd로 한 번 확인해보는 편이 안전합니다.
5. tmux 조합으로 장시간 세션 유지
터미널 창을 닫으면 Claude Code 세션도 함께 사라지는 게 기본 동작입니다. 장시간 돌아가는 작업은 tmux 옵션과 조합하면 터미널을 닫아도 세션이 유지됩니다.
claude -w feature-auth --tmux
이 명령을 실행하면 해당 worktree에 묶인 tmux 세션이 만들어집니다. 창을 닫더라도 tmux 세션 자체는 백그라운드에 남아 있어, 나중에 다시 같은 worktree 경로로 이동한 뒤 claude --resume을 실행하면 세션 picker에서 이전 세션을 골라 이어갈 수 있습니다. worktree로 생성된 세션 재개에는 아직 불안정한 부분이 있으므로(anthropics/claude-code#27562), 중요한 작업은 중간에 커밋을 남겨두는 편이 안전합니다.
서브에이전트가 worktree를 만든 뒤 비정상 종료되면 .claude/worktrees/ 하위에 orphaned worktree가 남을 수 있습니다. 이런 orphaned worktree는 cleanupPeriodDays 옵션에 설정한 기간이 지나면 Claude Code 시작 시 자동으로 정리됩니다. 단, uncommitted 변경이나 untracked 파일, unpushed 커밋이 하나도 없는 경우에만 삭제되니 작업 중인 내용이 날아갈 걱정은 덜 해도 됩니다.
6. 데이터 사이언스 관점의 활용 예시
1인 개발이나 데이터 사이언스 환경에서 쓸 만한 패턴 몇 가지를 소개합니다.
모델 A/B 실험 병렬 실행
git worktree add ../exp-baseline baseline-v2
git worktree add ../exp-new-loss new-loss-fn
각 worktree에서 별도 Claude Code 세션을 띄우고 학습 스크립트를 돌립니다. 한 세션은 학습 로그를 지켜보며 하이퍼파라미터를 조정하고, 다른 세션은 평가 지표를 비교하는 식으로 병렬 진행이 가능합니다.
PR 리뷰 전용 worktree
git worktree add ../pr-review origin/feature-X
동료가 올린 PR을 로컬에서 실행하며 리뷰하고 싶을 때 유용합니다. main worktree에서 본인 작업을 중단하지 않아도 되고, PR 브랜치를 체크아웃하는 동안 로컬 변경 사항이 휘말리는 사고도 막을 수 있습니다.
Claude 작업 + 병렬 리뷰
feature 구현을 한쪽 worktree에서 Claude에게 맡겨두고, 다른 worktree에서 본인이 직접 PR 리뷰나 가벼운 버그 수정을 이어갑니다. Claude가 돌고 있는 디렉토리를 건드리지 않기 때문에 양쪽 모두 안정적으로 진행됩니다.
7. 주의사항 몇 가지
worktree 개수가 늘어나면 관리 포인트도 같이 늘어납니다. 몇 가지만 염두에 두면 됩니다.
- 끝난 worktree는
git worktree remove <path>로 정리하고, 수동 삭제로 꼬인 경우git worktree prune을 한 번 돌려준다. node_modules,venv,.next같은 의존성 디렉토리는 worktree마다 별도로 생성되므로 디스크 사용량이 배로 늘어난다.- 같은 브랜치를 두 worktree에서 동시에 체크아웃할 수 없다는 제약은 계속 유지된다.
- 장시간 돌아가는 Claude 세션이 여러 개 붙으면 토큰 비용도 그만큼 나간다. 필요 없어진 세션은
/clear후 종료하는 습관이 좋다.
마무리
정리하면 git worktree는 여러 브랜치를 독립된 디렉토리로 펼쳐 병렬 작업이 가능하게 만드는 기능이고, Claude Code의 --worktree 플래그와 .worktreeinclude 파일은 이 패턴을 조금 더 매끄럽게 만들어주는 도구입니다. 서브에이전트 isolation 옵션까지 조합하면 배치 작업도 충돌 없이 돌릴 수 있습니다.
지난 글에서 다룬 /loop 스케줄링과 함께 쓰면 한쪽 worktree에서 모니터링을 돌리고 다른 worktree에서 구현을 진행하는 식의 조합도 가능합니다. 혼자 작업하는 환경에서 처리량을 늘리는 방법을 찾고 있다면 worktree 기반 병렬 세션부터 검토해볼 만합니다.
Claude Code 관련 글 모음
- Claude Code /loop와 스케줄링 활용법
- 업데이트된 Claude Desktop의 Claude Code 둘러보기 - (3) 뷰 기능
- 업데이트된 Claude Desktop의 Claude Code 둘러보기 - (2) 프로젝트 관리
- 업데이트된 Claude Desktop의 Claude Code 둘러보기 - (1) 기본 UI와 설정
- Claude Code Ultrathink와 Thinking 레벨 활용법
참고
'AI > Claude' 카테고리의 다른 글
| [Claude] Claude Code Superpowers brainstorm 스킬 활용 및 설치 방법 (0) | 2026.05.07 |
|---|---|
| [Claude] Claude Code gstack /office-hours 스킬 활용 및 설치 방법 (1) | 2026.05.04 |
| [Claude] Claude Code /loop와 스케줄링 활용법 - 주기적 작업 자동화 정리 (2) | 2026.04.20 |
| [Claude] 업데이트된 Claude Desktop의 Claude Code 둘러보기 - (3) 뷰 기능 (2) | 2026.04.17 |
| [Claude] 업데이트된 Claude Desktop의 Claude Code 둘러보기 - (2) 프로젝트 관리 (0) | 2026.04.16 |
댓글