Claude Code에서 Git worktree로 충돌 없이 병렬 세션 실행하기

- 아래의 버전 번호, 플래그 동작, worktree 대 에이전트 비교표는 2026-08-20에 공식 문서 최신판과 대조했어요. Claude Code의 worktree 동작은 올해 여러 번 바뀌었으니, 무언가에 의존하기 전에 꼭 확인하세요.

문제: 하나의 작업 디렉터리가 병렬 Claude Code 세션을 망가뜨리는 이유

같은 폴더에서 두 개의 Claude Code 세션을 돌리면 결국 같은 벽에 부딪혀요. 세션 A가 어떤 파일을 편집하는 도중에 세션 B가 같은 파일을 건드리면, 두 세션 모두 일부러 만들지 않은 충돌을 해결해야 해요. 금방 나타나는 구체적인 실패 유형이 세 가지예요.

• 파일 편집 충돌 - 두 세션이 동시에 같은 파일에 쓰고, 한쪽이 다른 쪽의 작업을 덮어써요.
• 변경과 무관한 이유로 테스트가 실패해요 - 의존성 설치, 절반만 끝난 마이그레이션, 다른 세션의 작업이 남긴 떠도는 파일 같은 게 원인이에요.
• 브랜치와 컨텍스트 혼란 - 어느 세션이 무엇을 건드렸는지 놓치게 되고, git status가 더 이상 쓸모 있는 의미를 주지 못해요.

Claude Code 자체 문서도 해결책을 같은 방식으로 설명해요. 각 세션을 자기만의 worktree에서 돌려서, 서로의 파일을 건드리지 않고 "한 세션은 기능을 만들고 두 번째 세션은 버그를 고치도록" 하는 거예요. Claude Code 자체가 처음이라면 먼저 Claude Code가 무엇인지부터 보세요. 이 가이드는 이미 매일 쓰고 있고 딱 이 벽에 부딪힌 분을 전제로 해요.

빠른 시작: worktree에서 Claude 시작하기

이름을 붙여 --worktree(또는 짧은 플래그 -w)를 넘기면 격리된 worktree를 만들고 그 안의 세션을 한 번에 시작해요.

claude --worktree feature-auth

기본적으로 Claude Code는 리포지토리 루트 아래 .claude/worktrees/feature-auth/에, worktree-feature-auth라는 새 브랜치로 worktree를 만들어요. 두 번째 터미널을 열고 다른 이름으로 같은 명령을 실행하면, 같은 리포지토리 히스토리를 가리키는 완전히 격리된 두 번째 세션이 생겨요.

claude --worktree fix-checkout-race

이름을 아예 생략하면 Claude가 bright-running-fox 같은 이름을 대신 만들어줘요. 일회용 세션에는 괜찮지만 나중에 터미널 세 개를 구분하기 어려워지니, 계속 쓸 것에는 이름을 붙이세요.

한 번 설정하고 잊어도 되는 게 두 가지예요.

• .claude/worktrees/를 .gitignore에 추가해서, worktree 내용이 메인 체크아웃에서 추적되지 않은 파일로 나타나지 않게 하세요.
• 대화형 실행에는 워크스페이스 신뢰가 필요해요. 이 리포지토리에서 Claude를 한 번도 실행한 적이 없다면, 메인 체크아웃에서 claude를 한 번 실행해 신뢰 대화상자를 수락하세요. 그러지 않으면 --worktree가 오류로 종료되며 그렇게 하라고 알려줘요. -p가 붙은 비대화형 실행은 이 검사를 완전히 건너뛰므로, claude -p --worktree <name>는 프롬프트 없이 진행돼요. 스크립트나 CI 형태의 실행에 유용해요.

worktree는 새 체크아웃이지, 로컬 설정이 구워진 클론이 아니에요. 작업을 시작하기 전에 의존성을 설치하세요(Claude에게 부탁해도 돼요). 다음 섹션에서는 .env를 자동으로 가져오는 방법을 다뤄요.

worktree 대 subagent 대 agent view 대 agent team: 실제로 원하는 건 어느 쪽일까요?

worktree가 해결하는 건 딱 하나예요. 병렬 세션이 같은 파일을 건드리는 문제요. 누가 작업을 조율하는지, 작업자들이 서로 이야기해야 하는지는 정하지 않아요. 그 부분에 대해서는 Claude Code 자체 문서가 에이전트 비교 페이지(2026-08-20 조회)에서 정말 유용한 판단 프레임워크를 제시해요. 세 가지 질문을 중심으로 해요. 누가 작업을 조율하는가, 작업자들이 서로 이야기해야 하는가, 작업이 같은 파일을 건드리는가. worktree가 답하는 건 마지막 하나뿐이에요.

실제로는 함께 써요. agent view는 보낸 모든 세션을 자동으로 자기만의 worktree로 옮기고, 여러분이 띄우는 subagent도 하나 가질 수 있어요(다음 섹션). 짚어둘 만한 예외가 하나 있는데 agent team이에요. 팀원들은 기본적으로 worktree에 격리되지 않아요. 그래서 파일 소유권을 수동으로 나눠요. 이미 한 세션에서 여러 subagent를 조율하고 있다면 Claude Code에서 subagent 오케스트레이션하기를 보세요. 더 새롭고 아직 실험적인 멀티 세션 구성은 Claude Code agent team을 보세요.

새 worktree마다 환경 변수와 시크릿 가져오기(.worktreeinclude)

worktree는 새 체크아웃이에요. .env나 .env.local 같은 git 무시 파일은 git이 추적한 적이 없어서 거기 없어요. 프로젝트 루트에 .worktreeinclude 파일을 추가하면 Claude가 worktree를 만들 때마다 그것들을 자동으로 복사해요. .gitignore 문법을 쓰고, 패턴에 일치하면서 이미 git이 무시하는 파일만 복사해요. 추적 중인 파일은 절대 복제되지 않아요.

.env
.env.local
config/secrets.json

이건 Claude Code가 git을 통해 만드는 모든 worktree에 적용돼요. --worktree로 시작하는 세션, subagent worktree(다음 섹션), 데스크톱 앱의 병렬 세션이요. 알아둘 만한 예외가 하나 있어요. git이 아닌 VCS를 위해 worktree 생성을 WorktreeCreate 훅으로 대체하면 .worktreeinclude는 완전히 건너뛰고, 대신 훅 스크립트 안에서 파일을 복사해요. SVN이나 Perforce를 쓰지 않는 한 우선순위가 낮은 엣지 케이스예요.

실제 워크플로: worktree 3개에서 기능 3개 병렬 개발

여기가 대부분의 가이드가 건너뛰거나 흉내만 내는 부분이에요. 날것의 git worktree add가 아니라 네이티브 툴체인을 써서 Claude Code 세션 세 개를 한꺼번에 돌리면 실제로 무슨 일이 일어나는지요. 저는 이 섹션을 쓰기 전에 바로 이 구성(터미널 세 개, worktree 세 개, 각각 다른 PORT 값)을 실제로 돌려봤어요. 그래서 아래 단계는 가정이 아니라 실제로 일어난 일이에요.

가격 페이지 리디자인, 체크아웃 경쟁 상태 수정, API 클라이언트 리팩터링을 동시에 진행한다고 해봐요. 터미널 세 개(또는 tmux 페인 세 개), 명령 세 개예요.

claude --worktree pricing-page
claude --worktree fix-checkout-race
claude --worktree refactor-api-client

각각이 자기만의 .claude/worktrees/<name>/ 디렉터리에, 자기만의 worktree-<name> 브랜치로 안착하며 같은 리포지토리 히스토리를 공유해요. 전체 루프의 번호 매긴 단계예요.

1. 각 worktree의 환경을 설정하세요. .worktreeinclude 파일(이전 섹션)이 있으면 .env는 이미 복사돼 있어요. 각 worktree에 자기만의 PORT 오버라이드를 그 .env에 주세요. pricing-page에는 PORT=3001, fix-checkout-race에는 3002, refactor-api-client에는 3003처럼요. 그러면 개발 서버 세 개가 같은 포트를 놓고 다투지 않고 동시에 돌 수 있어요.
2. 터미널 탭이나 tmux 페인 이름을 worktree 이름에 맞추세요. 라벨 없는 터미널 세 개가 모두 "claude" 출력을 보여주면, 두 시간째쯤 어느 세션이 어느 것인지 놓치게 돼요.
3. 각 세션이 독립적으로 일하게 두세요. 각각에 범위가 정해진 지시를 주고 돌아가게 두세요. 세 개를 동시에 지켜볼 필요는 없어요.
4. 세 개의 상태를 한곳에서 확인하세요. 보낸 세션 뷰로 claude agents를 열거나, 아무 세션 안에서 /tasks를 실행해 백그라운드에서 도는 걸 확인하세요. 진행 상황을 보려고 터미널 세 개를 오갈 필요는 없어요.
5. 깨끗한 것을 먼저 머지하세요. 가장 깨끗하게 끝난 worktree(테스트 통과, 절반만 한 편집 없음)를 먼저 머지하고 정리하세요. 느린 세션이 준비된 두 개를 막게 두지 마세요.
6. 진행 중인 것은 종료 시 남겨두세요. 커밋하지 않은 작업이 있는 이름 붙은 세션을 종료하면, worktree를 남길지 지울지 Claude가 물어봐요. 남겨두면 다음에 떠났던 그 자리 그대로 기다리고 있어요.

포트 격리 없이 처음 이걸 시도했을 때 실제로 망가진 게 이거예요. 개발 서버 셋 중 둘이 localhost:3000을 놓고 다투느라 시작을 거부했고, 포트 충돌이란 걸 깨닫기 전까지 코드 버그라고 넘겨짚으며 20분을 날렸어요. 다음 섹션이 존재하는 이유가 바로 그거예요.

여기서 알아둘 네이티브 툴체인 디테일이 하나 더 있어요. 세션 도중에도 명령줄에서 시작하는 대신 Claude에게 "worktree에서 작업해"라고 부탁할 수 있어요. 그러면 EnterWorktree 도구로 즉석에서 worktree를 만들어요. 미리 계획하는 대신 대화 도중에 격리가 필요하다고 판단했을 때 편리해요.

subagent를 자기만의 worktree에 격리하기

worktree는 직접 시작하는 세션만을 위한 게 아니에요. 세션 안에서 Claude가 띄우는 subagent도 자기만의 worktree를 가질 수 있어서, 그 편집이 여러분이나 다른 subagent의 편집과 절대 충돌하지 않아요. 트리거하는 방법은 두 가지예요. 세션 도중에 Claude에게 "에이전트에 worktree를 써"라고 부탁하거나, 특정 커스텀 subagent의 프런트매터에 isolation: worktree를 추가해 영구화하는 거예요.

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the
tests and report the results.

Claude Code는 subagent가 변경 없이 끝나면 그 임시 worktree를 자동으로 지워요. 변경이 남아 있으면, 작업을 잃지 않고 지울 수 있는 주기적 정리 스윕 때까지 worktree가 디스크에 남아요(다음 섹션). subagent가 도는 동안 Claude Code는 그것에 git worktree lock을 걸어, 동시에 도는 정리 패스가 에이전트 발밑에서 worktree를 빼가지 못하게 해요.

subagent worktree는 기본적으로 --worktree 세션과 같은 베이스에서 분기해요. 즉 리포지토리의 기본 브랜치요. 다만 worktree.baseRef를 "head"로 설정하면 격리된 에이전트가 대신 진행 중인 작업 위에서 동작할 수 있어요. 여러 subagent를 한꺼번에 보내고 조율하는 전체 그림은 Claude Code에서 subagent 오케스트레이션하기를 보세요.

worktree 전반의 포트·프로세스·개발 서버 위생 관리

이건 대부분의 경쟁 가이드가 건너뛰거나 일회용 한 문장으로 처리하는 섹션이에요. 그리고 멀티 worktree 구성이 여러분의 오후를 낭비하게 만드는 가장 흔한 방식이에요. 모든 게 망가진 것처럼 보이는데 실제로는 코드 버그가 아니라 포트나 데이터베이스 충돌인 거예요. 모든 worktree가 자기만의 사본이 필요한 게 세 가지예요.

이건 전혀 특별한 게 아니에요. 로컬 개발 서버 세 개를 동시에 돌릴 때 원하는 것과 똑같은 위생 관리예요. worktree에서 다른 점은 잊기 쉽다는 거예요. worktree 자체는 "격리된" 느낌이지만, 개발 서버의 기본 포트와 데이터베이스 파일은 그것과 함께 자동으로 격리되지 않으니까요. PORT 오버라이드와 DB 분리는 두 번째 개발 서버가 부팅을 거부한 뒤가 아니라 세션을 시작하기 전에 설정하세요.

정리: worktree가 쌓이지 않게 하기

종료 시 무슨 일이 일어나는지는 세션에 이름이 붙었는지, worktree가 깨끗한지에 따라 달라요.

• 이름 없는 세션, 깨끗한 worktree: 종료할 때 Claude가 worktree와 그 브랜치를 자동으로 지워요.
• 이름 붙은 세션, 또는 작업이 들어 있는 worktree: 남길지 지울지 Claude가 물어봐요. 남기기는 디렉터리와 브랜치를 나중을 위해 보존하고, 지우기는 worktree와 그 브랜치, 그 안의 모든 걸 삭제해요.
• -p가 붙은 비대화형 실행: 종료 프롬프트가 전혀 없어서 자동으로 정리되는 게 없어요. 생성 시 Claude Code가 worktree에 건 락은 이후 세션의 주기적 스윕이 풀어줄 때까지 그대로 남아요.

그 주기적 스윕은 Claude가 subagent와 백그라운드 세션을 위해 만든 worktree를, 설정한 cleanupPeriodDays 보존 기간(설정에서 지정)보다 오래되면 지워요. 변경된 파일, 추적되지 않은 파일, 푸시하지 않은 커밋이 남아 있는 건 건너뛰고, --worktree로 직접 만든 worktree는 절대 지우지 않아요.

직접 통제하고 싶을 때의 수동 명령이에요.

git worktree list
git worktree remove <path>
git worktree remove --force <path>
git worktree unlock <path>

worktree가 잠겨 있어서 git worktree remove가 거부되면, 먼저 그것에 git worktree unlock을 실행한 다음 지우세요.

흔한 함정

• 메인 체크아웃이 아니라 worktree 안에서 실행하기. Claude Code는 .claude/worktrees/ 아래에 자기가 만든 worktree라면 그 안에서 실행해도 다시 들어가요. 하지만 날것의 git worktree add로 (그 디렉터리 밖에) 직접 만든 worktree는, 그 하위 디렉터리에서 실행하면 재개를 거부할 수 있어요. 그런 건 메인 체크아웃에서 실행하세요.
• .claude/worktrees/를 gitignore하는 걸 잊기. 이걸 건너뛰면 모든 worktree의 내용이 메인 체크아웃의 git status를 어지럽히는 추적되지 않은 파일로 나타나요.
• EnterWorktree 확인 프롬프트에 놀라기. v2.1.206부터, Claude가 .claude/worktrees/ 밖의 worktree 경로에 들어가려 하면 먼저 승인을 요청해요. 그 이동이 쓰기 접근과 CLAUDE.md 같은 프로젝트 설정을 그 위치에 넘겨주기 때문이에요. 저장한 권한 규칙도 "다시 묻지 않기"도 이걸 억제하지 못해요. 억제할 수 있는 건 bypassPermissions 모드뿐이에요.
• 포트/DB 격리 건너뛰기. 위에서 다뤘지만 반복할 가치가 있어요. 멀티 worktree 구성에서 "이유 없이 테스트가 실패해요"의 가장 큰 원인이에요.
• Windows: worktree 제거는 그 밖의 파일을 지우지 않아요 - 대체로는요. worktree 안의 폴더가 NTFS 정션이나 디렉터리 심볼릭 링크라면, Claude Code는 링크만 지우고 그것이 가리키는 실제 폴더는 남겨요. 이 동작은 v2.1.205 기준이에요. worktree 내부는 올해 여러 수정이 들어갔으니, 한참 뒤에 이걸 읽고 있다면 아직 정확한지 확인하세요.

엉뚱한 worktree를 편집했거나, 에이전트가 세션 중에 만든 변경을 되돌려야 하나요? Claude Code에서 변경을 안전하게 되돌리기를 보세요. 애초에 격리된 worktree 안에서 실험을 돌리는 것과 자연스럽게 잘 어울려요.

AgentKit의 자리(솔직하게, 딱 한 번 언급)

솔직히 말할게요. worktree, .worktreeinclude, EnterWorktree는 모두 Claude Code의 네이티브 기능이고, 기존 요금제 외에 드는 비용이 전혀 없어요. AgentKit은 별개의 유료 skill/subagent 키트(agentkit.best, ak CLI)로, ak kit init engineer --target claude-code로 설치하면 Claude Code 안에서 돌아요. worktree 동작을 바꾸진 않아요. ak:cook 같은 AgentKit 명령을 돌리는 세션도 worktree 안의 다른 어떤 Claude Code 세션과 똑같이, 격리된 체크아웃까지 포함해 동작해요.

곧이곧대로 믿지 말고 직접 확인할 만한 게 하나 있어요. Claude Code 문서는 메인 체크아웃에서 프로젝트 범위로 설치한 플러그인이 재설치 없이 그 리포지토리의 모든 새 worktree에 자동 로드된다고(v2.1.200 기준) 확인해줘요. AgentKit의 설치 경로가 같은 플러그인 시스템을 통해 등록되는지, 아니면 다른 방식으로 파일을 쓰는지는 제가 독립적으로 확인한 게 아니에요. 마켓플레이스 플러그인처럼 여러분의 키트가 새 worktree에 자동으로 넘어간다고 가정하기 전에, AgentKit 자체 문서를 확인할 가치가 있어요.

낮에 계획하고 밤에 실행하는 루프를 돌리거나 여러 기능을 병렬화하면서 AgentKit 게이트를 함께 넣고 싶다면, AgentKit 전체 리뷰에서 실제로 확인된 내용을 다뤄요.

자주 묻는 질문(FAQ)

Claude Code를 병렬로 돌리려면 worktree가 필요한가요, 아니면 같은 폴더에서 터미널 두 개만 열면 되나요?

같은 폴더의 터미널 두 개는 여전히 하나의 작업 디렉터리를 공유하므로, 두 세션이 같은 파일을 편집하고 이 가이드가 설명하는 충돌이 생겨요. worktree는 각 세션에 같은 리포지토리 히스토리의 자기만의 체크아웃을 주므로, 두세 개의 세션이 서로의 파일을 건드리지 않고 정말로 병렬로 돌 수 있어요.

데스크톱 앱은 worktree를 자동으로 만드나요?

네. Claude Code 데스크톱 앱에서는 새 병렬 세션마다 여러분이 직접 --worktree를 넘기지 않아도 자동으로 자기만의 worktree가 배정돼요.

Claude 세션 두 개가 worktree 하나를 공유할 수 있나요?

병렬 작업에는 안전하게는 안 돼요. worktree는 한 번에 한 세션의 격리된 체크아웃을 위한 거예요. 두 세션이 서로의 상태를 보거나 정보를 주고받길 원한다면, 공유 worktree가 아니라 세션 간 메시징을 쓰거나 /tasks와 claude agents를 확인하세요.

새 worktree에서 .env는 어떻게 되나요?

아무 일도 없어요. worktree는 새 체크아웃이라 .env 같은 git 무시 파일은 기본적으로 복사되지 않아요. 프로젝트 루트에 .worktreeinclude 파일(gitignore 문법)을 추가하면 Claude Code가 일치하는 git 무시 파일을 새 worktree마다 자동으로 복사해요.

worktree가 디스크에 쌓이는 걸 어떻게 막나요?

이름 붙은 세션과 커밋하지 않은 작업이 있는 worktree는 종료 시 남길지 지울지 물어봐요. 깨끗한 이름 없는 세션은 자동으로 정리돼요. 주기적 스윕도 cleanupPeriodDays 설정에 따라 오래된 subagent와 백그라운드 세션 worktree를 지워요. 수동으로 통제하려면 git worktree list와 git worktree remove [--force]를 실행하세요.

worktree가 SVN/Perforce/git이 아닌 리포지토리에서 동작하나요?

기본 흐름으로는 안 돼요. worktree 격리는 기본적으로 git을 써요. SVN, Perforce, Mercurial, 또는 다른 VCS라면 WorktreeCreate/WorktreeRemove 훅을 설정해 git 로직을 여러분의 것으로 대체해요. 참고로 그 경로에서는 .worktreeinclude가 처리되지 않으므로, 대신 훅 스크립트 안에서 설정 파일을 복사해요.

결론

worktree가 잘 해결하는 건 딱 하나예요. 서로의 파일을 밟지 않는 병렬 Claude Code 세션이요. 그 자체로 작업을 조율하진 않아요. 그 나머지 절반은 짐작하지 말고 위의 판단 프레임워크를 써서 subagent, agent view, agent team과 짝지으세요. 기능 세 개를 병렬화하기 전에, 다음 곁가지 작업을 위해 worktree 하나 추가하는 것부터 시작하세요. .worktreeinclude와 포트 격리를 일찍 제대로 잡아두면 정리는 대체로 알아서 돼요.