Claude Code·Codex를 위한 git worktree 실전 가이드

git worktree로 Claude Code, Codex 등 AI 에이전트를 충돌 없이 각자 브랜치에서 동시에 돌리는 법. 명령어, 준비 팁, 흔한 함정, 정리까지 담았어요.

저장소 하나에서 코딩 에이전트를 둘 이상 돌린다면 git worktree가 꼭 필요해요. 에이전트마다 자기 브랜치, 자기 폴더에서 동시에, 서로 발을 밟지 않고 일할 수 있게 해 주거든요.

git worktree란?

일반적인 클론에는 작업 트리가 하나 있어요. 폴더 하나, 체크아웃된 브랜치 하나죠. worktree는 같은 저장소에 붙은 추가 작업 폴더로, 다른 브랜치가 체크아웃돼 있어요. 모든 worktree가 하나의 .git 히스토리를 공유하기 때문에 어디서 커밋하든 다른 곳에서 바로 보이지만, 파일은 서로 분리돼 있어요.

에이전트 입장에서는 이런 뜻이에요.

Claude Code는 feat/auth 브랜치의 ../atlas-auth에서 파일을 고쳐요
Codex는 feat/search 브랜치의 ../atlas-search에서 파일을 고쳐요
나는 main 브랜치의 메인 폴더에서 계속 리뷰하고 앱을 돌려요

누구도 남의 변경을 덮어쓰지 않아요.

작업마다 worktree 만들기

메인 저장소 폴더에서 실행하세요.

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

그다음 폴더마다 에이전트를 시작해요.

cd ../atlas-auth && claude
cd ../atlas-search && codex

worktree 폴더 이름은 작업 이름으로 지으세요. 한 달 뒤에도 atlas-auth는 뜻이 통하지만 wt2는 아무 의미가 없어요.

Claude Code에게 worktree 만들기를 맡기기

최신 Claude Code는 worktree를 대신 만들어 줘요.

claude --worktree feature-auth   # or: claude -w feature-auth

이 명령은 .claude/worktrees/feature-auth/ 아래에 worktree-feature-auth라는 새 브랜치로 worktree를 만들고, 그 안에서 Claude를 시작해요. 두 번째 터미널에서 다른 이름으로 한 번 더 실행하면 격리된 세션이 하나 더 생겨요. 세션 도중에 Claude에게 "worktree에서 작업해 줘"라고 요청할 수도 있어요.

Claude Code worktree 문서에 나온 몇 가지 세부 사항이에요.

.claude/worktrees/를 .gitignore에 추가하세요. 그래야 메인 체크아웃에서 worktree 파일이 추적되지 않은 파일로 보이지 않아요.
저장소에 커밋이 최소 하나는 있어야 해요.
종료할 때 Claude는 깨끗한 worktree를 지우고(이름을 붙인 worktree는 먼저 물어봐요), 변경이 남은 worktree는 유지할지 물어봐요.
.worktreeinclude 파일에 .env처럼 git이 무시하는 파일을 적어 두면 새 worktree마다 복사돼요.

작업에 Claude Code만 쓴다면 claude --worktree를 쓰세요. 폴더와 브랜치 이름을 직접 정하고 싶거나, Codex나 다른 에이전트를 worktree에서 돌리려면 그냥 git worktree add를 쓰세요.

에이전트를 시작하기 전에 worktree 준비하기

새 worktree에는 git이 추적하는 파일만 들어 있어요. 에이전트에게 넘기기 전에 이것부터 챙기세요.

의존성 설치. node_modules, 가상 환경, 빌드 폴더는 공유되지 않아요. worktree마다 npm install(또는 그에 맞는 명령)을 실행하세요. pnpm처럼 저장소를 공유하는 패키지 매니저를 쓰면 빨라요.
추적되지 않는 설정 복사. .env 파일과 로컬 설정은 보통 git이 무시하니, 앱 실행에 필요한 건 복사해 두세요. claude --worktree를 쓴다면 대신 .worktreeinclude에 적으면 돼요.
포트 나눠 쓰기. 개발 서버 두 개가 동시에 3000번 포트를 쓸 수는 없어요. 두 번째는 PORT=3001 npm run dev처럼 다른 포트로 띄우세요.
지침은 추적되는 파일로 공유. CLAUDE.md와 AGENTS.md는 git에 체크인돼 있으니 모든 worktree가 자동으로 받아요.

리뷰, 머지, 정리

에이전트가 끝나면 이렇게 하세요.

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

worktree 폴더를 직접 지웠다면 git worktree prune으로 남은 항목을 정리하세요.

흔한 함정

"Branch is already checked out." 브랜치 하나는 한 번에 worktree 하나에서만 체크아웃할 수 있어요. worktree마다 새 브랜치를 만드세요.
잊힌 worktree. 오래된 worktree는 브랜치를 붙잡고 디스크도 차지해요. 가끔 git worktree list를 실행하세요.
지울 때 남은 미커밋 변경. worktree에 변경이 있으면 git worktree remove가 거부해요. 먼저 커밋하거나 stash하고, 정말 버리려면 --force를 쓰세요.
메인 폴더를 고치는 에이전트. 에이전트는 저장소 루트가 아니라 각자의 worktree 폴더 안에서 시작하세요.

Vibe Console에서 worktree 쓰기

Vibe Console은 에이전트가 일하는 동안 worktree를 계속 보여줘요.

소스 제어(⌘⇧G)의 Worktree 탭에 모든 worktree가 브랜치와 함께 나오고, 메인 worktree와 detached 체크아웃도 표시돼요.
worktree를 터미널로 드래그하면 경로가 붙여넣어지고, 거기서 ⌘K로 에이전트를 시작할 수 있어요.
작업이 끝나면 Worktree 제거로 정리하고, 로컬 변경이 남아 있으면 강제 제거를 물어봐요. 메인 worktree는 보호돼요.
격자는 터미널을 최대 9개까지 보여주니 worktree마다 에이전트에게 칸을 하나씩 줄 수 있어요. 에이전트 병렬 실행을 참고하세요.

worktree는 위에서 본 git worktree add나 claude --worktree로 만드세요. 어느 쪽이든 바로 목록에 나타나요.

자주 묻는 질문

worktree는 디스크를 많이 차지하나요?

체크아웃된 파일과 그 안에 설치한 것만큼만 차지해요. git 히스토리는 공유돼요.

worktree와 별도 클론 중 뭘 써야 하나요?

worktree예요. 히스토리를 공유하니 브랜치와 커밋이 어디서든 바로 보이고, 정리도 명령 한 줄이면 끝나요.

에이전트 둘이 worktree 하나를 같이 써도 되나요?

파일을 고치는 쪽이 많아야 하나일 때만요. 읽기만 하는 리뷰어 에이전트라면 코드를 쓰는 에이전트와 worktree를 같이 써도 돼요.

14일 동안 무료로 써 보세요: Vibe Console 다운로드.