클로드 코드 worktree 사용법: 병렬 작업 충돌 막고 정리하는 법

클로드 코드 worktree는 세션마다 파일과 브랜치를 따로 주는 격리 작업 폴더로, claude --worktree 이름 한 줄이면 만들어진다(2026년 10월 20일 기준). 터미널 두 개에서 클로드 코드를 동시에 돌려도 서로의 수정이 덮어써지지 않고, 끝낼 때 변경이 없으면 폴더가 자동으로 정리된다.

클로드 코드 worktree가 필요한 경우

한 터미널에서는 로그인 기능을 만들게 하고 다른 터미널에서는 결제 버그를 고치게 했는데, 두 세션이 같은 파일을 건드려 서로의 수정이 뒤섞이는 일이 생긴다. 한 부엌에서 두 요리사가 같은 도마를 쓰는 상황과 같다. 각자 자기 도마를 쓰면 부딪히지 않는 것처럼, worktree는 같은 저장소를 쓰면서도 작업대(폴더)만 따로 준다. 깃의 worktree 기능은 한 저장소의 기록을 공유하는 여러 작업 폴더를 만드는 방식이다. 다만 폴더만 나눌 뿐이라, 두 작업의 결과를 합치는 일(병합)은 나중에 사람이 해야 한다.

클로드 코드 공식 worktree 문서는 worktree를 "자기 파일과 브랜치를 가진 별도 작업 디렉터리이며, 메인 체크아웃과 저장소 기록·원격 저장소를 공유한다"고 설명한다. 세션 하나는 기능을 만들고 다른 세션은 버그를 고치는 식으로 나눠 쓰라는 것이 공식 예시다.

클로드 코드 worktree 시작하는 명령

클로드 코드를 아직 설치하지 않았다면 클로드 코드 설치와 요금제 정리를 먼저 본다. 저장소 폴더에서 이름을 붙여 실행하면 되고, 공식 문서에 따르면 --worktree 대신 -w도 쓸 수 있으며 폴더는 저장소 루트의 .claude/worktrees/<이름>/에 worktree-<이름> 브랜치로 만들어진다.

claude --worktree feature-auth

다른 터미널에서 이름만 바꿔 같은 명령을 실행하면 두 번째 격리 세션이 시작된다. 이름을 생략하면 bright-running-fox 같은 이름이 자동으로 붙는다.

하고 싶은 일	명령
이름을 붙여 시작	claude --worktree feature-auth
풀 리퀘스트(PR) 1234번에서 시작	claude --worktree "#1234"
세션 중에 "worktree에서 작업해 줘"라고 요청	클로드가 EnterWorktree 도구로 생성
특정 기존 브랜치에서 시작	git worktree add ../폴더 브랜치명 후 그 폴더에서 claude

시작 전에 두 가지를 확인한다. 첫째, 공식 작업 흐름 문서는 worktree가 기존 커밋에서 만들어지므로 저장소에 커밋이 최소 하나 있어야 하고, 없으면 Failed to resolve base branch "HEAD" 오류가 난다고 안내한다. 둘째, 해당 폴더에서 클로드 코드를 한 번도 실행한 적이 없으면 인터랙티브 실행은 신뢰 확인 단계에서 오류로 끝나므로, 먼저 claude를 한 번 실행해 허용한다. 공식 문서는 .gitignore에 .claude/worktrees/를 넣어 두라고 권하며, 그러면 worktree 내용이 메인 폴더에서 '추적되지 않는 파일'로 뜨지 않는다.

제대로 만들어졌는지는 git worktree list로 확인한다. 메인 폴더와 .claude/worktrees/feature-auth 두 줄이 보이고 각 줄에 서로 다른 브랜치가 적혀 있으면 성공이다. 직접 해 보려면 두 터미널에서 이름이 다른 worktree를 열어 각각 다른 파일을 하나씩 만들게 한 뒤, 메인 폴더에서 git status를 실행해 두 파일이 모두 보이지 않는지 본다. 보이지 않으면 격리가 된 것이다.

.env 같은 설정 파일 가져오기

worktree는 새로 받은 사본이라 .env처럼 깃에 올리지 않는 파일은 비어 있다. 공식 문서는 프로젝트 루트에 .worktreeinclude 파일을 만들어 복사할 파일을 적으라고 안내한다. 문법은 .gitignore와 같고, 패턴에 맞으면서 동시에 깃이 무시하는 파일만 복사되므로 이미 추적되는 파일이 중복되지는 않는다.

.env
.env.local
config/secrets.json

공식 문서는 worktree가 새 체크아웃이므로 개발 환경을 거기서 다시 준비해야 한다고 안내한다. 클로드에게 의존성 설치를 시키거나 직접 설치 명령을 실행한다. 비밀 값이 든 파일이 새 폴더마다 복사되므로 목록에는 꼭 필요한 파일만 적는 편이 안전하다.

worktree 종료할 때 정리 규칙

세션을 끝내면 클로드 코드가 worktree에 사라지면 곤란한 작업이 있는지 먼저 본다. 공식 정리 규칙은 다음과 같다.

상태	종료 시 동작
변경 없음, 이름 없이 시작한 세션	worktree와 브랜치를 자동 삭제
변경 없음, 이름을 붙인 세션	보존할지 먼저 묻는다
수정·미추적 파일이나 새 커밋이 있음	유지할지 삭제할지 묻는다. 삭제하면 폴더와 브랜치, 그 안의 작업이 함께 사라진다
상태를 확인할 수 없음	자동 삭제하지 않고 묻는다

보존한 worktree로 돌아갈 때는 종료 때 클로드 코드가 출력하는 claude --worktree 이름 --resume 명령을 쓴다. -p 옵션으로 비대화형 실행을 했다면 종료 질문이 없어 worktree가 자동으로 지워지지 않으므로, 직접 git worktree remove 경로로 지운다. 잠겨 있어 git이 거부하면 git worktree unlock을 먼저 실행한다. 정리가 끝났는지는 git worktree list에서 해당 줄이 사라졌는지로 확인한다.

기준 브랜치와 서브에이전트 설정

공식 문서에 따르면 새 worktree는 기본적으로 현재 작업 중인 브랜치가 아니라 저장소 원격의 기본 브랜치(보통 main)에서 시작한다. 아직 push하지 않은 내 커밋 위에서 이어 작업하려면 설정 파일의 worktree.baseRef를 "head"로 둔다. 기본값은 "fresh"이고, 이 설정에는 브랜치 이름을 넣을 수 없다. 특정 브랜치에서 시작하려면 앞의 git worktree add를 쓴다.

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

서브에이전트(한 세션 안에서 일을 나눠 맡는 보조 에이전트)도 worktree를 쓸 수 있다. 클로드에게 "에이전트마다 worktree를 써 줘"라고 하거나, 커스텀 서브에이전트 파일 상단에 isolation: worktree를 적어 항상 격리해서 돌린다. 변경 없이 끝난 서브에이전트의 임시 worktree는 자동으로 지워지고, 변경이 남은 것은 작업을 잃지 않을 때 주기적 정리가 지운다. 서브에이전트 worktree도 기본 브랜치에서 시작하며, 진행 중인 작업 위에서 돌려야 하면 앞의 baseRef를 "head"로 바꾼다.

선택 기준은 이렇다. 터미널을 여러 개 열어 서로 다른 일을 시키면 worktree를 쓰고, 한 세션 안에서 조사나 반복 수정을 나눠 맡기면 서브에이전트를 쓴다. 이 구분은 공식 문서가 worktree는 파일 편집을 격리하고 서브에이전트는 한 세션 안에서 일을 나눈다고 설명한 것에 근거한다. 폴더를 통째로 복사하는 방식은 깃이 worktree처럼 브랜치로 묶어 관리해 주지 않는다.

자주 하는 실수

첫째, 이미 worktree에 들어가 있는 상태에서 메인 폴더 쪽 파일을 고치려 한다. 공식 문서에 따르면 격리 중인 세션은 메인 체크아웃 경로에 대한 편집과 그쪽으로 향하는 git 명령을 막는다. 메인 폴더 작업은 메인 폴더에서 새 세션으로 한다. 둘째, 변경이 남은 worktree를 종료 질문에서 '삭제'로 고른다. 공식 문서는 삭제하면 폴더와 브랜치, 그 안의 작업이 함께 사라진다고 밝히므로, 남길 작업이 있으면 먼저 push하거나 '유지'를 고른다. 셋째, 깃 LFS를 git lfs install --local로 설정한 저장소에서 파일이 포인터 텍스트로만 보인다. 공식 문서는 worktree 안에서 git lfs pull을 실행하라고 안내한다.

세션마다 대화가 따로 쌓이므로 병렬로 돌릴수록 사용량 확인이 필요하다. 클로드 코드 토큰 사용량이 빨리 줄어드는 이유를 알아 두면 병렬 작업의 비용을 가늠하기 쉽고, 계정이 둘이라면 클로드 코드 계정을 세션마다 나눠 쓰는 방법이 도움이 된다. 여러 에이전트에 일을 나누는 구조 자체는 AI 에이전트 오케스트레이션 설계 방법에서 다룬다.

자주 묻는 질문

클로드 코드 worktree는 윈도우에서도 쓸 수 있나요?

쓸 수 있다. 공식 문서에 윈도우 전용 설치 조건은 없고, worktree를 지울 때 NTFS 정션 같은 링크는 링크만 지우고 가리키는 폴더는 남긴다고 안내한다.

git을 안 쓰는 프로젝트에서도 worktree를 쓸 수 있나요?

공식 문서에 따르면 기본 기능은 git 저장소가 필요하다. SVN이나 Mercurial 같은 다른 버전 관리는 WorktreeCreate·WorktreeRemove 훅으로 만들기·정리 로직을 직접 지정해야 하고, 이때 .worktreeinclude는 적용되지 않는다.

같은 이름으로 다시 실행하면 어떻게 되나요?

공식 문서에 따르면 폴더가 이미 있으면 새로 만들지 않고 그 worktree를 연다. 변경이 없고 만든 브랜치 그대로이며 자기 커밋이 없는 등 조건이 맞으면 기본 브랜치 기준으로 초기화되고, 그 밖에는 이전 작업 지점에서 다시 열린다.