Claude Code 워크트리(Worktree) 완전 가이드 2026

Claude Code에서 워크트리를 사용하면 같은 레포지토리를 여러 디렉토리에 동시에 체크아웃해서 서로 다른 브랜치를 병렬로 작업할 수 있습니다. 에이전트 두 개가 각자 다른 기능을 개발하거나, 한쪽에서 버그를 고치면서 다른 쪽에서 새 기능을 추가하는 것이 가능합니다.

워크트리 기초

왜 워크트리인가?

기존 방식:

# 작업 중단 → 스태시 → 브랜치 전환 → 작업 → 다시 전환
git stash
git checkout feature/auth
# ... 작업 ...
git checkout main
git stash pop

워크트리 방식:

# 브랜치별 독립 디렉토리 — 동시에 열어서 동시에 작업
project/          # main 브랜치
project-auth/     # feature/auth 브랜치
project-bugfix/   # hotfix/login 브랜치

컨텍스트 전환이 없고, 각 워크트리가 독립적인 node_modules, .next, dist를 가집니다.

워크트리 생성

# 기본: 새 브랜치로 워크트리 생성
git worktree add ../project-auth feature/auth

# 기존 브랜치로 워크트리 생성
git worktree add ../project-bugfix hotfix/login-fix

# 목록 확인
git worktree list
# /Users/user/project          abc1234 [main]
# /Users/user/project-auth     def5678 [feature/auth]
# /Users/user/project-bugfix   ghi9012 [hotfix/login-fix]

Claude Code + 워크트리 병렬 개발

패턴 1: 병렬 기능 개발

터미널 두 개를 열어 동시에 Claude Code 실행:

# 터미널 1 — 인증 기능
cd ~/project-auth
claude
"JWT 인증 미들웨어 구현해줘.
accessToken 15분, refreshToken 7일 만료.
Redis 기반 토큰 블랙리스트 포함."

# 터미널 2 — 결제 기능 (동시에)
cd ~/project-payment
claude
"Stripe 결제 플로우 구현해줘.
checkout session 생성부터 webhook 처리까지.
실패 시 자동 재시도 3회."

두 에이전트가 서로의 변경사항에 영향을 주지 않고 독립적으로 실행됩니다.

패턴 2: 위험한 리팩토링 격리

큰 변경이 main을 깨뜨릴 것이 걱정될 때:

# 워크트리에서 실험
git worktree add ../project-refactor refactor/typescript-migration

cd ../project-refactor
claude
"JavaScript → TypeScript 마이그레이션 해줘.
any 타입 없이, 빌드 통과하는 수준까지.
실패하면 변경사항 롤백."

# main은 그대로 — 언제든 돌아올 수 있음
cd ../project
git status  # 깨끗함

패턴 3: 핫픽스 + 기능 개발 동시

프로덕션 버그가 터졌는데 기능 개발 중일 때:

# 기존 개발 워크트리 유지
# ../project-feature → feature/new-dashboard 계속 진행 중

# 핫픽스 워크트리 추가
git worktree add ../project-hotfix hotfix/critical-auth-bug

cd ../project-hotfix
claude
"프로덕션 인증 버그 긴급 수정해줘.
JWT 검증 시 algorithm 체크 누락 문제.
최소 변경으로 수정하고 테스트 추가해줘"

# 수정 후 main에 병합
git checkout main
git merge hotfix/critical-auth-bug
# 기능 개발 워크트리는 그대로

고급 워크트리 패턴

자동화 스크립트

#!/bin/bash
# new-feature.sh — 워크트리 + Claude Code 자동 시작

FEATURE_NAME=$1
BASE_BRANCH=${2:-main}

# 워크트리 생성
WORKTREE_PATH="../$(basename $(pwd))-${FEATURE_NAME}"
git worktree add "$WORKTREE_PATH" -b "feature/${FEATURE_NAME}" "$BASE_BRANCH"

# 의존성 설치
cd "$WORKTREE_PATH"
bun install

echo "워크트리 준비 완료: $WORKTREE_PATH"
echo "실행: cd $WORKTREE_PATH && claude"

사용:

./new-feature.sh user-dashboard main
cd ../project-user-dashboard && claude

워크트리 완료 후 정리

# 병합 후 워크트리 제거
git worktree remove ../project-auth

# 강제 제거 (변경사항 있어도)
git worktree remove --force ../project-auth

# 브래치도 함께 삭제
git branch -d feature/auth

# 오래된 워크트리 정리
git worktree prune

Claude Code 에이전트 격리 실행

SDK를 사용해 각 워크트리에 에이전트를 프로그래밍 방식으로 실행:

import subprocess
import os
from pathlib import Path

def run_agent_in_worktree(task: str, branch: str, base_path: str = "."):
    """워크트리를 생성하고 Claude Code 에이전트를 실행"""
    # 워크트리 경로 결정
    repo_name = Path(base_path).name
    worktree_path = f"../{repo_name}-{branch.replace('/', '-')}"
    
    # 워크트리 생성
    subprocess.run(
        ["git", "worktree", "add", worktree_path, "-b", branch],
        cwd=base_path,
        check=True
    )
    
    # Claude Code로 태스크 실행
    result = subprocess.run(
        ["claude", "-p", task],
        cwd=worktree_path,
        capture_output=True,
        text=True
    )
    
    return result.stdout, worktree_path

# 병렬로 여러 태스크 실행
import concurrent.futures

tasks = [
    ("인증 모듈 리팩토링 — JWT → OAuth2 마이그레이션", "refactor/oauth"),
    ("결제 모듈 테스트 커버리지 80%로 높여줘", "test/payment-coverage"),
    ("API 응답 캐싱 레이어 추가", "feat/response-cache"),
]

with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
    futures = {
        executor.submit(run_agent_in_worktree, task, branch): branch
        for task, branch in tasks
    }
    
    for future in concurrent.futures.as_completed(futures):
        branch = futures[future]
        output, path = future.result()
        print(f"✓ {branch}: {path}")

실측 성능 데이터

Claude Code 워크트리 병렬 개발 실제 결과:

Frequently Asked Questions

워크트리와 git stash의 차이는?

git stash는 현재 작업을 임시 저장하고 브랜치를 전환합니다. 한 번에 하나의 작업만 가능합니다. 워크트리는 여러 브랜치를 동시에 독립 디렉토리로 체크아웃해서 병렬 작업이 가능합니다. 빌드 결과물도 워크트리별로 분리됩니다.

워크트리마다 node_modules를 따로 설치해야 하나요?

네. 각 워크트리는 독립적인 파일시스템을 가지므로 bun install을 각각 실행해야 합니다. 단, pnpm을 사용하면 글로벌 패키지 캐시를 공유해 디스크 사용량을 줄일 수 있습니다.

Claude Code 에이전트가 워크트리 간 파일을 교차 수정할 수 있나요?

물리적으로는 가능하지만 권장하지 않습니다. 각 에이전트는 자신의 워크트리 안에서만 작업하도록 CLAUDE.md에 경계를 명시하거나, --allowed-paths로 제한하세요.

같은 파일을 두 워크트리에서 동시에 수정하면?

각 워크트리는 독립된 브랜치이므로 파일 수정이 충돌하지 않습니다. 병합 시 git이 충돌을 감지합니다. 작업 범위를 사전에 분리(모듈별, 레이어별)하면 병합 충돌을 0으로 줄일 수 있습니다.

관련 가이드: Claude Code 완전 가이드 한국어 · Claude Code 리팩토링 가이드 한국어 · Claude Code CI/CD 가이드 한국어

P1 Claude Code Power Prompts 300 — 병렬 에이전트 개발 및 워크트리 자동화 프롬프트 포함. 지금 확인 →