Claude Code를 git worktree에서 실행하려면 claude -w <이름>(긴 형태는 --worktree)으로 시작하면 됩니다. Claude Code는 저장소 루트에 .claude/worktrees/<이름>/을 만들고, 원격의 기본 브랜치에서 딴 worktree-<이름>이라는 새 브랜치를 거기에 체크아웃합니다. 그때부터 그 세션은 이 폴더 안의 파일만 수정할 수 있습니다. 다른 터미널에서 이름만 바꿔 같은 명령을 실행하면, 서로의 파일을 건드릴 수 없는 에이전트 두 개가 나란히 돌아갑니다. 함정은 worktree가 완전히 새 체크아웃이라는 점입니다. .env, node_modules, 그 밖에 git이 무시하는 파일은 직접 복사하거나 설치하기 전까지 없습니다. 제가 worktree에서 겪은 문제는 거의 전부 여기서 나왔습니다.
저는 평소에 에이전트를 여러 개 병렬로 돌리는데, worktree는 꽤 아프게 배운 끝에 쓰게 됐습니다. 이 글에서는 claude -w가 어떻게 동작하는지(2.1.328 버전에서 확인), .worktreeinclude는 무엇을 위한 것인지, node_modules는 어떻게 할지, tmux에서 세션을 어떻게 배치하는지, 그리고 지금도 그냥 git worktree add를 쓰는 때는 언제인지 정리합니다.
체크아웃 하나로는 병렬 에이전트가 안 되는 이유#
9월의 어느 날, 제가 만드는 마켓플레이스 앱의 같은 체크아웃에서 Claude Code 세션 다섯 개가 동시에 작업하고 있었고, 두 가지 일이 터졌습니다. 테스트 설정 파일을 고친 한 줄짜리 수정이 빌드 실패 네 번을 버텨 냈는데, 막상 커밋하려고 보니 사라져 있었습니다. git commit은 작업 트리가 깨끗하다고 했고, 파일에는 다른 세션이 쓴 내용이 들어 있었죠. 이런 식으로 사라진 수정은 git 어디에도 기록이 남지 않습니다. reflog에도 stash에도 없고, 수정 시각도 평범합니다. 같은 날, 작업 트리를 그대로 빌드하는 배포 스크립트가 다른 세션의 덜 끝난 작업을 프로덕션에 내보낼 뻔했습니다.
10월에는 세 번째 일이 생겼습니다. 한 세션이 다른 세션의 스테이징되지 않은 변경 옆에서 자기 파일을 커밋했는데, pre-commit 훅이 훅이 도는 동안 스테이징되지 않은 변경을 전부 stash했습니다. 다른 세션이 고친 내용은 그동안 디스크에서 사라졌고, 타입 체커는 그 세션의 새 파일에서 실패했고, 커밋은 중단됐습니다. 게다가 모든 세션이 제 이름으로 커밋하니 git log로는 누가 무엇을 했는지 알 수 없습니다.
worktree를 쓰는 이유는 한 줄로 말할 수 있습니다. 쓰는 쪽이 여럿인 작업 트리는 경쟁 상태이고, 진 쪽은 진 줄도 모릅니다. 에이전트마다 작업 트리를 따로 주면 경쟁 자체가 사라집니다.
claude -w 사용법과 동작#
공식 문서의 worktrees 페이지에 나온 내용과, 제가 직접 돌려 보고 확인한 내용입니다.
- 위치와 브랜치.
claude -w add-search는.claude/worktrees/add-search/를worktree-add-search라는 새 브랜치로 만듭니다. 이름을 빼면bright-running-fox같은 이름이 자동으로 붙습니다..claude/worktrees/는.gitignore에 넣어 두세요. 안 그러면 메인 체크아웃에서 전부 추적되지 않는 파일로 보입니다. - 어디서 따는지(base ref).
worktree.baseRef의 기본값은"fresh"로, 원격의 기본 브랜치(보통origin/main)에서 땁니다. 최근 24시간 동안 fetch한 적이 없으면 최대 5초 동안 fetch해 줍니다."head"로 바꾸면 지금 로컬HEAD에서 따기 때문에 아직 push하지 않은 커밋까지 따라옵니다. 브랜치 이름은 지정할 수 없으니, 특정 브랜치에서 만들고 싶다면git worktree add를 직접 쓰면 됩니다. - 풀 리퀘스트.
claude --worktree "#1234"는 그 PR의 head를 fetch해서.claude/worktrees/pr-1234를 만듭니다. 따옴표를 빼먹으면 셸이#뒤를 주석으로 처리합니다. - 신뢰 확인. Claude를 한 번도 연 적 없는 폴더에서 대화형
claude -w를 처음 실행하면 “Workspace trust not yet accepted"라며 실패합니다. 그 폴더에서 그냥claude를 한 번 실행해 신뢰 대화상자를 수락하면 됩니다.claude -p -w는 이 확인을 건너뜁니다. - 울타리. 세션이 worktree 안에 있는 동안 Claude Code는 메인 체크아웃의 파일 수정, 메인 체크아웃을 작업 디렉터리로 하는 명령,
git -C나--git-dir,GIT_DIR로 메인 쪽을 가리키는 git 명령을 거부합니다. 무엇을 못 막는지도 문서에 분명히 적혀 있습니다. 메인 체크아웃에 쓰는cp나 셸 리다이렉트는 이 검사로 막히지 않습니다.
worktree가 메인 체크아웃과 무엇을 공유하는지도, 무엇을 공유하지 않는지만큼 중요합니다. 모든 worktree가 같은 .git에 쓰기 때문에, 어느 한 곳에서 만든 커밋과 브랜치는 모든 곳에서 보입니다. 프로젝트 범위 플러그인은 어디서나 로드됩니다. 그리고 worktree 안에서 “Yes, and don’t ask again"으로 답한 승인은 메인 체크아웃의 .claude/settings.local.json에 저장됩니다. 그래서 그 승인은 모든 worktree에 적용되고, 승인한 worktree를 지운 뒤에도 남습니다. 편하긴 한데, 승인하는 명령에 비밀 정보를 넣지 말아야 할 이유가 하나 더 생긴 셈이죠.
정리, 그리고 남아 있는 잠금#
대화형 worktree 세션을 끝낼 때 Claude Code는 지우면 사라질 작업이 있는지 확인합니다. 이름 없는 세션의 worktree가 깨끗하면 브랜치까지 자동으로 지웁니다. 이름이 있는 세션은 먼저 물어봅니다. 작업이 남아 있으면 남길지 물어보고, 화면에 출력되는 claude --worktree <이름> --resume으로 나중에 돌아올 수 있습니다.
비대화형 실행은 사정이 다르고, 직접 돌려 보면서 걸린 건 이것 하나였습니다. claude -p에는 종료할 때 묻는 단계가 없으니 정리도 하지 않습니다. 게다가 Claude Code는 세션이 도는 동안 worktree에 git worktree lock을 걸어 두는데, -p 실행이 끝난 뒤에도 이미 없는 프로세스 ID를 단 채로 잠금이 남아 있습니다. 위 녹화에서도 git worktree remove가 “cannot remove a locked working tree, lock reason: claude session add-search"라며 거부하죠. 문서에도 정확히 이렇게 나와 있습니다. 나중에 다른 세션이 오래된 잠금을 정리할 때 풀리거나, 먼저 git worktree unlock을 실행하면 됩니다. 알고 나면 별일 아니지만, 처음 보면 조금 놀랍니다.
.worktreeinclude: 새 체크아웃에 없는 파일#
worktree에는 추적되는 파일만 들어 있습니다. git이 무시하는 파일도 가져가고 싶다면 저장소 루트에 .worktreeinclude를 두세요. 문법은 .gitignore와 같고, Claude Code는 패턴에 맞으면서 동시에 git이 무시하는 파일만 복사합니다. 그래서 추적되는 파일이 중복될 일은 없습니다.
# .worktreeinclude
.env
.env.local
config/secrets.json이 파일은 Claude Code가 git으로 만드는 모든 worktree에 적용됩니다. claude -w, 서브에이전트 worktree, 데스크톱 앱의 병렬 세션이 다 해당됩니다. git worktree add로 직접 만든 worktree에는 적용되지 않고, WorktreeCreate 훅으로 생성 과정을 바꾸면 아예 처리되지 않습니다.
.env만 넣지 말고 더 넣으라고 권하고 싶습니다. 잊어버리기 쉬운 gitignore 대상 파일일수록 요란하게 실패하지 않거든요. 제 앱은 다른 세션의 커밋 안 된 수정이 절대 배포되지 않도록, 배포 스크립트가 깨끗한 worktree에서 빌드하게 바꿨습니다. 그런데 그 깨끗한 작업 트리에는 한 기능이 쓰는 gitignore 대상 서명 인증서가 없었습니다. 이미지는 그대로 빌드됐고, 그 기능은 프로덕션에서 13일 동안 실패했습니다. 스크립트가 인증서를 복사해 넣고 하나라도 없으면 경고하도록 고친 뒤에야 멈췄죠. worktree에서 한 또 다른 배포에서는 gitignore 대상 테마 폴더가 없었는데, 2분짜리 익스포트가 작업 트리를 더럽힌 뒤에야 빌드가 실패했습니다. 배포와 관련된 일을 worktree에 맡기기 전에 메인 체크아웃에서 git status --short --ignored를 실행해 보고, 그중 무엇을 빌드가 읽는지 확인해 두세요.
node_modules: 가장 비싼 부분#
.worktreeinclude는 작은 파일용입니다. node_modules에는 도움이 안 되고, Claude Code에도 worktree끼리 이걸 공유하는 기능은 없습니다. 코드를 실행해야 하는 worktree라면 각자 node_modules가 필요합니다.
실제 프로젝트에서는 숫자가 커집니다. 제 모바일 앱 저장소에는 메인 체크아웃 옆에 worktree가 19개 있습니다. 그중 12개를 재 보니 194 MB에서 12 GB까지였고, 가장 큰 네 개가 바로 자기 node_modules를 가진 네 개였습니다. 이번 주에는 노트북 디스크가 96% 차 있어서, 정리한다면 여기부터입니다.
방법을 간단한 것부터 순서대로 보면 이렇습니다.
- worktree마다 설치한다. 처음에 에이전트에게
npm install을 시키거나 직접 합니다. 느리고 디스크도 먹지만, 놀랄 일은 없습니다. - lockfile이 같은 체크아웃에서 복제한다. macOS에서는
cp -c -R ../myapp/node_modules .가 APFS 클론을 씁니다. 클론은 어느 한쪽이 바뀌기 전까지 데이터 블록을 공유합니다. 데모의 45 MB는 0.8초 걸렸습니다. 저는 worktree에서 실제로 배포할 때도 이 방법을 썼습니다. 다만 lockfile이 같을 때만 복제하고, 네이티브 빌드 폴더는 조심하세요. 제 경우 메인 체크아웃의 iOS Pods가 worktree 브랜치보다 오래된 SDK용으로 빌드돼 있어서, 그건 새로 설치해야 했습니다. - pnpm을 쓴다. 패키지는 스토어 한 곳에 모이고, macOS의 pnpm은 하드 링크보다 클론을 먼저 시도합니다(리눅스와 윈도우에서는 하드 링크가 먼저). 데모에서 두 번째 worktree 설치는 5초쯤 걸렸습니다.
WorktreeCreate훅에서 설치한다. 이 훅은 Claude Code의 기본 git 로직을 대신하므로,git worktree add다음에 설치까지 돌릴 수 있습니다. 이건 아직 안 해 봤습니다. 해 본다면.worktreeinclude가 더 이상 처리되지 않으니.env복사도 훅에서 해야 한다는 걸 기억하세요.
tmux에서 병렬 에이전트 돌리기#
저는 원래 tmux 안에서 사는 사람이라(매일 쓰는 방식을 정리한 글에 레이아웃이 있습니다), worktree가 그대로 들어맞습니다. worktree 하나에 창이나 패널 하나씩. 아래는 같은 파일을 바꾸라고 지시한 에이전트 세 개를 동시에 띄운 모습입니다.
두 에이전트가 동시에 src/index.js를 고쳤는데 둘 다 상대를 몰랐습니다. 각자의 src/index.js는 디스크에서 서로 다른 파일이기 때문이죠. 메인 체크아웃도 깨끗했습니다. 끝에 남는 건 리뷰하고 머지할 브랜치 세 개이고, 이건 worktree가 대신해 주지 못하는 일입니다. 두 에이전트가 같은 줄을 바꾸면 여전히 머지 충돌이 납니다. 다만 소리 없이 덮어써지는 대신, 눈에 보이는 머지 단계에서 나타납니다.
VS Code에서 worktree는 그냥 폴더입니다. code .claude/worktrees/add-search로 열면 자기 브랜치를 가진 별도 창이 됩니다.
worktree는 스냅숏이다#
worktree도 낡습니다. 11월 19일, 2~3일 전부터 준비돼 있던 worktree에서 OTA 업데이트가 나갔는데, 그 사이 다른 곳에서 나간 수정 두 개를 조용히 되돌려 버렸습니다. 그날 바로 잡아서 교체했지만, worktree가 완벽하게 격리돼 있었던 게 바로 문제였습니다. 그 수정을 한 번도 본 적이 없었으니까요. git 명령 한 줄이면 릴리스 전에 잡을 수 있었습니다.
baseRef: "fresh"는 새 worktree를 최신으로 유지해 줍니다. 오래된 worktree를 최신으로 유지해 주는 건 없으니, 거기서 릴리스하기 전에 확인하세요.
서브에이전트와 훅#
이런 격리를 얻으려고 에이전트마다 터미널을 열 필요는 없습니다. 프런트매터에 isolation: worktree를 넣은 커스텀 서브에이전트는 항상 전용 임시 worktree에서 돕니다.
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---
Apply the requested refactor across every affected file, then run the tests
and report the results.문서에 나온 예시 그대로입니다. 서브에이전트가 변경 없이 끝나면 worktree는 지워집니다. 변경이 있는 worktree는 작업을 잃지 않고 지울 수 있을 때까지 주기적 정리에서 살아남습니다. 미묘한 점 하나. .claude/worktrees/ 아래 worktree에서 도는 서브에이전트는 지시를 메인 대화에서 이어받고, worktree 루트의 CLAUDE.md는 읽지 않습니다.
WorktreeCreate와 WorktreeRemove 훅은 git 로직을 통째로 대신합니다. git이 아닌 버전 관리 시스템을 쓰거나 worktree를 .claude/worktrees/ 말고 다른 곳에 두고 싶을 때를 위한 것이지만, 위에서 말한 설치 같은 준비 단계를 넣는 자리이기도 합니다.
그냥 git worktree add가 더 나은 경우#
고백하자면 제 앱 저장소의 .claude/worktrees 폴더는 비어 있습니다. worktree 19개는 전부 그냥 git worktree add로 만들었고, 전부 지난 한 달 사이에 생겼고, 절반은 detached HEAD 상태입니다. 노트북의 다른 저장소에도 40, 40, 18, 10, 3, 2, 2개가 더 있습니다. 게다가 대부분은 제가 만든 게 아닙니다. 이 노트북에 있는 Claude Code 대화 기록 638개 중 85개에서 에이전트가 git worktree add를 실행했고, 횟수로는 모두 336번입니다.
그냥 git이 더 나은 건 이럴 때입니다.
- 이미 있는 특정 브랜치가 필요할 때. 예를 들어 핫픽스용으로 남겨 둔 릴리스 브랜치.
baseRef로는 안 됩니다. - 수정 하나만 내보내고 싶을 때. 다른 세션들이 아직 배포하지 않은 작업을
main에 커밋해 둔 상태여서, 프로덕션에서 돌고 있는 커밋에 detached worktree를 만들고 제 수정만 cherry-pick해서 거기서 배포했습니다. 이렇게 하면 나가는 건 그 수정 하나뿐입니다. - 에이전트에게 직접 지시를 쓸 때. 한 저장소에서 에이전트 여러 개를 돌릴 때, 저는 각자에게 주는 지시에
git worktree add --detach "$TMPDIR/<task>-wt" refs/remotes/origin/main으로 자기 worktree를 만들고,git push origin HEAD:main으로 push하고, 충돌하면 rebase하라고 적습니다. - 지워지면 안 될 때. Claude Code의 정리는
git worktree add로 직접 만든 worktree를 절대 지우지 않습니다.
claude -w가 나은 건 손으로 세션을 시작하면서 브랜치 생성, .env 복사, 메인 체크아웃을 둘러싼 울타리, 정리를 맡기고 싶을 때입니다. 둘을 섞어 써도 괜찮습니다. 어느 쪽으로 만들든 Claude Code는 똑같이 worktree로 다루고, 위에서 말한 메인 체크아웃과의 공유도 똑같습니다.
요약#
병렬로 돌리는 세션마다 claude -w <이름>을 쓰고, .claude/worktrees/를 .gitignore에 넣으세요. .worktreeinclude에는 .env만이 아니라 빌드에 필요한 gitignore 대상 파일을 전부 적어 두세요. node_modules는 worktree마다 설치할지, 복제할지, pnpm을 쓸지 정해 두세요. -p로 돌린 뒤에는 git worktree unlock이 필요한 잠금이 남아 있을 수 있습니다. 막 만든 게 아닌 worktree에서 배포하기 전에는, 이미 프로덕션에 나간 내용이 들어 있는지 확인하세요. worktree는 에이전트끼리 파일을 덮어쓰는 건 막아 주지만, 서로 생각이 다른 것까지 막아 주지는 않습니다. 마지막에 브랜치 세 개를 리뷰하는 건 결국 사람입니다.
더 읽을거리#
이 블로그에서:
- 제가 매일 Claude Code를 쓰는 방식: tmux, 권한 모드, 폰에서 접속하는 방법
외부 자료:
- Claude Code 문서의 Run parallel sessions with worktrees: 웬만한 문서보다 꼼꼼합니다
- git-worktree: 무엇이 공유되고 무엇이 worktree마다 따로인지
- pnpm의
packageImportMethod: 클론과 하드 링크
