#TL;DR
git worktree는 하나의 저장소에서 여러 브랜치를 별도 디렉토리로 동시에 체크아웃하는 Git 기본 기능이다. 2015년에 도입된 오래된 기능이지만, Claude Code 같은 AI 코딩 에이전트를 병렬로 실행하는 용도로 다시 주목받고 있다. Claude Code는 --worktree 플래그로 네이티브 지원하며, subagent 격리와 /batch 스킬까지 worktree 기반으로 동작한다.
#git worktree란
Git 저장소는 기본적으로 하나의 워킹 디렉토리만 가진다. 브랜치를 전환하려면 git stash → checkout → 작업 → 다시 checkout → stash pop을 밟아야 하고, 빌드 캐시나 변경 중인 파일이 많으면 전환 자체가 부담이다.
git worktree는 같은 저장소의 다른 브랜치를 별도 디렉토리에 체크아웃하는 기능이다. 각 디렉토리는 독립적인 워킹 트리를 가지지만, .git 폴더(커밋 히스토리, 브랜치 정보, 설정)는 공유한다.
my-project/ ← 메인 워크트리 (main 브랜치)
my-project-payments/ ← 연결된 워크트리 (feature/payments)
my-project-refactor/ ← 연결된 워크트리 (feature/refactor)별도로 git clone하는 것과 비슷해 보이지만, 핵심 차이가 있다. clone은 전체 히스토리를 복제하고 디스크를 두 배로 사용하지만, worktree는 .git 데이터베이스를 공유하므로 추가 디스크 사용이 최소화된다. 한쪽에서 만든 커밋이 다른 쪽에서 즉시 보인다.
#기본 명령어
# 새 브랜치를 만들면서 워크트리 생성
git worktree add ../my-project-hotfix -b hotfix/critical main
# 기존 브랜치로 워크트리 생성
git worktree add ../my-project-payments feature/payments
# 현재 워크트리 목록 확인
git worktree list
# 워크트리 제거
git worktree remove ../my-project-hotfix
# 수동 삭제된 워크트리 정리
git worktree prune#알아두면 좋은 특성
- 같은 브랜치를 두 워크트리에서 동시에 체크아웃할 수 없다. Git이 이를 강제한다. (
--force로 우회 가능하지만 권장하지 않는다.) - stash는 워크트리 간에 공유된다.
.git오브젝트 스토어에 저장되기 때문이다. .gitignore된 파일(node_modules, .env 등)은 워크트리에 복사되지 않는다. 새 워크트리에서는 의존성을 다시 설치해야 한다.- 워크트리는 원본과 연결되어 있다. 별도 clone이 아니므로 브랜치 생성, 커밋 등이 양쪽에서 모두 보인다.
#AI 코딩 에이전트 시대에 왜 다시 주목받는가
git worktree는 Git 2.5(2015년)에 도입됐다. 10년간 “알면 편한 기능” 정도의 위치였는데, 2025~2026년 들어 AI 코딩 에이전트들이 적극적으로 활용하면서 상황이 달라졌다.
#핵심 이유: AI 에이전트는 워킹 디렉토리를 점유한다
Claude Code, Cursor, Codex 같은 AI 코딩 에이전트는 워킹 디렉토리의 파일을 직접 읽고 수정한다. 에이전트가 feature/payments를 작업하는 동안 워킹 디렉토리는 변경 중인 상태다. 이 상태에서 다른 브랜치를 체크아웃하거나, 다른 에이전트 세션을 같은 디렉토리에서 실행하면 충돌이 발생한다.
사람이 작업할 때는 파일을 하나씩 수정하므로 git stash로 충분했다. 하지만 AI 에이전트는 여러 파일을 동시에 수정하고, 작업 시간도 수 분 이상 걸린다. 이 동안 개발자는 기다리기만 해야 한다.
worktree는 이 문제를 해결한다. 에이전트 세션마다 별도 워크트리를 할당하면, 여러 작업을 동시에 진행할 수 있다. 하나의 워크트리에서 에이전트가 작업하는 동안 다른 워크트리에서 완료된 결과를 리뷰하는 흐름이 가능해진다.
“The real power is that while Claude is working in one worktree, you can be reviewing what finished in another. You’re not waiting — you’re directing.”
“Claude가 한 워크트리에서 작업하는 동안, 다른 워크트리에서 완료된 결과를 리뷰할 수 있다. 기다리는 게 아니라 지시하는 것이다.”
#에이전트 생태계 전체의 흐름
이건 Claude Code만의 이야기가 아니다. OpenAI의 Codex CLI도 백그라운드 에이전트를 독립된 샌드박스에서 실행하며, parallel-code 같은 오픈소스 도구는 Claude Code, Codex, Gemini를 각각 별도 워크트리에서 병렬 실행한다. Anthropic의 Boris Cherny(Claude Code 개발자)는 일상적으로 10~15개 워크트리를 동시에 운영한다고 밝힌 바 있다.
“편의 기능”이었던 git worktree가 “병렬 실행 인프라”로 역할이 바뀐 것이다.
#Claude Code의 네이티브 worktree 지원
Claude Code(v2.1.49+)는 worktree를 네이티브로 지원한다. 수동으로 git worktree add를 실행할 필요 없이, --worktree(-w) 플래그 하나로 워크트리 생성부터 세션 시작까지 한 번에 처리된다.
#기본 사용법
# 이름을 지정해서 워크트리 생성 + 세션 시작
claude --worktree feature-auth
# .claude/worktrees/feature-auth/ 디렉토리에 생성
# worktree-feature-auth 브랜치에서 시작
# 이름 자동 생성
claude --worktree
# bright-running-fox 같은 랜덤 이름
# 약어도 가능
claude -w bugfix-123병렬 작업은 터미널을 여러 개 열면 된다.
# 터미널 1: feature 작업
claude -w feature-auth
# 터미널 2: 버그 수정
claude -w bugfix-payment
# 터미널 3: 리팩토링 탐색
claude -w refactor-db각 세션은 완전히 독립적이다. 파일 충돌 없이, 컨텍스트 간섭 없이 병렬로 실행된다.
#워크트리 정리
세션을 종료하면 Claude가 정리 방법을 물어본다.
- 변경 없음: 워크트리와 브랜치가 자동으로 삭제된다.
- 변경 있음: 유지할지 삭제할지 선택할 수 있다. 유지하면 나중에 다시 돌아올 수 있고, 삭제하면 커밋되지 않은 변경과 브랜치가 모두 제거된다.
비정상 종료로 남은 subagent 워크트리는 자동으로 정리된다. --worktree 플래그로 직접 생성한 워크트리는 자동 정리 대상이 아니므로, 사용 후 수동으로 제거하거나 세션 종료 시 정리 옵션을 선택해야 한다.
#.worktreeinclude로 환경 파일 자동 복사
새 워크트리에는 .gitignore된 파일(.env 등)이 복사되지 않는다. 프로젝트 루트에 .worktreeinclude 파일을 만들면 지정한 파일을 자동으로 복사할 수 있다.
# .worktreeinclude (.gitignore 문법 사용)
.env
.env.local
config/master.key#Subagent와 /batch — worktree의 확장
#Subagent worktree 격리
Claude Code의 subagent(하위 에이전트)도 worktree를 사용할 수 있다. 세션 중에 “use worktrees for your agents”라고 요청하거나, 커스텀 subagent의 frontmatter에 isolation: worktree를 설정하면 각 subagent가 독립된 워크트리에서 실행된다.
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Review code changes for quality issues
isolation: worktree
allowed-tools: ['Read', 'Bash']
---
Review the changes in the current branch...#/batch 스킬 — 대규모 병렬 변경
/batch 스킬은 worktree를 대규모로 활용한다. 하나의 큰 작업을 5~30개의 독립 단위로 분해하고, 각 단위마다 별도의 워크트리에서 백그라운드 에이전트를 실행한다. 각 에이전트는 구현, 테스트, PR 생성까지 독립적으로 수행한다.
# 예: src/ 디렉토리를 Solid에서 React로 마이그레이션
/batch migrate src/ from Solid to React실행하면 오케스트레이터가 작업을 분석하고, 예를 들어 src/components/Button, src/pages/Home 같은 단위로 분해한 뒤 각각 별도 워크트리에서 에이전트를 실행한다. 완료되면 각 단위별로 PR이 생성되어 개별 리뷰가 가능하다.
incident.io 팀은 Claude Code의 worktree 병렬 실행으로 API 클라이언트 생성 빌드 시간을 18%(30초) 단축한 사례를 공유했다.
#실전 워크플로우
#기본 패턴: 병렬 개발
# 1. feature 작업 시작
claude -w feature-auth
# 2. 다른 터미널에서 버그 수정
claude -w bugfix-payment
# 3. Claude가 작업하는 동안 완료된 워크트리 리뷰
cd .claude/worktrees/feature-auth
git diff main
# 4. PR 생성 (워크트리 안에서)
git push -u origin feature/auth
gh pr create --title "Add auth module" --base main
# 5. 정리
git worktree remove .claude/worktrees/feature-auth#Writer/Reviewer 패턴
두 세션을 역할 분리해서 사용하는 패턴이다. 한 세션이 기능을 구현하고, 다른 세션이 fresh context로 리뷰한다. 같은 에이전트가 작성한 코드를 리뷰하는 것보다 편향이 적다.
# 터미널 1: 구현
claude -w implement-feature
# 터미널 2: 리뷰 (구현 완료 후)
claude -w review-feature
# "review the changes in ../implement-feature branch"#테스트 주도 패턴
한 세션이 테스트를 먼저 작성하고, 다른 세션이 테스트를 통과하는 코드를 작성한다.
# 터미널 1: 테스트 작성
claude -w write-tests
# 터미널 2: 구현
claude -w implement
# "make all tests in the write-tests branch pass"#주의할 점
#의존성 재설치가 필요하다
워크트리는 .gitignore된 파일을 복사하지 않으므로, node_modules, 가상 환경 등은 새로 설치해야 한다. .worktreeinclude로 .env 파일은 복사할 수 있지만, 대용량 의존성은 직접 설치해야 한다.
#같은 파일을 수정하면 머지 충돌이 발생한다
워크트리 간 파일 격리는 완벽하지만, 결국 브랜치를 머지할 때 같은 파일을 수정했다면 충돌이 생긴다. 이건 워크트리의 문제가 아니라 Git 자체의 동작이다. 각 세션이 수정하는 파일 범위를 분리하는 것이 중요하다.
#워크트리 수에는 실질적 한계가 있다
Git은 워크트리 수를 제한하지 않지만, 각 워크트리에서 Claude Code 세션을 실행하면 CPU와 메모리를 소비한다. 실무적으로는 3~5개가 적정선이고, 그 이상은 CI/CD나 에이전트 오케스트레이션으로 넘기는 것이 맞다.
#알림 설정을 함께 사용하라
워크트리를 여러 개 돌리면 어느 세션이 끝났는지 추적이 어렵다. Claude Code의 Notification 훅을 설정하면 세션이 완료되거나 입력이 필요할 때 알림을 받을 수 있다.
macOS에서 CLI 알림에 널리 사용되는 terminal-notifier를 설치하면 된다.
brew install terminal-notifier.claude/settings.json에 다음을 추가한다.
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "terminal-notifier -title 'Claude Code' -message '$CLAUDE_NOTIFICATION'"
}
]
}
]
}
}#stash vs clone vs worktree
| 항목 | git stash + checkout | git clone | git worktree |
|---|---|---|---|
| 디스크 사용 | 최소 | 전체 복제 | 최소 (공유) |
| 히스토리 공유 | 동일 저장소 | 별도 복사본 | 동일 저장소 |
| 병렬 작업 | 불가 | 가능 | 가능 |
| AI 에이전트 병렬 실행 | 불가 | 가능하지만 비효율 | 최적 |
| 커밋 즉시 공유 | 해당 없음 | push/pull 필요 | 즉시 |
| Claude Code 네이티브 지원 | 없음 | 없음 | --worktree 플래그 |
clone으로도 병렬 실행은 가능하지만, 저장소를 통째로 복제하므로 디스크를 배로 사용하고 커밋 공유에 push/pull이 필요하다. worktree는 이 오버헤드 없이 같은 결과를 얻는다.
git worktree는 10년 된 기능이지만, AI 코딩 에이전트와 만나면서 비로소 본래의 가치를 발휘하고 있다. claude -w task-name 한 줄이면 병렬 개발 환경이 준비된다.
#참고 자료
- Claude Code Docs — Common Workflows: Git Worktrees — 공식 문서의 worktree 섹션
- Botmonster — CLAUDE.md Productivity Stack: Skills, Git Worktrees, and Hooks — worktree + CLAUDE.md + hooks + skills 전체 스택 가이드
- Dan Does Code — Parallel Vibe Coding: Using Git Worktrees with Claude Code — VS Code 연동, PR 워크플로우, 충돌 처리까지 상세 가이드
- incident.io — Shipping Faster with Claude Code and Git Worktrees — API 생성 빌드 시간 18% 단축 사례
- Threads — Boris Cherny: Introducing built-in git worktree support for Claude Code — Claude Code 개발자의 공식 발표
- GitHub — parallel-code: Run Claude Code, Codex, and Gemini side by side — 여러 AI 에이전트를 worktree별로 병렬 실행하는 오픈소스 앱
- Git 공식 문서 — git-worktree