“Claude Code worktree”는 켜야 하는 기능처럼 들립니다. 대개는 그보다 단순합니다. worktree는 git이 만드는 directory이고, Claude Code는 시작한 directory에서 파일을 편집하는 프로세스입니다. 이 두 사실을 합치면 격리된 에이전트 session이 됩니다.
이 구분이 중요한 이유는 인터넷에서 세 가지가 뒤섞여 쓰이기 때문입니다. git worktree, Claude Code 자체 앱 안의 worktree 기능, 그리고 대신 worktree를 만들어 주는 워크스페이스 도구입니다. 이름과 목적은 같지만 directory를 누가 만들었는지에 따라 위치, 정리, 리뷰 방식이 달라집니다.
git worktree란 정확히 무엇인가
일반적인 clone에는 작업 트리가 하나뿐입니다. 에디터에서 보이는 파일입니다. git worktree를 쓰면 같은 저장소가 여러 작업 트리를 동시에 가질 수 있고, 각각 다른 branch에 있습니다. object database와 remote는 공유되지만 checkout된 파일과 index는 공유되지 않습니다.
git worktree list
# /Users/you/app abc1234 [main]
# /Users/you/app-fix-login def5678 [fix/login]- 각 worktree는 자체 branch, HEAD, index, 디스크상의 파일을 가집니다.
- 같은 branch를 두 worktree에서 동시에 checkout할 수 없습니다.
- worktree를 삭제하면 directory와 checkout이 사라지지만 branch history는 남습니다.
- 모든 worktree는 여전히 같은 저장소이므로 commit, fetch, push가 같은 object를 봅니다.
이것이 바로 에이전트에 필요한 격리입니다. Claude Code는 열어 둔 checkout을 건드리지 않고 자기 worktree에서 읽고, 편집하고, 테스트를 실행하고, commit할 수 있습니다. 에이전트가 뭔가를 망가뜨리면 directory를 지우고 main branch를 지키면 됩니다.
Claude Code에 worktree가 필요한 이유
에이전트 session은 파일을 건드리는 채팅이 아닙니다. 명령을 실행하고, dev server를 띄우고, 생성 파일을 쓰고, 변경을 stage하고, 때로는 branch를 바꿉니다. 한 checkout의 두 session은 이 상태를 모두 공유합니다. 실패는 대개 극적이지 않습니다. 테스트가 잘못된 코드에 대해 통과하고, formatter가 다른 에이전트의 작업을 다시 쓰고, commit에 두 작업의 파일이 함께 들어갑니다.
worktree는 이런 공유 상태 실패를 별도 directory로 바꿔 줍니다. 대가는 새 worktree마다 깨끗하게 시작한다는 점입니다. node_modules도, .env도, 로컬 데이터베이스도 없습니다. 이 가이드의 나머지는 그 비용을 의도적으로 치르는 방법에 관한 것입니다.
Claude Code에 worktree 모드가 있나?
Claude Code CLI는 worktree에서 작업하기 위해 특별한 모드가 필요 없습니다. session 경계는 작업 directory입니다. ../app-fix-login 안에서 claude를 시작하면 그곳에서 읽고 쓰며, ../app-fix-billing에서 또 하나를 시작하면 다른 branch와 다른 파일 집합을 갖습니다.
다른 Claude Code 표면은 worktree를 대신 관리합니다. desktop app은 격리된 git worktree에서 병렬 session을 실행할 수 있고, agent team이나 subagent는 session 안에서 작업을 위임합니다. 그것들은 편의 계층입니다. checkout을 만들고, 에이전트를 넣고, 경로를 숨깁니다. 예측 가능한 위치가 필요하면 worktree를 직접 만들고 그 안에서 Claude Code를 실행하세요.
Claude Code worktree는 어디에 두어야 하나?
위치는 worktree를 누가 만드는지에 달렸습니다. 수동 설정이라면 git worktree add에 경로를 넘깁니다. 두 가지 관례가 잘 맞습니다. main checkout 옆의 형제 directory, 또는 저장소 밖의 전용 worktrees/ 폴더입니다.
# sibling next to the main checkout
git worktree add ../app-fix-login -b fix/login origin/main
# or a dedicated root outside the repo
git worktree add ~/worktrees/app/fix-login -b fix/login origin/mainworktree는 main checkout 밖에 두세요. 저장소 안의 worktree는 모든 검색에 나타나고, editor indexing을 헷갈리게 하며, 실수로 commit될 수 있습니다. 도구가 저장소 안 숨은 폴더에 worktree를 만든다면, 그 폴더가 gitignore되어 있는지 확인한 뒤 의존하세요.
Nethür는 자체 관리 directory에 worktree를 만들고 경로를 추적합니다. Claude Code, GSD, 순수한 git worktree add로 만든 worktree가 이미 있다면, Nethür는 옮기라고 하지 않고 외부 worktree로 보여 줄 수 있습니다. Settings → General → Workspace에서 어떤 외부 소스를 볼지, 어떤 위치 root를 스캔할지 제어합니다.
경로를 직접 관리하고 싶지 않다면 Nethür 같은 git worktree GUI가 디스크에는 일반 checkout을 그대로 두면서 worktree 생성, 추적, 정리를 대신해 줍니다.
worktree를 만들고 Claude Code 시작하기
최신 base ref에서 시작해 에이전트가 지난주 코드를 상대로 작업하지 않게 하세요.
git fetch origin
git worktree add ../app-fix-login -b fix/login origin/main
cd ../app-fix-login
claudeworktree마다 고유한 branch 이름을 쓰세요. 같은 작업에 두 번째 에이전트를 원한다면 프롬프트가 같더라도 다른 branch로 두 번째 worktree를 만드세요. branch가 있어야 두 결과를 독립적으로 비교하고 merge할 수 있습니다.
Nethür에서 같은 단계는 대화상자 하나입니다. worktree를 만들고, 작업 이름을 붙이고, 시작 ref를 고르고, 에이전트를 선택합니다. Nethür가 백그라운드에서 git fetch와 git worktree add를 실행하고, 생성되는 동안 워크스페이스를 보여 주며, 새 checkout에서 에이전트를 엽니다. worktree 문서에서 시작 ref 선택기, 폴더 워크스페이스, 연결된 이슈를 다룹니다.
의존성, env 파일, 포트
새 worktree는 깨끗한 checkout이므로 git이 무시하는 모든 것이 빠져 있습니다. 처리 방법은 세 가지이고, 대부분의 팀은 결국 세 가지를 모두 씁니다.
- worktree마다 설치합니다. 정확하고 단순하지만, 모든 에이전트에
node_modules가 필요하면 느리고 디스크를 많이 씁니다. - 무겁고 다시 만들 수 있는 directory를 공유합니다. Nethür의 Worktree Shared Paths는 primary checkout의 gitignore된 directory를 materialize하며, 저장소 수준 정의는
nethur.yaml의worktree.sharedDirectories를 씁니다. - 작고 worktree별인 파일을 복사합니다.
.worktreeinclude에.env나 로컬 editor 설정처럼 복사할 gitignore 파일과 directory를 나열해 각 worktree가 자기 복사본을 갖게 합니다.
# nethur.yaml at the repo root
worktree:
sharedDirectories:
- node_modules
- .cache
# .worktreeinclude at the repo root
.env
.env.local
.vscode/settings.json포트에는 별도 규칙이 필요합니다. 두 에이전트가 같은 dev server를 시작하면 두 번째가 실패하거나, 더 나쁘게는 첫 번째의 데이터베이스에 연결됩니다. 포트와 데이터베이스 이름을 worktree별 환경 파일에 넣거나, setup hook이 worktree 이름에서 유도하게 하세요.
diff를 리뷰하고 worktree 제거하기
각 worktree를 지금 main에 있는 것이 아니라 시작한 ref와 비교해 리뷰하세요. 그래야 diff가 에이전트 작업에 집중됩니다. Nethür는 워크스페이스별 diff를 보여 주고, 인라인 주석을 지원하며, commit 전에 리뷰 노트를 에이전트에게 돌려보낼 수 있습니다.
작업이 merge되면 worktree와 branch를 제거하세요. directory를 직접 삭제하지 마세요. git은 .git/worktrees 아래에 metadata를 두므로 수동 rm -rf는 오래된 항목을 남깁니다.
git worktree remove ../app-fix-login
git branch -d fix/login
# if git refuses because the branch has unmerged commits
git worktree remove --force ../app-fix-loginworktree가 사라진 뒤에도 git이 merge되지 않은 commit이 있는 로컬 branch를 남길 수 있습니다. 이는 안전장치이지 버그가 아닙니다. Nethür는 남은 branch를 리뷰 단계에서 보여 주어 나중에 찾아다니지 않고 어떤 branch를 강제 삭제할지 결정하게 합니다.
흔한 worktree 실수
- 같은 branch를 두 worktree에서 checkout합니다. Git이 거부하므로 두 번째 에이전트에는 다른 branch를 고르세요.
- worktree를 저장소 안에 둡니다. 검색과 에디터가 중복 파일을 보고, 그 directory가 commit될 수 있습니다.
- main 데이터베이스를 가리키는
.env하나를 공유합니다. migration이 관련되면 각 에이전트에 자체 데이터베이스나 schema를 주세요. - base ref를 잊습니다. 오래된 로컬 branch에서 만든 worktree는 혼란스러운 diff와 고통스러운 merge를 낳습니다.
- 실험이 끝난 뒤 수십 개의 worktree를 열어 둡니다. 어느 것이 이겼는지 기억할 때 branch를 정리하세요.
팀에서의 worktree
팀 서버에서 worktree는 더 이상 개인 directory가 아닙니다. 공유 프로젝트 상태입니다. 팀원이 worktree가 존재하는지, 누가 만들었는지, 어떤 에이전트가 실행 중인지, 막혀 있는지 볼 수 있습니다. 그 가시성이 작업을 안전하게 넘기는 바탕입니다.
Nethür는 노트북, 팀원 머신, VPS, SSH 대상 어디에서 실행되든 같은 worktree 모델을 유지합니다. 에이전트는 checkout이 있는 곳에서 실행되고 client는 session만 렌더링합니다. 이 설정의 팀 버전을 원한다면 Claude Code for teams를 읽어 보세요.
작업 하나로 시도해 보기
작은 변경을 위해 worktree 하나를 만들고 그 안에서 Claude Code를 실행한 뒤, 옆에 main checkout을 열어 두세요. 두 session이 서로 간섭하지 않는 것을 보면 추가 directory가 부담으로 느껴지지 않습니다. 병렬 에이전트 가이드는 이를 여러 에이전트로 확장하고 결과를 비교하는 방법을 보여 줍니다.



