Claude Worktree 완전 가이드

서론

Claude Code로 복잡한 작업을 처리할 때, 이런 곤란한 상황을 겪어본 적이 있을 것입니다. 세 가지 독립적인 작업을 처리해야 하는데, 같은 디렉토리에서 여러 Claude 인스턴스를 실행하면 코드가 충돌합니다. 한 Agent가 파일을 수정하는 동안 다른 Agent도 같은 파일을 건드리고, 마지막에 병합할 때 엉망이 됩니다.

2025년 2월, Anthropic은 --worktree 명령을 출시하여 이 상황을 완전히 바꾸었습니다. 이제 세 개의 터미널에서 각각 claude -w feature-1, claude -w feature-2, claude -w bugfix-1을 실행할 수 있으며, 세 Agent가 각자 격리된 환경에서 작업하여 서로 간섭하지 않습니다.

Worktree 이해하기

여러분이 건축가이고, 동시에 세 개의 다른 방을 설계하고 있다고 상상해보십시오. 전통적인 방식은 같은 도면에 그리는 것인데, 수정을 반복하다 보면 쉽게 엉망이 됩니다. Worktree의 방식은 세 장의 독립된 도면을 제공하여 각 도면을 하나의 방 설계에 전용하고, 마지막에 주 도면에 통합하는 것입니다.

기술적으로 말하면, Worktree는 Git의 네이티브 기능입니다. Claude Code의 --worktree 명령은 이 기능을 더 간단하고 사용하기 쉽게 래핑했습니다. 하나의 명령으로 격리 환경 생성, Claude 인스턴스 시작, 완료 후 자동 정리까지 수행합니다.

왜 직접 여러 번 Clone하지 않는가

이런 의문이 들 수 있습니다. 왜 코드를 여러 번 clone하지 않는가?

Worktree는 동일한 .git 데이터베이스를 공유하며, 모든 커밋 히스토리와 브랜치 정보가 공유됩니다. 이는 하나의 worktree에서 생성한 commit이 다른 worktree에서 즉시 보인다는 의미입니다.

언제 Worktree를 사용해야 하는가

작업을 시작하기 전에, 먼저 해당 작업이 worktree에 적합한지 판단해보십시오.

경험 법칙: 작업에 30분 이상이 필요하면 worktree 사용을 고려하십시오. 짧은 작업에 worktree를 사용하면 오히려 시간 낭비입니다. 환경 생성, 의존성 설치, 최종 병합까지 합치면 작업 자체보다 오래 걸릴 수 있습니다. 하지만 깊은 작업이 필요한 작업에서는 worktree의 격리성이 매우 유용합니다.

전제 조건

Worktree를 사용하기 전에 다음 조건을 충족하는지 확인하십시오.

완전한 워크플로: 생성부터 정리까지

아래에서 실제 개발 순서에 따라, Worktree 생성부터 최종 정리까지의 완전한 흐름을 살펴보겠습니다.

1단계: Worktree 생성

원격 기본 브랜치에서 생성

-w 또는 --worktree 매개변수로 Claude를 시작합니다.

# "feature-auth"라는 이름의 worktree를 생성하고 Claude 시작
claude -w feature-auth

# 랜덤 이름 자동 생성 (예: "bright-running-fox")
claude -w

이 명령은 실제로 네 가지 작업을 수행합니다.

1. <repo>/.claude/worktrees/feature-auth/에 새 작업 디렉토리 생성
2. worktree-feature-auth라는 새 브랜치 생성
3. 원격 기본 브랜치(예: origin/main 또는 origin/master)에서 코드 체크아웃 — 주의: 현재 있는 브랜치가 아닙니다
4. 새 디렉토리에서 Claude Code 시작

모든 worktree는 .claude/worktrees/ 디렉토리 아래에 있습니다.

your-project/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/      ← 첫 번째 worktree
│       ├── bugfix-123/        ← 두 번째 worktree
│       └── refactor-api/      ← 세 번째 worktree
├── src/
└── package.json

이 경로를 .gitignore에 추가하는 것을 권장합니다.

# .gitignore
.claude/worktrees/

현재/특정 브랜치에서 생성

-w는 항상 원격 기본 브랜치에서 체크아웃하며, 현재 기본 브랜치 지정은 지원하지 않습니다. 현재 브랜치(또는 특정 브랜치)를 기반으로 worktree를 생성하려면 세 가지 방법이 있습니다.

방법 1: 수동 Git 생성

# 현재 HEAD 기반으로 worktree 생성
git worktree add -b my-feature .claude/worktrees/my-feature HEAD

# 또는 특정 브랜치 기반
git worktree add -b hotfix .claude/worktrees/hotfix origin/release-v2

# 해당 디렉토리에서 Claude 시작
cd .claude/worktrees/my-feature && claude

이 방법은 완전한 제어권을 제공합니다. 임의의 브랜치, 임의의 commit을 기반으로 worktree를 생성할 수 있으며, 작업 디렉토리가 처음부터 올바른 브랜치에 있습니다. 공식 문서에서도 "더 많은 브랜치 및 위치 제어가 필요한 경우, Git으로 직접 worktree를 생성한 다음 해당 디렉토리에서 Claude를 실행하세요"라고 권장합니다.

방법 2: 대화 중 생성 (권장)

기존 Claude 세션에서 직접 Claude에게 worktree 생성을 요청합니다.

> 从当前分支开启一个worktree
> start a worktree

-w 명령과 달리, 대화 중에 생성하는 worktree는 현재 브랜치를 자동으로 기반으로 하며, 원격 기본 브랜치가 아닙니다. Claude가 자동으로 worktree 생성을 완료하고 전환하며, 전체 과정에서 수동으로 Git 명령을 조작할 필요가 없습니다. 이미 특정 feature 브랜치에서 작업 중이라면, 한 마디로 현재 브랜치 기반의 격리 환경을 만들 수 있는 가장 편리한 방법입니다.

방법 3: -w로 먼저 생성 후, 세션에서 브랜치 전환

먼저 claude -w로 worktree를 생성한 후, 세션에 진입하여 Claude에게 대상 브랜치로 전환을 요청합니다. 이 방법의 단점은 먼저 원격 기본 브랜치를 가져온 후 전환한다는 것입니다. 한 단계가 더 필요하며, 앞의 두 방법보다 깔끔하지 않습니다. 또한 대상 브랜치가 다른 worktree에서 이미 사용 중이면 브랜치 충돌이 발생합니다.

스크린샷에서 보듯이, Claude가 브랜치 충돌을 감지하고 두 가지 선택지를 제공합니다. 메인 디렉토리로 돌아가서 작업하거나, 대상 브랜치 기반으로 새 작업 브랜치를 생성합니다. 최종적으로는 동작하지만, 전체 과정이 방법 1과 방법 2보다 직접적이지 않습니다.

고급: Makefile로 원클릭 명령 래핑

현재 브랜치에서 worktree를 자주 생성해야 한다면, 프로젝트 루트 디렉토리의 Makefile에 단축 명령을 추가하여 생성 + 에디터 열기 + Claude 시작을 하나의 확정적인 파이프라인으로 연결할 수 있습니다.

# 현재 브랜치에서 worktree를 생성하고 개발 환경 시작
# 사용법: make worktree name=my-feature
worktree:
	@if [ -z "$(name)" ]; then \
		echo "사용법: make worktree name=<worktree-name>"; \
		echo "예시: make worktree name=fix-login-bug"; \
		exit 1; \
	fi
	@echo "→ $$(git branch --show-current)에서 worktree 생성: $(name)"
	git worktree add -b $(name) .claude/worktrees/$(name) HEAD
	@echo "→ 환경 초기화"
	cd .claude/worktrees/$(name) && npm install
	@echo "→ Zed에서 열기"
	zed .claude/worktrees/$(name)
	@echo "→ Claude 시작"
	cd .claude/worktrees/$(name) && claude

사용법은 매우 간결합니다.

# 현재 브랜치 기반으로 worktree 생성, Zed로 열기, Claude 시작
make worktree name=fix-login-bug

# 여러 병렬 작업 추가 생성
make worktree name=feature-search
make worktree name=refactor-api

여러 개의 Git/cd/claude 명령을 수동으로 입력하는 것에 비해, make worktree name=xxx 한 줄이면 되며, 매번 실행되는 과정이 완전히 동일합니다. 특정 단계를 잊거나 경로를 잘못 입력하는 일이 없습니다. 주의할 점은, Makefile이 네이티브 git worktree add를 사용하기 때문에 Claude Code의 WorktreeCreate Hook이 트리거되지 않습니다(이 Hook은 claude -w 또는 대화 중 worktree 생성 시에만 동작합니다). 따라서 환경 초기화 단계(의존성 설치, .env 복사 등)는 위 예시의 npm install처럼 Makefile에 직접 작성해야 합니다.

2단계: 환경 초기화

Worktree 생성이 완료되면, 첫 번째로 할 일은 개발 환경을 초기화하는 것입니다. 각 새 worktree는 독립된 디렉토리이므로, node_modules, 가상 환경, .env 파일 등은 자동으로 가져오지 않습니다.

Claude Code는 WorktreeCreate Hook을 제공하여 환경 설정을 자동화합니다.

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "npm install && cp ../.env .env"
      }
    ]
  }
}

이렇게 하면 worktree를 생성할 때마다 의존성이 자동으로 설치되고, 환경 변수 파일이 자동으로 복사됩니다. 일반적인 초기화 단계는 다음과 같습니다.

Hook을 설정하지 않았다면, 각 worktree 세션을 시작할 때 /init을 실행하여 Claude가 현재 작업 디렉토리의 컨텍스트를 올바르게 이해하고, 프로젝트 구조와 CLAUDE.md 설정을 다시 읽도록 하는 것이 좋습니다.

3단계: 커밋과 병합

환경이 준비되고 개발이 완료되면, 다음 단계는 변경 사항을 대상 브랜치에 병합하는 것입니다.

main 브랜치로 병합

가장 일반적인 경우로, worktree가 origin/main에서 분기되었고 변경 사항도 main에 병합해야 합니다. Worktree의 Claude 세션에서 직접 말하면 됩니다.

> 모든 변경 사항을 커밋하고, 원격에 푸시한 다음, main으로 PR을 생성해줘

Claude가 자동으로 commit → push → gh pr create의 전체 과정을 완료합니다.

feature 브랜치로 병합

feature-x 브랜치에서 개발하고 있다면, worktree의 변경 사항은 main이 아닌 feature-x로 병합해야 합니다.

> 변경 사항을 커밋하고 푸시한 다음, feature-x 브랜치로 PR을 생성해줘

Claude가 gh pr create --base feature-x를 실행하여 feature 브랜치를 대상으로 하는 PR을 직접 생성합니다.

또한 worktree 세션을 종료한 후(worktree 유지를 선택), 메인 디렉토리로 돌아가서 Claude를 시작할 수도 있습니다.

> worktree-my-task 브랜치의 변경 사항을 현재 브랜치에 병합해줘

worktree의 일부 commit이 필요 없다면, 선택적으로 cherry-pick할 수 있습니다.

> worktree-my-task 브랜치의 커밋 히스토리를 확인하고, 인증 모듈 관련 커밋만 현재 브랜치에 cherry-pick해줘

팁: 모든 worktree는 동일한 .git 데이터베이스를 공유하므로, worktree에서 생성한 commit은 메인 디렉토리에서 즉시 볼 수 있으며, 추가적인 push/pull 작업이 필요 없습니다.

4단계: 종료와 정리

코드 병합이 완료되면, worktree 세션을 종료할 수 있습니다.

worktree 세션을 종료할 때, Claude는 상황에 따라 자동으로 처리합니다.

유지된 worktree는 계속 존재하므로, 나중에 작업을 이어갈 수 있습니다.

WorktreeRemove Hook을 설정하여 정리를 자동화할 수도 있습니다.

{
  "hooks": {
    "WorktreeRemove": [
      {
        "command": "echo 'Worktree cleaned up'"
      }
    ]
  }
}

수동 관리 명령

수동으로 worktree를 관리해야 한다면, 표준 Git 명령을 사용할 수 있습니다.

# 모든 worktree 나열
git worktree list

# 특정 worktree 수동 삭제
git worktree remove .claude/worktrees/feature-auth

# 오래된 worktree 참조 정리
git worktree prune

주의: worktree 디렉토리를 직접 rm -rf로 삭제하지 마십시오. 올바른 방법은 git worktree remove를 사용하는 것이며, 이미 잘못 삭제했다면 git worktree prune을 실행하여 남은 참조를 정리하십시오.

병렬 개발 패턴

기본 워크플로를 숙지한 후, worktree를 활용하여 병렬 개발을 실현하는 방법을 살펴보겠습니다.

다중 터미널 병렬

가장 일반적인 사용법은 여러 터미널 탭에서 동시에 실행하는 것입니다.

# 터미널 1: 사용자 인증 기능 처리
claude -w feature-auth

# 터미널 2: 결제 버그 수정
claude -w bugfix-payment

# 터미널 3: API 모듈 리팩토링
claude -w refactor-api

각 Claude 인스턴스는 자신의 worktree에서 작업하며, 수정 사항이 서로 영향을 미치지 않습니다. 다음과 같이 할 수 있습니다.

• 한 터미널에서 Claude에게 새 기능 개발을 맡기기
• 다른 터미널에서 Claude에게 버그 수정을 맡기기
• 세 번째 터미널에서 직접 코드 리뷰 진행하기

경쟁적 구현

효율적인 사용법 중 하나는 여러 Agent가 동일한 기능을 독립적으로 구현하게 하는 것입니다.

# 세 개의 터미널에서 각각 실행
claude -w feature-search-v1
claude -w feature-search-v2
claude -w feature-search-v3

동일한 요구사항 설명을 제공하고, 각자 구현하게 합니다. 마지막에 세 가지 방안을 비교하고 가장 좋은 것을 병합합니다. 이는 LLM의 비결정성을 활용하는 것입니다. 동일한 입력이 다른 출력을 생성할 수 있으며, 때로는 두 번째 버전이 더 나을 수 있습니다.

UI 디자인 탐색도 이 패턴에 매우 적합합니다. 애플리케이션의 인터페이스를 재설계하고 싶지만 어떤 스타일이 더 좋을지 확실하지 않다면:

# 세 Agent에게 각각 다른 스타일을 구현하게 하기
claude -w ui-minimal    # 미니멀 스타일
claude -w ui-colorful   # 선명한 배색
claude -w ui-glassmorphism  # 글래스모피즘 스타일

완료 후 세 버전의 개발 서버를 동시에 실행하고(다른 포트에서), 나란히 비교하여 가장 만족스러운 방안을 메인 브랜치에 병합합니다. 전통적인 "하나 수정하고, 결과 확인하고, 불만족이면 다시 수정하는" 프로세스보다 훨씬 효율적입니다.

Subagent 격리

Worktree는 메인 Claude 인스턴스뿐만 아니라 Subagent에도 적용할 수 있습니다. 커스텀 Subagent의 frontmatter에 isolation: worktree를 추가합니다.

---
name: code-migrator
description: Handles large-scale code migrations. Use for batch refactoring.
tools: Read, Write, Edit, Bash, Grep, Glob
isolation: worktree
---

You are a code migration specialist...

대화 중에 Claude에게 직접 말할 수도 있습니다.

> 使用 worktree 来隔离你的 agents
> use worktrees for your agents

Subagent가 worktree 격리로 설정되면:

메인 Agent (메인 디렉토리)
│
├── Migration Agent 1 시작 ──→ worktree-migration-1/
│   └── src/auth/ 디렉토리 처리
│
├── Migration Agent 2 시작 ──→ worktree-migration-2/
│   └── src/api/ 디렉토리 처리
│
└── Migration Agent 3 시작 ──→ worktree-migration-3/
    └── src/utils/ 디렉토리 처리

각 Subagent가 자신의 worktree에서 독립적으로 작업하며, 서로 간섭하지 않습니다. 완료 후 커밋되지 않은 변경 사항이 없으면 worktree가 자동으로 정리됩니다.

Tmux 및 IDE와 결합

--tmux 매개변수와 함께 사용하면 새 Tmux 세션에서 자동으로 시작되며, 터미널을 닫아도 Claude가 백그라운드에서 계속 실행됩니다.

claude -w feature-auth --tmux

VS Code 또는 Cursor를 사용한다면, 소스 컨트롤 패널이 모든 worktree를 자동으로 인식합니다. 메인 저장소는 하나의 repo로 표시되고, 각 worktree는 독립된 repo로 표시되어 IDE에서 직접 전환, 커밋, 푸시할 수 있습니다. Worktree는 Ralph 루프와도 결합할 수 있으며, 각 Ralph 루프가 자신의 worktree에서 실행되어 루프가 실패하더라도 메인 브랜치에 영향을 미치지 않습니다.

주의사항 및 모범 사례

흔한 함정

1. 브랜치 출처 혼동: -w로 생성한 worktree는 원격 기본 브랜치에서 체크아웃되며, 현재 있는 브랜치가 아닙니다. feature-x 브랜치에서 claude -w my-task를 실행하면, 새 worktree의 코드는 origin/main에서 오며 feature-x의 변경 사항을 포함하지 않습니다. 현재 브랜치 기반으로 작업하려면 현재/특정 브랜치에서 생성을 참고하십시오.
2. 커밋되지 않은 변경은 가져오지 않음: worktree 생성 시, 메인 디렉토리에서 스테이징되지 않았거나 커밋되지 않은 수정 사항은 새 worktree에 나타나지 않습니다. Worktree는 commit 히스토리를 기반으로만 생성되므로, 중요한 변경 사항이 커밋되었는지 확인하십시오.
3. 같은 브랜치를 여러 Worktree에서 사용할 수 없음: Git은 두 worktree가 동시에 같은 브랜치를 체크아웃하는 것을 허용하지 않습니다. 메인 디렉토리에서 이미 feature-x 브랜치에 있다면, worktree에서도 feature-x를 체크아웃하려 하면 오류가 발생합니다. 각 worktree는 서로 다른 브랜치에 있어야 합니다.
4. 환경 재초기화 필요: 각 새 worktree에는 node_modules 등 런타임 의존성이 포함되지 않으므로, WorktreeCreate Hook을 설정하여 자동화하는 것을 권장합니다(2단계: 환경 초기화 참고).

사용 권장 사항

욕심내지 마십시오. 기술적으로는 많은 worktree를 열 수 있지만, 각 Claude 인스턴스는 API 할당량을 소모하고, 너무 많은 병렬 작업은 추적하기 어려우며, 최종 병합 시 충돌도 더 복잡해집니다.

명명 규칙: 좋은 명명 습관을 들여 후속 관리를 편리하게 하십시오.

# 좋은 명명
claude -w feature-user-auth
claude -w bugfix-payment-123
claude -w refactor-api-v2

# 좋지 않은 명명
claude -w test
claude -w temp
claude -w 1

비 Git 버전 관리

SVN, Perforce 또는 Mercurial을 사용한다면, WorktreeCreate와 WorktreeRemove Hook을 설정하여 유사한 격리 효과를 구현할 수 있습니다. 이러한 Hook을 설정한 후, --worktree를 사용할 때 기본 Git 동작 대신 사용자 정의 명령이 호출됩니다.

마치며

Worktree는 Claude Code 팀이 매일 사용하는 기능으로, Boris Cherny는 이를 "1순위 생산성 팁"이라고 부릅니다. 핵심 가치는 간단합니다. 여러 Agent가 서로 간섭하지 않고 병렬로 작업할 수 있게 하는 것입니다.

시작은 간단합니다. 다음 명령만 실행하면 됩니다.

claude -w your-task-name

관련 읽을거리:

• Claude Subagent 완전 가이드 — Subagent와 Worktree의 조합 이해하기
• Ralph Wiggum 심층 분석 — AI 프로그래밍 효율을 높이는 또 다른 방법
• Claude 시스템 아키텍처 완전 해설 — 전체 아키텍처에서 Worktree의 위치 이해하기

참고 자료:

• Claude Code 공식 문서 - Common Workflows
• Boris Cherny의 Worktree 발표 공지
• Git Worktree 공식 문서
• incident.io - Shipping faster with Claude Code and Git Worktrees
• Dev.to - Git worktree + Claude Code: My Secret to 10x Developer Productivity

영상 튜토리얼:

• I'm using claude --worktree for everything now — worktree 전체 워크플로 실전 데모
• Git Worktrees: The secret sauce to Claude Code! — 수동 worktree 생성 방법
• Native Worktrees Just Killed Traditional Claude Code Workflows — 네이티브 worktree 기능 상세 해설
• Claude Code Worktrees in 7 Minutes — 빠른 시작 튜토리얼, Subagent 사용법 포함
• Stop Using Claude Code on One Branch — 다중 worktree 병렬 개발의 장점