Claude Code 워크트리로 병렬 세션 돌리기: 만들기·격리 규칙·안전한 정리

터미널 두 개에서 Claude Code를 같은 폴더로 띄우면 두 세션이 같은 파일을 번갈아 고칩니다. 워크트리는 세션마다 따로 git 체크아웃을 줘서 이 충돌을 없애고, 잘못되면 통째로 버리면 되는 자리를 만들어 줘요(이 관점은 맡기는 정도를 네 단계로 세운 글에 있습니다).

쓰는 법 자체는 간단합니다. 터미널마다 claude --worktree <이름>을 다른 이름으로 실행하면, 저장소 루트의 .claude/worktrees/<이름>/에 worktree-<이름> 브랜치로 워크트리가 생기고 세션끼리 파일을 건드리지 않습니다.

그런데 직접 해 보니 막히는 곳은 시작과 끝에 있더라고요. 커밋이 하나도 없는 저장소에서는 Failed to resolve base branch "HEAD"로 시작부터 안 되고, 잠긴 워크트리는 cannot remove a locked working tree로 지워지지 않았습니다.

2026년 9월 18일 공식 문서 기준이고, git 동작과 오류 메시지는 Ubuntu 24.04 · git 2.43.0 · Claude Code 2.1.274 테스트 환경에서 직접 확인했습니다.

10월 12일에는 Windows 11 · PowerShell 5.1 · git 2.53.0 · Claude Code 2.1.296에서 워크트리를 만들고 지우는 과정을 다시 확인했습니다. 격리 검사가 과하게 걸리거나 정리가 일을 지운 사례는 공개 이슈를 인용했습니다.

시작 전에 해 둘 것

1. .claude/worktrees/를 .gitignore에 넣기

넣지 않으면 워크트리 내용이 메인 체크아웃에 추적되지 않는 파일 더미(?? .claude/)로 보입니다. Windows에서 워크트리 하나를 만든 직후 메인의 git status --short도 딱 이 한 줄이었어요.

2. .worktreeinclude로 .env 채우기

워크트리는 새 체크아웃이라 .env·.env.local처럼 추적되지 않는 파일이 없습니다. 워크트리에서만 빌드가 깨진다면 이것부터 의심해 보세요. 프로젝트 루트에 .worktreeinclude를 두면 워크트리를 만들 때 복사됩니다.

.env
.env.local
config/secrets.json

.gitignore와 같은 문법이고, 패턴에 맞으면서 git이 무시하는 파일만 복사합니다. WorktreeCreate 훅으로 워크트리 만들기를 대신하고 있다면 이 파일은 처리되지 않으니 훅 안에서 복사하세요. 의존성 설치는 워크트리 안에서 따로 합니다.

3. 세션 시작하기

claude --worktree feature-auth

다른 터미널에서 다른 이름으로 같은 명령을 실행하면 격리된 세션이 하나 더 생깁니다. 이름을 생략하면 bright-running-fox 같은 이름을 지어 주고, 세션 도중에 “워크트리에서 작업해”라고 해도 만들어 줘요. 이미 있는 이름이면 새로 만들지 않고 그 워크트리를 엽니다.

처음 실행할 때 막힐 수 있는 곳이 있습니다. 그 폴더에서 claude를 한 번도 실행한 적이 없으면 신뢰 대화상자를 먼저 수락하라는 오류가 나니, claude를 한 번 실행해 수락하세요(-p 실행은 이 확인을 건너뜁니다). 커밋이 하나도 없는 저장소라면 아래 오류 절의 Failed to resolve base branch가 납니다.

4. 필요하면 갈라지는 지점 바꾸기

기본은 원격의 기본 브랜치(보통 main)라 대부분은 그대로 두면 됩니다. 푸시 안 한 커밋을 들고 가야 하면 설정에 "head"를 적습니다.

{ "worktree": { "baseRef": "head" } }

• 브랜치 이름은 넣을 수 없습니다. 특정 브랜치에서 시작하려면 git worktree add로 직접 만듭니다.
• 기본값 "fresh"는 최근 24시간 안에 가져온 적이 없으면 기본 브랜치를 최대 5초 동안 가져오고, 실패하면 로컬 값을 씁니다.
• 풀 리퀘스트에서 시작하려면 claude --worktree "#1234"처럼 번호(또는 GitHub PR·GitLab MR URL)를 넘깁니다. #은 따옴표로 감싸고, 워크트리는 .claude/worktrees/pr-<번호>에 생깁니다.

따로 쓰는 것과 함께 쓰는 것

워크트리라고 모든 게 나뉘는 건 아닙니다. 따로인 건 작업 파일과 브랜치뿐이고, .git·플러그인·승인은 함께 써요.

대상	워크트리에서	알아 둘 점
작업 파일·브랜치	따로	한 브랜치는 한 워크트리에서만
.git 폴더	함께	git 명령이 메인의 .git에 씀
프로젝트 범위 플러그인	함께	재설치 불필요(2.1.200 이상)
“다시 묻지 않기” 승인	함께	메인에 저장, Windows 등은 예외
.env 같은 무시 파일	없음	.worktreeinclude로 복사

직접 만든 워크트리의 .git을 열어 보면 폴더가 아니라, 메인 저장소 안을 가리키는 한 줄짜리 파일이었습니다.

$ cat ../demo-feature-a/.git
gitdir: ~/demo/.git/worktrees/demo-feature-a

Windows에서 claude --worktree가 만든 워크트리도 같은 모양이었고, 경로만 슬래시로 적혀 있었어요.

gitdir: C:/work/demo/.git/worktrees/feature-a

저장소 하나를 여러 폴더가 나눠 쓰는 구조라서, 샌드박스를 켠 상태에서도 워크트리 안의 git commit이 되도록 그 쓰기는 허용돼 있습니다.

승인 규칙도 함께 씁니다. Bash 명령에 “다시 묻지 않기”를 고르면 메인 체크아웃의 .claude/settings.local.json에 저장돼 같은 저장소의 다른 워크트리에도 적용돼요. Windows처럼 Claude Code가 저장소 루트를 쓰지 않는 경우에는 그 워크트리에만 남습니다.

워크트리 안에서 막히는 명령

세션이 워크트리에 격리돼 있는 동안에는 메인 체크아웃으로 향하는 명령이 막힙니다. --worktree로 시작했든, 도중에 들어갔든, 재개했든 같고, 걸리는 검사는 이렇습니다.

• 파일 편집: 메인 체크아웃 경로를 고치는 Edit·Write·NotebookEdit.
• 작업 폴더: 작업 폴더가 메인 체크아웃이거나 메인 밖에 머문다고 확인할 수 없는 Bash·PowerShell·Monitor 명령.
• git 우회: git -C, --git-dir, GIT_DIR·GIT_WORK_TREE, git 전의 cd.
• 명령 형태: 명령 이름을 실행 때 계산하거나 구문을 해석할 수 없어, 그 안의 git이 워크트리에 머무는지 확인할 수 없는 명령.

거슬리면 검사를 끄고 싶어지는데, 명령 형태 검사는 끌 수 없습니다. 대신 거부될 때 Claude에게 어떻게 다시 쓰면 되는지(예: 평범한 여러 명령으로 쪼개기)가 함께 전달되니, Claude가 그 안내대로 고쳐 다시 실행하면 됩니다.

PowerShell 명령에는 작업 폴더 검사만 걸리고, 이 세션이 띄우는 서브에이전트에도 같은 검사가 걸립니다. 한 세션 안에서 일을 나누는 방법은 조사와 검토를 서브에이전트로 나누는 방법에 있습니다.

끝낼 때 지워지는 것과 남는 것

대화형 세션은 끝낼 때 묻고, claude -p 실행은 묻지 않고 워크트리를 그대로 남깁니다. 이 차이를 모르면 워크트리가 소리 없이 쌓여요.

• 대화형 세션: 깨끗하고 이름 없는 세션이면 워크트리와 브랜치를 자동으로 지우고, 이름 붙인 세션이면 먼저 묻습니다. 변경·추적되지 않는 파일이나 새 커밋이 남아 있으면 유지할지 지울지 묻고, 유지하면 나중에 다시 들어올 claude --worktree <이름> --resume 명령을 보여 줍니다.
• claude -p 실행: 종료 프롬프트가 없어 정리하지 않습니다. 만들 때 건 잠금도 이후 세션의 정리 작업이 풀 때까지 남습니다. Windows에서 claude -p --worktree feature-a를 한 번 돌리고 나서 git worktree list --porcelain을 보니, 실행이 끝났는데도 워크트리에 locked claude session feature-a (pid <번호>)가 붙어 있었습니다.
• 주기적 정리(스윕): 서브에이전트·백그라운드 세션용으로 Claude가 만든 워크트리 중 cleanupPeriodDays가 지난 것만 지우고, 일이 남아 있으면 둡니다. 백그라운드로 보내지 않은 --worktree 세션과 직접 git worktree add로 만든 워크트리는 나이와 상관없이 남습니다.

주의: 남은 일이 있을 때 지우기를 고르면 폴더와 브랜치뿐 아니라 그 안의 커밋 안 한 일도 함께 사라집니다.

남은 워크트리를 직접 지울 때는 이 순서입니다. 잠겨 있지 않으면 unlock은 건너뛰고, 커밋 안 한 변경이 있으면 남길 것을 확인한 뒤 remove에 --force를 붙이세요.

git worktree list
git worktree unlock <경로>
git worktree remove <경로>

직접 만난 오류

아래는 모두 테스트 환경에서 직접 실행해 본 메시지입니다.

fatal: 'feature-a' is already used by worktree at ...

fatal: 'feature-a' is already used by worktree at '~/demo-feature-a'

한 브랜치는 한 워크트리에서만 체크아웃할 수 있습니다. 다른 브랜치 이름으로 만들거나, 그 브랜치를 쓰던 워크트리를 먼저 정리하세요.

fatal: ... contains modified or untracked files, use --force to delete it

워크트리에 저장되지 않은 변경이 있어 git이 삭제를 거부한 것입니다. 남길 것은 먼저 커밋하거나 옮기고, 버려도 되는 것만 남았을 때 --force를 붙입니다.

fatal: cannot remove a locked working tree;

fatal: cannot remove a locked working tree;
use 'remove -f -f' to override or unlock first

워크트리가 잠겨 있다는 뜻입니다. 에이전트나 백그라운드 세션이 도는 동안 Claude Code가 git worktree lock을 걸어 두거든요.

Windows의 git 2.53에서는 같은 오류에 잠금 사유가 붙어 나옵니다. 어느 세션이 잠갔는지 바로 보여서 -p가 남긴 것인지 가리기 쉬워요.

fatal: cannot remove a locked working tree, lock reason: claude session feature-a (pid <번호>)
use 'remove -f -f' to override or unlock first

git worktree unlock <경로>로 푼 뒤 지우면 됩니다. Ubuntu에서는 잠금을 푼 다음 --force 삭제가 통과했고, Windows에서는 변경이 없던 워크트리라 --force 없이도 지워졌습니다.

두 환경 모두 워크트리를 지워도 worktree-feature-a 같은 브랜치는 남았어요. 브랜치까지 정리하려면 git branch -D <브랜치>를 따로 실행합니다.

Failed to resolve base branch "HEAD": git rev-parse failed

커밋이 하나도 없는 저장소에서 claude --worktree를 실행하면 나옵니다. 커밋을 하나 만들고 다시 실행하세요. Windows에서는 Error creating worktree: 뒤에 같은 문구가 붙어 나왔고, 커밋 하나를 만들자 바로 워크트리가 생겼습니다. 이 메시지는 Claude Code가 내는 것이고, git은 같은 상황에서 No possible source branch, inferring '--orphan'을 출력하고 워크트리를 만들었습니다.

다른 사람들이 겪은 문제

버전과 운영체제는 보고자가 적은 값이고, 만들 때·도는 동안·끝난 뒤에 한 번씩 막혔다는 보고들입니다.

만들 때 설정 폴더가 덜 따라왔다

channel-dante(2026-02-24, 이슈 #28041, Claude Code 2.1.51, macOS)는 워크트리의 .claude/에 settings.local.json만 있고 skills/·agents/·rules/·settings.json 등은 오지 않았다고 보고했습니다.

2026년 10월 6일 확인한 문서는 워크트리 루트에 .claude/skills가 없으면 메인 체크아웃의 프로젝트 스킬을 불러오고(v2.1.277 이상), .claude/agents·.claude/commands도 같은 방식으로 읽는다고 합니다.

도는 동안 격리 검사가 과하게 걸렸다

apollion69(2026-09-17, 이슈 #95122, Claude Code 2.1.272·2.1.273, WSL2 Ubuntu)는 git을 쓰지 않는 Bash 호출까지 거부돼, 9월 15~17일 워크트리 세션 여섯 개에서 75건이 거부되고 약 115번의 도구 호출이 낭비됐다고 보고했습니다.

끝난 뒤 워크트리가 쌓였다

atrimble-synmax(2026-02-18, 이슈 #26725)는 세션이 비정상 종료되면 정리할 수단이 없어, 1월 15일에 생긴 워크트리가 이후 수십 번의 세션 동안 남았다고 보고했습니다. 이 보고의 경로는 ~/.claude-worktrees/로 현재 문서의 .claude/worktrees/와 다릅니다.

끝난 뒤 정리가 일을 지웠다

bkhatarani-bot(2026-04-10, 이슈 #46444, Windows 11)는 새 세션을 열 때마다 이전 워크트리가 커밋 없이 정리돼 약 10일치 작업과 300개 넘는 파일이 사라졌다고 보고했습니다.

9월 18일 문서는 일이 남은 워크트리를 남긴다고 해 이 보고와 어긋납니다. 보고의 버전란에는 모델 이름이 적혀 있습니다.

네 건을 놓고 보면, 쓰기 전에 만들 때 무엇이 따라오는지와 끝낼 때 무엇이 지워지는지만 확인해 둬도 세 단계 중 두 곳은 미리 막을 수 있습니다.

마치며

워크트리는 claude --worktree <이름> 한 줄로 시작되지만, 실제로 손이 가는 건 그 앞뒤였습니다. 시작 전에는 .gitignore와 .worktreeinclude를 준비해 두면 새 워크트리에서 빌드가 바로 돌고, 끝낼 때는 -p 실행이 남긴 워크트리가 없는지 가끔 git worktree list로 보는 게 좋습니다. 워크트리 안에서 거부되는 명령은 메인 체크아웃을 향한 것이라 쪼개 쓰면 풀린다는 것도 기억해 두세요.

저는 무엇보다 .claude/worktrees/를 .gitignore에 넣는 것부터 권합니다. 그다음 첫 워크트리 세션을 띄워 보세요.