Git worktree는 하나의 저장소 히스토리를 공유하면서 여러 브랜치를 서로 다른 디렉터리에 체크아웃하는 기능이다. AI 코딩 에이전트를 병렬로 돌릴 때 각 에이전트에 별도 worktree를 주면 파일 충돌과 브랜치 전환으로 인한 컨텍스트 손실을 크게 줄일 수 있다.
왜 clone보다 낫나
여러 clone을 만들면 디스크 사용량이 늘고, 한 clone의 커밋을 다른 clone에서 바로 보기 어렵고, 공통 상태를 사람이 따로 맞춰야 한다. worktree는 .git 객체 저장소를 공유하므로 히스토리는 하나지만 작업 디렉터리와 index는 분리된다.
my-project/ # main
my-project-feat-auth/ # feat/auth
my-project-feat-api/ # feat/api
my-project-hotfix-login/ # hotfix/login각 디렉터리에서 실행한 Claude Code, Codex, Cursor는 자기 브랜치 파일만 본다.
기본 명령
git worktree add -b feat/auth ../my-project-feat-auth main
git worktree list
git worktree remove ../my-project-feat-auth
git worktree prune이미 있는 브랜치를 새 디렉터리에 붙일 때는 -b 없이 브랜치명을 넘긴다.
git worktree add ../my-project-hotfix-login hotfix/login에이전트용 체크리스트
- main worktree는 깨끗하게 유지한다.
- 새 worktree를 만든 뒤
.env,.env.local, 가상환경,node_modules를 별도로 준비한다. - 장시간 실행 중인 에이전트 worktree는
git worktree lock으로 실수 pruning을 막는다. - 한 worktree에 한 에이전트와 한 명확한 목표를 배정한다.
- 병합은 사람이 main worktree에서 diff와 테스트를 확인한 뒤 수행한다.
적합한 사용 케이스
| 상황 | worktree 이점 |
|---|---|
| 기능 후보 여러 개 비교 | 같은 기준에서 독립 브랜치 결과를 비교 |
| 버그 수정과 기능 개발 병행 | 긴 세션을 끊지 않고 긴급 수정 처리 |
| 여러 AI 도구 비교 | Claude Code, Codex, Copilot을 디렉터리별로 분리 |
| 대규모 리팩터링 | 파일 묶음별로 독립 실험 후 좋은 결과만 병합 |
반대로 작은 수정 하나를 처리할 때는 worktree가 오히려 운영 비용을 늘린다. worktree는 “동시에 여러 흐름을 유지해야 하는 상황”에서 가장 강하다.
관련 문서
- claude-code — Claude Code 개요
- fusion — 작업 보드와 git worktree로 AI 에이전트를 조율하는 오케스트레이터
- orca — 여러 코딩 에이전트를 worktree 단위로 조율하는 Agent IDE
- pro-workflow — 교정에서 학습하는 Claude Code 워크플로 스택
참고 자료
- Git Worktrees for AI Development — KDnuggets (2026-07-18 확인)