용어 사전

git worktree란?

git worktree는 저장소를 별도 브랜치에 체크아웃한 작업 폴더입니다. 기본 저장소와 같은 git 기록을 공유하지만, 자체 폴더에 별도 파일을 가집니다. 원하는 만큼 동시에 열 수 있습니다.

워크트리가 해결하는 문제

보통 저장소는 하나의 폴더에 하나의 브랜치만 체크아웃합니다. 기능 두 개를 동시에 작업하려면 변경 사항을 stash하고, 브랜치를 바꾸고, 다른 작업을 한 뒤, 다시 브랜치를 바꾸고 stash를 풀어야 합니다. 번거롭습니다.

워크트리를 쓰면 이미 다른 브랜치가 체크아웃된 두 번째 폴더가 생깁니다. 한 폴더에서는 기능 A를, 다른 폴더에서는 기능 B를 작업하세요. stash도 전환도 필요 없습니다. 두 작업이 동시에 존재합니다.

AI 에이전트에 중요한 이유

AI 에이전트 두 개를 같은 폴더에서 실행하면 서로의 변경 사항을 덮어씁니다. 에이전트 A가 auth.ts을 수정합니다. 에이전트 B도 auth.ts을 수정합니다. 마지막에 저장한 쪽만 남습니다. 다른 에이전트의 작업은 사라집니다.

워크트리가 이 문제를 해결합니다. 에이전트마다 자체 폴더, 자체 브랜치, 별도 파일 사본을 받습니다. 둘 다 동시에 auth.ts을 수정해도 서로 덮어쓰지 않습니다. 작업이 끝나면 각 브랜치를 따로 병합하세요.

디스크에서는 이렇게 보입니다

my-project/              ← your main repo (main branch)
../my-project-feature-a/ ← worktree (feature-a branch)
../my-project-feature-b/ ← worktree (feature-b branch)

세 폴더는 모두 같은 Git 기록을 공유합니다. 한 워크트리에 커밋한 변경 사항은 병합 후 다른 워크트리에서도 보입니다. 하지만 커밋하지 않은 파일 변경은 완전히 격리됩니다.

Pane의 워크트리 자동화 방식

Git 명령어를 직접 실행할 필요가 없습니다. Pane에서 새 pane을 만들면:

1. Pane이 워크트리와 브랜치를 만들어 줍니다.
2. 환경 변수, node_modules와 기타 중요 디렉터리를 복사합니다. 에이전트가 바로 작업을 시작할 수 있습니다.
3. pane을 보관하면 Pane이 워크트리를 자동으로 정리합니다.

직접 하는 방법 (참고용)

Pane 없이 직접 하려면:

git worktree add ../feature-a feature-a
cd ../feature-a
claude   # start your agent here

# when done:
git worktree remove ../feature-a

Pane에서는 클릭 한 번이면 전부 처리됩니다.

관련 문서

작성자 Parsa Khazaeepoul

마지막 업데이트 2026년 6월 24일