핵심 요약
- claude --worktree(축약형 -w)를 실행하면 세션이 .claude/worktrees/<name>에 만들어진 리포지토리 사본 안에서 시작되고, worktree-<name>이라는 브랜치가 체크아웃됩니다.
- 다른 터미널에서 세션을 더 띄우면 병렬 작업이 됩니다 — 세션마다 자기 디렉터리만 편집하면서 같은 Git 히스토리와 원격을 공유합니다.
- 서브에이전트에도 워크트리가 붙습니다: 자연어로 부탁하거나, .claude/agents/*.md 프론트매터에 isolation: worktree를 넣어 상시화하세요.
- 종료할 때 변경 없는 이름 없는 워크트리는 자동 삭제, 작업 중인 것은 유지/삭제를 물어봅니다. 결과 머지는 worktree-<name>을 평범하게 git merge하면 끝.
Claude Code Worktrees in 7 Minutes
채널: Developers Digest7:10
I'm using claude --worktree for everything now
채널: Matt Pocock7:57
Worktrees — official documentation
공식 문서: code.claude.com/docs
이 페이지의 모든 플래그, 경로, 정리 동작은 공식 worktrees 문서와 대조해 검증했습니다. 위 영상들이 시각·사실 자료이며, 종료 시 유지/삭제 프롬프트와 main으로 push되는 함정도 여기서 확인했습니다.
스크린샷의 권리는 각 제작자에게 있으며, 해당 타임스탬프로 바로 연결됩니다. 얼굴이 나온 장면은 사용하지 않았습니다.
Claude Code 워크트리 사용법, 단계별로
파트 1 — 첫 번째 격리 세션
- 1
커밋이 하나 이상 있는 Git 리포지토리 준비
워크트리는 기존 히스토리에서 갈라지므로, worktree 기능에는 진짜 Git 리포지토리가 필요합니다. 새 폴더에서 git init을 실행하고 파일을 하나 만들고(데모는 touch index.html만 실행) 커밋하세요. 건너뛰면 Claude Code가 갈라질 대상이 없습니다.
git init과 touch index.html — claude --worktree가 돌아가기 위해 필요한 건 커밋 하나뿐입니다.1:06부터 시청 - 2
워크트리가 실제로 뭔지 알기
Git 워크트리는 리포지토리의 히스토리와 원격을 공유하면서 자체 브랜치를 체크아웃한 두 번째 작업 디렉터리입니다. 브랜치를 전환하는 것과 달리 아무것도 stash되지 않습니다: 메인 체크아웃과 모든 워크트리가 동시에 쓸 수 있는 상태로 남죠. 병렬 에이전트가 정확히 원하는 것입니다.
하나의 리포지토리, 여러 작업 폴더: ../main, ../feature1, ../feature2가 각자 브랜치에 동시에 앉아 있습니다.0:30부터 시청 - 3
--worktree 플래그로 Claude Code 실행
리포지토리 안에서 claude --worktree(또는 축약형 claude -w)를 실행하세요. Claude Code는 .claude/worktrees/<name>을 만들고, 이름을 안 넘기면 bright-tumbling-rabbit 같은 이름을 지어 세션을 그 사본으로 바로 보냅니다. 데스크톱 앱에서는 세션을 시작할 때 워크트리 옵션을 고르면 됩니다.
환영 배너의 작업 디렉터리가 이미 .claude/worktrees 안쪽 — 이후 모든 일은 사본에서 일어납니다.1:22부터 시청 - 4
두 번째 작업을 위한 세션 하나 더 열기
다른 터미널에서 claude --worktree를 한 번 더 실행하세요. 이름 없이는 독립적인 워크트리가 하나 더 생기고, 같은 이름을 두 번 넘기면 같은 워크트리를 다시 엽니다. 이제 에이전트 둘이 같은 프로젝트를 동시에 편집할 수 있습니다. 각자 자기 디렉터리만 보이기 때문입니다.
파트 2 — 파일과 명령이 머무는 곳
- 5
.claude/worktrees 아래의 온전한 사본 확인
파일 관리자로 폴더를 열어 보세요: 워크트리마다 온전한 체크아웃에 자체 index.html, 자체 .claude/settings.local.json, 자체 git 파일이 있고, 무거운 오브젝트 데이터베이스는 메인 .git에 공유된 채입니다. 그래서 사본 하나 더 띄우는 게 거저리인 겁니다.
디스크 위의 두 워크트리 — clever-munching-toast와 spicy-napping-otter — 각각 자체 git 폴더와 index.html을 가진 온전한 프로젝트 사본입니다.1:50부터 시청 - 6
명령이 워크트리 안에 머무는지 확인
첫 세션이 브라우저에서 페이지를 열면 권한 프롬프트는 경로가 .claude/worktrees/clever-munching-toast 쪽을 가리킨다고 보여 줍니다 — 메인 체크아웃이 아닙니다. Claude Code는 서브에이전트가 메인 체크아웃을 직접 편집하는 것도 막고, 그 격리 검사 중 하나는 끌 수 없습니다.
승인 대화상자에 워크트리 경로가 정확히 적혀 있어, 세션 1이 자기 사본만 건드린다는 증거가 됩니다.1:42부터 시청 - 7
워크트리 이름 짓기, PR에서 갈라내기(선택)
claude --worktree feature-auth는 예측 가능한 이름의 워크트리를 만들고, 같은 이름을 다시 실행하면 복제 대신 다시 엽니다. 따옴표로 감싼 PR 번호(claude --worktree "#1234")나 GitHub/GitLab PR URL을 넘기면 그 풀 리퀘스트의 워크트리가 .claude/worktrees/pr-<number>에 생깁니다.
파트 3 — 병렬 서브에이전트와 정리
- 8
워크트리 격리로 병렬 서브에이전트 요청
격리는 터미널을 넘어 확장됩니다. "서로 다른 서브에이전트 다섯을 띄워 다섯 가지 변형을 만들고, git worktree 격리를 활용해"라는 프롬프트 하나면 Claude Code가 Task 에이전트를 각자 격리된 워크트리에서 띄워 같은 리포지토리를 부딪힘 없이 동시에 작업합니다.
다섯 Task 에이전트가 병렬로 spawn — 각자 자기만의 격리 git worktree에서 작업한다고 알립니다.2:42부터 시청 - 9
각 에이전트가 자기 레인에서 도는 모습 보기
작업 목록에는 다섯 변형이 전부 도구 사용량과 토큰 수와 함께 표시되므로, 터미널 다섯 개를 열지 않고도 진행 상황이 보입니다. 서브에이전트 대화 기록은 메인 스레드 컨텍스트에 안 실리므로, 에이전트들이 무거운 일을 하는 동안 지휘 세션은 가볍게 유지됩니다.
실행 중인 다섯 서브에이전트 — Variation 1은 이미 50.3k 토큰으로 끝났고 나머지는 제각각 워크트리에서 파일을 읽고 있습니다.3:42부터 시청 - 10
변형 비교 후 승자 머지
에이전트가 끝나면 Claude Code가 변형마다 .claude/worktrees/agent-<id>/ 아래 경로와 함께 목록을 보여 주므로 브라우저에서 나란히 열어 비교할 수 있습니다. 마음에 드는 것은 그 워크트리 브랜치를 평범한 git merge로(또는 PR로) 출하하면 됩니다 — 충돌이 생겨도 다른 Git 머지처럼 풀면 됩니다.
요약에 변형마다 .claude/worktrees 경로가 적히고, 렌더링된 결과 하나가 목록 옆에 열려 있습니다.4:22부터 시청 - 11
격리를 재사용 가능한 서브에이전트로 저장
워크트리 격리를 상시화하려면 부탁만 하면 됩니다: "프런트엔드 개발자 서브에이전트를 만들고, Haiku 모델을 쓰고, 워크트리 격리를 활용하게 해 줘." Claude Code가 자기 에이전트 문서를 조사해 .claude/agents/ 아래 새 파일을 써 줍니다.
자연어면 충분 — Claude Code는 파일을 쓰기 전에 커스텀 에이전트 형식을 자기 문서에서 확인합니다.5:42부터 시청 - 12
isolation: worktree 프론트매터 확인
생성된 frontend-dev.md에는 name, description, model: haiku, 도구 허용 목록, 그리고 — 새 줄 — isolation: worktree가 들어 있습니다. 이제 이 서브에이전트의 모든 실행은 임시 워크트리에서 이뤄지고, 변경 없이 끝나면 자동으로 제거됩니다.
프론트매터 8번째 줄의 isolation: worktree — 이 한 줄이 이 서브에이전트의 모든 실행에 전용 워크트리를 줍니다.6:42부터 시청 - 13
머지 후 정리는 Claude에게
세션을 종료하면 Claude Code가 워크트리를 살펴봅니다: 깨끗한 이름 없는 워크트리는 자동 삭제, 작업이 있는 것은 유지/삭제를 물어보고 — 유지하면 나중에 쓸 claude --worktree <name> --resume 명령을 출력합니다. 헤드리스 -p 실행은 절대 정리하지 않으니 git worktree remove로 지우세요.
Claude Code 워크트리 vs 수동 git worktree add
워크트리 자체는 Git에 몇 년 전부터 있었습니다 — 새로운 건 Claude Code가 그 전체 수명 주기를 관리한다는 점입니다. 중요한 차이:
- 1생성: 수동이라면 git worktree add ../project-feature -b feature를 실행하고 cd한 뒤 Claude를 띄웁니다. claude --worktree는 한 단계로 .claude/worktrees/<name> 안에 세션을 떨어뜨리고, 이름은 자동으로도 직접으로도 붙입니다.
- 2기준 커밋: worktree.baseRef가 시작점을 정합니다 — fresh(기본값)는 원격 기본 브랜치에서, head는 push하지 않은 로컬 커밋을 끌고 옵니다. 특정 브랜치를 지정하는 플래그는 없고, 문서는 그 경우 수동 git worktree add를 권합니다.
- 3Dotfiles: 프로젝트 루트의 .worktreeinclude 파일이 .env 같은 gitignore된 파일을 새 워크트리마다 복사해 줍니다. 손으로 만든 워크트리엔 이 혜택이 없습니다.
- 4정리: Claude Code는 종료 때 워크트리를 점검해, 깨끗한 이름 없는 워크트리는 자동 삭제, 작업 중인 것은 만지기 전에 물어보고, 버려진 서브에이전트 워크트리도 주기적으로 쓸어 담습니다. 수동 워크트리는 온전히 본인 책임입니다.
- 5가드레일: 격리 검사가 서브에이전트의 메인 체크아웃 편집을 막고, 세션 재개 시 그 워크트리로 되돌려 놓습니다. 날것 git worktree add에는 이런 안전망이 없습니다.
속은 여전히 평범한 Git입니다. VS Code 소스 제어 패널은 워크트리마다 변경 사항을 나열하고, 머지는 평범한 git 머지이며, 손으로 만든 워크트리와 Claude가 만든 워크트리가 같은 리포지토리에 공존합니다 — 작업마다 도구를 고르면 됩니다.
워크트리가 말을 안 들을 때
함정 대부분은 기능 버그가 아니라 Git 기본이 비친 것입니다. 이 다섯 가지가 거의 모든 거친 모서리를 커버합니다:
- 1push가 main에 올라간다. 새 워크트리 브랜치는 origin 기본 브랜치를 추적하므로, 조건 없는 git push가 main을 겨냥할 수 있습니다. git push origin worktree-<name>처럼 명시하고 main은 보호하세요.
- 2파일이나 도구가 없다. gitignore된 파일(.env, vendor 디렉터리)과 LFS 같은 리포지토리 로컬 필터 드라이버는 새 워크트리로 전파되지 않습니다. .worktreeinclude에 나열하거나, 워크트리 안에서 git lfs pull과 셋업 명령을 실행하세요.
- 3신뢰 오류로 실행 실패. 신뢰하지 않는 디렉터리에서 claude --worktree는 워크스페이스 승인을 요구하는 오류로 끝납니다 — 승인하고 다시 실행하세요. (비대화형 -p 실행은 이 검사를 건너뜁니다.)
- 4머지 때 두 워크트리가 충돌. 두 작업이 같은 파일 — 라우트, 사이드바, package.json — 을 고치면 머지 때 충돌을 푸는 건 다른 Git 워크플로와 같습니다. 워크트리가 없애 주는 건 실행 중 충돌이지, 겹치는 의도가 아닙니다.
- 5헤드리스 실행 후 남는 워크트리. -p 실행은 뒷정리를 안 합니다. git worktree remove로 직접 지우세요(잠겨 있으면 먼저 git worktree unlock).
세션 발밑에서 워크트리를 지워도 치명적이지 않습니다: 다음 resume는 실행 디렉터리로 폴백하고 묶음만 풀립니다. 세션의 다른 부분은 멀쩡합니다.