클로드 코드 워크트리 — 세션 여러 개 동시에 돌리기
클로드 코드를 두 개 이상 동시에 돌리면 같은 파일을 서로 덮어쓰는 사고가 납니다. 이걸 막는 게 워크트리입니다. claude --worktree 이름(줄여서 -w)으로 켜면 저장소 안에 .claude/worktrees/이름/ 폴더와 worktree-이름 브랜치가 만들어지고, 그 세션은 거기서만 파일을 고칩니다. 커밋 기록과 원격은 원래 저장소와 그대로 공유하므로 나중에 합치기도 쉽습니다. 아래에 만드는 법, 끝난 뒤 정리, 그리고 워크트리를 지워도 브랜치가 남는 함정까지 실제 출력과 함께 정리했습니다. (2026년 8월 2일 기준 · CLI 2.1.204)
1. 워크트리가 뭔가 — 폴더 하나 더 만드는 것
깃의 워크트리는 같은 저장소를 보면서 작업 폴더만 하나 더 두는 기능입니다. 저장소를 통째로 다시 받는 clone과 다릅니다. 커밋 기록·원격 주소는 하나를 같이 쓰고, 폴더와 브랜치만 따로 갖습니다.
확인해 보면 워크트리 폴더의 .git은 폴더가 아니라 파일 한 개이고, 그 안에 본체를 가리키는 줄이 들어 있습니다.
$ cat wt-a/.git
gitdir: /경로/myrepo/.git/worktrees/wt-a그래서 워크트리 안에서 git commit을 해도 본체의 .git에 기록됩니다. 커밋이 따로 노는 게 아닙니다.
2. 클로드 코드에서 쓰기 — claude --worktree
claude --worktree feature-auth이러면 .claude/worktrees/feature-auth/가 만들어지고 worktree-feature-auth 브랜치로 세션이 시작됩니다. 다른 터미널에서 이름만 바꿔 한 번 더 실행하면 두 번째 세션이 완전히 분리된 폴더에서 돕니다. 이름을 생략하면 bright-running-fox 같은 이름을 알아서 지어 줍니다.
실제로 돌려 보면 목록에 이렇게 잡힙니다. 세션이 도는 동안에는 locked가 붙어 다른 정리 작업이 건드리지 못합니다.
$ git worktree list
/경로/myrepo 59d95be [main]
/경로/myrepo/.claude/worktrees/demo-wt 59d95be [worktree-demo-wt] locked.claude/worktrees/를 .gitignore에 넣어 두세요. 안 그러면 본체 저장소에서 워크트리 안 파일들이 전부 "추적되지 않은 파일"로 뜹니다.
세션 중에 "워크트리에서 작업해 줘"라고 말로 시켜도 됩니다. 그때는 클로드가 직접 워크트리를 만들어 그리로 옮겨 갑니다.
3. 처음 시작할 때 걸리는 것 두 가지
첫째, 신뢰 확인입니다. 그 폴더에서 클로드 코드를 한 번도 안 켰다면 --worktree가 오류를 내고 끝납니다. 먼저 claude를 한 번 실행해 신뢰 대화상자를 통과시켜 두세요. (-p로 돌리는 비대화형 실행은 이 확인을 건너뜁니다)
둘째, 워크트리는 새 체크아웃이라 .env 같은 파일이 없습니다. 깃이 무시하는 파일은 따라오지 않기 때문입니다. 매번 복사하기 번거로우면 프로젝트 루트에 .worktreeinclude 파일을 만들어 두면 됩니다. .gitignore와 같은 문법으로 적고, 깃이 무시하는 파일 중 여기 적힌 것만 새 워크트리로 복사됩니다.
.env
.env.local
config/secrets.json4. 어느 브랜치에서 갈라지나
기본값은 원격의 기본 브랜치(보통 main)입니다. 지금 내 작업 상태가 아니라 깨끗한 상태에서 시작한다는 뜻입니다. 지금 하던 작업 위에서 갈라지게 하려면 설정에서 worktree.baseRef를 바꿉니다.
| 값 | 어디서 갈라지나 |
|---|---|
"fresh" (기본) |
원격의 기본 브랜치. 내 미푸시 커밋은 안 따라옵니다 |
"head" |
지금 내 HEAD. 작업 중인 브랜치 상태를 그대로 가져갑니다 |
이 설정에 브랜치 이름은 못 넣습니다. 특정 브랜치에서 시작하고 싶으면 아래 6번처럼 깃으로 직접 만들면 됩니다. PR에서 갈라지고 싶을 때는 번호 앞에 #을 붙여 넘깁니다(셸이 주석으로 읽지 않게 따옴표로 감쌉니다).
claude --worktree "#1234"5. 끝나면 어떻게 정리되나
대화형 세션을 끝내면 클로드가 그 워크트리에 남길 만한 작업이 있는지(고친 파일·새 파일·새 커밋) 먼저 봅니다.
- 깨끗하면 — 이름 없이 만든 세션은 워크트리와 브랜치를 자동으로 지웁니다. 이름을 준 세션은 지울지 물어봅니다.
- 작업이 남아 있으면 — 남길지 지울지 물어봅니다. 지우면 그 안의 작업도 같이 사라집니다.
-p로 돌린 비대화형 실행은 종료 질문이 없어서 워크트리가 그대로 남습니다. 실제로 돌려 보니 실행이 끝난 뒤에도 목록에 남아 있었습니다. 스크립트로 돌린다면 git worktree remove로 직접 치워야 합니다.
6. 깃 명령으로 직접 다루기
특정 브랜치를 열어 보거나 저장소 바깥에 두고 싶을 때는 깃으로 만듭니다.
# 있는 브랜치를 워크트리로
$ git worktree add wt-a feature-a
Preparing worktree (checking out 'feature-a')
# 새 브랜치를 만들면서
$ git worktree add -b hotfix wt-hotfix
Preparing worktree (new branch 'hotfix')
# 목록
$ git worktree list
# 삭제
$ git worktree remove wt-a여기서 자주 막히는 지점이 같은 브랜치를 두 곳에서 열 수 없다는 것입니다. 이미 열려 있는 브랜치를 또 워크트리로 만들려고 하면 이렇게 거부합니다.
fatal: 'main' is already checked out at '/경로/myrepo'고친 파일이 남아 있는 워크트리도 그냥은 안 지워집니다. 메시지가 방법까지 알려 줍니다.
fatal: 'wt-a' contains modified or untracked files, use --force to delete it7. 놓치기 쉬운 함정 — 브랜치는 남는다
워크트리를 지워도 그 워크트리가 쓰던 브랜치는 저장소에 그대로 남습니다. 폴더만 없어질 뿐입니다. 몇 번 반복하면 worktree-… 브랜치가 수북이 쌓이니, 다 쓴 브랜치는 따로 정리하세요. 지우는 방법은 git 브랜치 삭제에 로컬·원격을 나눠 정리해 뒀습니다.
또 하나, 탐색기나 rm으로 폴더만 지우면 목록에서 안 사라집니다. 이렇게 prunable이라고 표시된 채 남습니다.
$ git worktree list
/경로/myrepo 59d95be [main]
/경로/myrepo/wt-hotfix 59d95be [hotfix] prunable
$ git worktree prune # 이걸 돌려야 목록에서 없어진다8. 서브에이전트도 워크트리에 가둘 수 있다
여러 에이전트가 동시에 파일을 고치면 서로 충돌합니다. 커스텀 서브에이전트 파일의 머리말에 isolation: worktree 한 줄을 넣으면 그 에이전트는 항상 자기 워크트리에서만 일합니다.
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---이렇게 만들어진 워크트리는 작업이 끝나고 변경이 없으면 자동으로 지워지고, 변경이 남았으면 정리 대상에서 빠집니다. 서브에이전트 자체를 만드는 법은 클로드 서브에이전트 사용법에 정리해 뒀습니다.
자주 묻는 질문 (FAQ)
Q. 저장소를 두 번 clone 하는 것과 뭐가 다른가요?
디스크와 기록이 하나로 묶입니다. clone은 커밋 기록을 통째로 복사하고 원격도 따로 잡히지만, 워크트리는 .git을 공유해서 한쪽에서 만든 커밋을 다른 쪽에서 바로 볼 수 있습니다.
Q. 워크트리 안에서 만든 변경은 어떻게 합치나요?
평소처럼 커밋하고 푸시한 뒤 PR을 올리면 됩니다. 브랜치가 본체 저장소에 그대로 있으므로 특별한 절차가 없습니다.
Q. 세션을 이어서 하면 워크트리로 돌아가나요?
돌아갑니다. --continue·--resume 모두 원래 있던 워크트리에서 다시 시작합니다. 다만 --fork-session으로 갈라내면 처음 실행했던 폴더에서 시작합니다.
Q. 깃을 안 쓰는 저장소에서도 되나요?
기본 기능은 깃 전용입니다. 다른 버전 관리 도구를 쓴다면 WorktreeCreate 훅으로 만드는 로직을 직접 대체해야 합니다.
마무리
정리하면 claude --worktree 이름 하나로 세션마다 독립된 작업 폴더를 얻습니다. 시작 전에 .claude/worktrees/를 .gitignore에 넣고, .env가 필요하면 .worktreeinclude에 적어 두세요. 그리고 정리할 때는 폴더를 지웠다고 끝이 아니라 git worktree prune과 브랜치 삭제까지 해야 저장소가 깔끔하게 남습니다.
📚 참고 출처 (2026년 8월 2일 확인)
· Claude Code — Run parallel sessions with worktrees
· git — git-worktree
· 본문의 명령 출력은 임시 저장소를 만들어 Claude Code 2.1.204와 git으로 직접 실행해 확인했습니다.
COMMENTS