내가 Claude Code를 Git Worktrees에서 실행하는 이유 (그리고 여러분도 그래야 하는 이유)

Claude Code를 사용한 첫 한 달 동안, 저는 다른 모든 코딩 도구를 사용하던 방식 그대로 사용했습니다. 즉, 리포지토리(repo)의 루트 디렉토리에서 한 번에 하나의 세션만 실행하는 방식이었습니다. 작동은 했습니다. 하지만 Claude가 기능 구현의 중간 단계에 있을 때, 운영 환경(production)의 오타를 수정하기 위해 main 브랜치로 급히 넘어가야 할 때마다 저는 똑같은 벽에 부딪혔습니다. stash를 하고, checkout을 하고, 그 과정에서 Claude의 세션이 현재 어떤 브랜치에 있는지 혼란스러워하며 컨텍스트(context)를 잃고, 조용히 욕설을 내뱉는 상황 말입니다.

해결책은 2015년부터 도구 상자에 있었지만 제가 한 번도 사용해 본 적 없는 Git 기능인 git worktree였습니다.

git worktree가 실제로 하는 일

worktree는 동일한 .git 폴더에 연결된 두 번째(세 번째, 열 번째) 작업 디렉토리(working directory)입니다. 디렉토리는 다르지만, 체크아웃된 브랜치도 다르고, 리포지토리 히스토리(history)는 동일합니다. 디스크 사용량은 최소화됩니다. 작업 파일(working files)만 복제될 뿐, 오브젝트 데이터베이스(object database)는 복제되지 않기 때문입니다.

# 메인 리포지토리 내부에서
git worktree add ../myrepo-hotfix main
git worktree add ../myrepo-feature-x -b feature/x

이제 각각 자신의 브랜치를 가진, 완전히 사용 가능한 세 개의 형제 디렉토리를 갖게 됩니다.

이것이 Claude Code에 중요한 이유

worktree를 갖게 되면 워크플로우(workflow)는 명확해집니다: Claude 세션당 하나의 worktree를 사용하는 것입니다.

mkdir -p ~/work/myrepo-worktrees
cd ~/work/myrepo
git worktree add ../myrepo-worktrees/feat-auth -b feat/auth
git worktree add ../myrepo-worktrees/feat-billing -b feat/billing
git worktree add ../myrepo-worktrees/hotfix-prod -b hotfix/prod

# 이제 세 개의 터미널에서 세 개의 Claude 세션을 실행합니다
cd ~/work/myrepo-worktrees/feat-auth && claude
cd ~/work/myrepo-worktrees/feat-billing && claude
cd ~/work/myrepo-worktrees/hotfix-prod && claude

각 Claude 세션은 서로 다른 디렉토리에 뿌리를 두고, 서로 다른 브랜치에서 자신만의 파일 컨텍스트(file context)를 가집니다. 이들은 서로의 편집 내용을 침범할 수 없습니다. 각 worktree가 자신의 브랜치를 소유하기 때문에 "branch is already checked out at..." 에러도 사라집니다. 그리고 한 에이전트(agent)가 작업을 마치면, 브랜치 관련 복잡한 조작 없이 일반적인 git merge를 수행하면 됩니다.

저에게 있어 이 방식은 "한 번에 하나의 기능"을 개발하던 것을 "하루 종일 세 개의 기능을 병렬로" 개발하는 것으로 바꾸어 놓았으며, 그 대가로 지불한 것은 고작 200 MB의 중복된 node_modules 뿐이었습니다. 이 방식이 완벽하게 작동하게 만든 tmux 설정은 다음과 같습니다. 저는 세 개의 세션을 하나의 tmux 윈도우로 묶어 세 개를 한눈에 볼 수 있게 합니다:

tmux new-session -d -s claude-pool
tmux send-keys -t claude-pool 'cd ~/work/myrepo-worktrees/feat-auth && claude' C-m
tmux split-window -h -t claude-pool
tmux send-keys -t claude-pool 'cd ~/work/myrepo-worktrees/feat-billing && claude' C-m
tmux split-window -v -t claude-pool
tmux send-keys -t claude-pool 'cd ~/work/myrepo-worktrees/hotfix-prod && claude' C-m
tmux attach -t claude-pool

세 개의 창, 세 개의 에이전트(agent), 컨텍스트 충돌 제로.

주의사항

• node_modules: 각 워크트리(worktree)마다 별도의 폴더가 필요합니다. 디스크 용량을 감수하거나, 공유 저장소(shared store)를 사용하는 pnpm을 사용하세요.
• .env 파일: 이 파일들은 gitignore 되어 있으므로 새로운 워크트리로 따라오지 않습니다. 심볼릭 링크(Symlink)를 걸거나 복사하세요.
• 훅(Hooks): git 훅은 워크트리 간에 공유되는 .git/hooks에 위치합니다. 한 번 테스트하면 모든 곳에서 실행됩니다.
• 워크트리 삭제: 절대 디렉토리를 rm -rf로 삭제하지 마세요. Git의 장부 기록이 일관되게 유지되도록 git worktree remove <path>를 사용해야 합니다. 그렇지 않으면 나중에 워크트리가 dirty하다는 오류를 보게 될 것입니다.

과한 경우라면
만약 한 번에 하나의 에이전트만 실행하고, 핫픽스(hotfix)를 위해 컨텍스트 스위칭(context-switching)을 할 일이 없다면 일반적인 브랜치(branch)만으로도 충분합니다. 워크트리는 "병렬성 × 중단율"이 높을 때 효과를 발휘하는데, AI 에이전트를 사용할 때는 이 수치가 거의 항상 높습니다.

결국 저는 모든 git worktree 명령어, 모든 일반적인 오류, 그리고 Cursor / Codex / OpenCode를 위한 설정법까지 gitworktree.org에 정리해 두었습니다. 그중에서도 Claude Code + worktree 가이드를 가장 자주 찾아보게 됩니다. 만약 여러분만의 AI 에이전트용 워크트리 팁이 있다면 댓글로 남겨주세요. 항상 다음 10%의 속도 향상을 위해 열려 있습니다.