Git branch와 worktree의 분리 모델

TL;DR

git worktree는 Claude Code가 만든 기능이 아니라 Git 2.5부터 있던 기능이다.
branch는 히스토리 포인터이고, worktree는 작업 디렉터리다. 둘은 대체 관계가 아니다.
worktree를 만든다고 node_modules, .env, dev server port 같은 개발 환경이 통째로 복제되지는 않는다.
AI 병렬 작업에서 worktree가 중요해진 이유는 브랜치 전략이 바뀌어서가 아니라 동시에 필요한 작업 디렉터리 수가 늘었기 때문이다.

git flow에 익숙하면 작업 단위는 보통 branch로 나뉜다.

develop
  -> feature branch 생성
  -> 작업
  -> push
  -> merge
  -> develop으로 복귀

AI 코딩 도구를 쓰기 시작하면 이 모델이 불편해진다. 사람은 한 번에 한 branch를 보고 있어도 되지만, 에이전트는 여러 작업을 동시에 맡길 수 있다. 같은 작업 디렉터리에서 여러 에이전트가 움직이면 checkout, 빌드 산출물, 포트, 파일 변경이 서로 충돌한다. 여기서 git worktree가 등장한다. 처음 볼 때 생기기 쉬운 오해는 세 가지다.

worktree는 Claude Code가 만든 신기능이다.
worktree는 branch의 업그레이드 버전이다.
worktree를 만들면 개발 환경도 통째로 복제된다.

셋 다 다르게 정리해야 한다.

가설 1. Claude Code의 신기능

git worktree는 Git 자체 기능이다. Git 2.5에 multiple worktrees 기능이 들어갔다. Claude Code가 만든 개념이 아니다. Claude Code의 worktree 옵션은 기존 Git 기능을 AI 작업 흐름에 맞게 자동화한 것에 가깝다.

Claude Code worktree isolation
  -> 작업용 branch 준비
  -> 별도 worktree 생성
  -> 그 경로에서 에이전트 실행
  -> 필요 시 정리

새 개념이 아니라 git worktree add와 git worktree remove를 에이전트 실행 모델 안에 넣은 것이다. 이 차이는 중요하다. Claude Code를 몰라도 worktree는 쓸 수 있고, Claude Code의 기능을 이해하려면 먼저 Git worktree의 동작을 알아야 한다.

가설 2. branch의 업그레이드

branch와 worktree는 다른 축을 다룬다. branch는 커밋을 가리키는 ref다.

.git/refs/heads/feature/login
  -> <commit-hash>

worktree는 그 커밋의 파일들을 실제 디렉터리에 펼쳐 둔 작업 공간이다.

repository
  -> .git/objects 공유
  -> main worktree
  -> linked worktree A
  -> linked worktree B

둘의 역할은 이렇게 나뉜다.

개념	다루는 것
branch	히스토리 위치
switch/checkout	현재 작업 디렉터리를 다른 branch 기준으로 바꿈
worktree	작업 디렉터리를 하나 더 만듦

따라서 worktree는 branch 전략을 대체하지 않는다. feature branch를 만들고 merge하는 흐름은 그대로 남는다. 달라지는 것은 그 branch를 어느 디렉터리에서 펼쳐 작업하느냐다.

# 새 branch를 만들면서 새 작업 디렉터리 생성
git worktree add -b feature/search ../app-search develop

# 이미 있는 branch를 별도 작업 디렉터리에 펼침
git worktree add ../app-old-feature feature/old-feature

branch는 worktree 없이 존재할 수 있다. 반대로 worktree는 어떤 commit 또는 branch를 기준으로 파일을 펼친다.

같은 branch의 동시 checkout

worktree에는 한 가지 중요한 제약이 있다. 같은 branch를 여러 worktree에서 동시에 checkout하는 것은 기본적으로 막힌다.

main worktree: develop checkout
linked worktree: develop checkout 시도
  -> 거부

이 제약은 branch ref가 하나뿐이기 때문에 필요하다. 두 작업 디렉터리가 같은 branch ref를 각자 움직이면 branch가 어느 커밋을 가리켜야 하는지 충돌한다. 그래서 병렬 작업에서는 worktree마다 별도 branch를 두는 것이 자연스럽다.

main worktree       -> develop
worktree/search     -> feature/search
worktree/auth       -> feature/auth
worktree/fix-build  -> fix/build

branch는 히스토리를 나누고, worktree는 책상을 나눈다.

가설 3. 개발 환경 복제

worktree를 만들면 Git이 추적하는 파일은 새 디렉터리에 펼쳐진다. 하지만 Git이 추적하지 않는 파일은 따라오지 않는다.

항목	worktree 생성 시
tracked source files	펼쳐짐
`.git/objects`	저장소와 공유
`HEAD`, index	worktree별로 분리
`node_modules`	따라오지 않음
`.env.local`	gitignore면 따라오지 않음
`.next`, `dist`	보통 새로 생성
dev server port	머신 단위 공유 자원

따라서 worktree는 소스 격리이지 실행 환경 전체 복제가 아니다. pnpm을 쓰는 경우 node_modules는 worktree마다 새로 만들어야 할 수 있다. 하지만 pnpm store는 보통 사용자 홈 디렉터리에 있으므로 같은 머신의 worktree들이 공유한다. 이 경우 install은 주로 store에서 hard link를 만들고, store에 없는 패키지만 registry에서 받는다.

local worktree A
  -> node_modules A

local worktree B -> node_modules B

shared pnpm store
  -> package contents

CI, Docker, 원격 에이전트처럼 홈 디렉터리나 store가 매번 새로 생기는 환경은 다르다. 이 경우 worktree 여부보다 store 공유 여부가 비용을 결정한다.

AI 병렬 작업에서 맞는 이유

사람이 혼자 작업할 때는 작업 디렉터리 하나로도 충분한 경우가 많다. 급한 작업이 생기면 stash하거나 임시 커밋을 만들고 branch를 바꾸면 된다. AI 에이전트를 여러 개 돌리면 병목이 달라진다.

공유 자원	충돌
작업 디렉터리	서로의 파일 변경을 덮을 수 있음
checkout 상태	한 에이전트의 branch switch가 다른 작업을 흔듦
빌드 산출물	`.next`, `dist`가 섞일 수 있음
dev server port	같은 포트를 동시에 쓰려 함
테스트 DB/스토리지	같은 fixture를 건드릴 수 있음

worktree는 이 중 작업 디렉터리와 checkout 상태를 분리한다. 빌드 산출물도 경로가 분리되므로 대부분 따로 생긴다. 하지만 포트, 외부 DB, 로컬 캐시, OS 자원은 여전히 공유된다. worktree만으로 완전한 샌드박스가 만들어지는 것은 아니다.

workflow, orchestration, subagent

worktree는 AI workflow에서 격리의 한 층이다. 그 위에는 orchestration과 subagent 구조가 붙을 수 있다.

orchestrator
  -> 작업을 쪼갬
  -> subagent A: worktree/search
  -> subagent B: worktree/auth
  -> subagent C: worktree/test
  -> 결과를 main branch에 통합

이 구조에서 worktree가 맡는 책임은 좁다.

층	책임
branch	변경 이력의 분기
worktree	파일 시스템 작업 공간 분리
subagent	특정 작업 수행
orchestrator	작업 분배와 결과 통합

worktree가 orchestration을 대신하지 않는다. 여러 에이전트가 만든 변경을 어떤 순서로 합치고, 충돌을 어떻게 해결하고, 어떤 테스트를 최종 gate로 둘지는 별도 문제다.

정리

처음 세운 세 가설은 이렇게 정리된다.

가설	판정
worktree는 Claude Code가 만든 신기능이다	Git 2.5부터 있던 기능이다
worktree는 branch의 업그레이드 버전이다	branch는 ref, worktree는 작업 디렉터리다
worktree를 만들면 환경도 통째로 복제된다	tracked file만 펼쳐지고 실행 환경은 별도 관리가 필요하다

worktree는 branch flow를 대체하지 않는다. feature branch를 만들고, 작업하고, merge하는 구조는 그대로다. 달라지는 것은 branch를 바꾸기 위해 하나의 책상을 계속 갈아엎지 않아도 된다는 점이다. AI 병렬 작업에서 worktree가 유용한 이유도 여기에 있다. 에이전트마다 branch와 작업 디렉터리를 나누면 checkout 충돌 없이 동시에 작업할 수 있다. 다만 포트, 캐시, DB 같은 실행 자원은 여전히 공유되므로 workflow 설계에서 따로 다뤄야 한다.