Claude Code의 Git worktree: 병렬 세션

Ailoot 사용에 관한 실용적인 정보는 문서에서 확인할 수 있습니다.

Claude Code의 git worktree란#

같은 폴더에서 여러 에이전트를 병렬로 실행하는 것이 2026년의 속도로 바이브 코딩을 할 때 겪는 근본적인 문제입니다. AI 에이전트는 사람이 누가 무엇을 수정하고 있는지 파악하는 속도보다 더 빠르게 코드를 작성합니다. 파일 격리 없이 하나의 디렉터리에서 Claude Code 세션 두 개를 병렬로 실행하면 한 세션이 다른 세션의 작업을 덮어쓰게 됩니다.

Git worktree는 파일 시스템 수준에서 이 문제를 해결합니다. 작업하는 기본 디렉터리 하나가 있습니다. claude --worktree feature-auth 명령은 별도 브랜치에 .claude/worktrees/feature-auth/ 폴더를 만들고 그 안에서 Claude Code를 시작합니다. 파일이 격리됩니다. 한 세션의 변경 사항은 명시적으로 병합할 때까지 다른 세션에서 보이지 않습니다.

Anthropic 공식 문서에서는 이렇게 설명합니다.

자가 점검 팁: 커밋 파일의 절반이 다른 사람의 작업이었던 적이 있다면 worktree가 필요합니다.

git worktree와 일반 브랜치의 차이#

표준 Git 흐름에서는 main 브랜치에 있을 때 git checkout feature-x를 실행하면 Git이 작업 복사본의 파일을 덮어씁니다. 실행 중인 npm run dev는 package.json이 바뀌면서 깨집니다. 커밋하지 않은 변경 사항을 stash하고 IDE가 다시 색인할 때까지 기다립니다. 다시 돌아오면 모든 것이 또 덮어써지므로 stash와 pop을 다시 해야 합니다.

Git worktree를 사용하면 다른 방법이 생깁니다. 브랜치 사이에서 폴더 하나를 전환하는 대신 다른 브랜치를 위한 두 번째 폴더를 만듭니다. git worktree add ../project-feature-x feature-x 명령은 feature-x 브랜치의 파일을 담은 ../project-feature-x/ 디렉터리를 만듭니다. main은 원래 폴더에 그대로 있고 개발 서버도 계속 실행됩니다.

이전에는 Claude Code에서 worktree 모드를 수동으로 설정해야 했습니다. git worktree add를 실행하고 cd한 다음 claude를 실행하는 과정을 모든 터미널에서 반복했습니다. --worktree 플래그(또는 -w)는 이 세 가지를 명령 하나로 처리합니다.

첫 번째 병렬 세션 시작하기: --worktree 플래그#

최소 예제입니다. 첫 번째 터미널을 프로젝트 루트에서 엽니다.

claude --worktree feature-auth

Claude Code는 세 가지 작업을 합니다.

1. origin/HEAD의 스냅샷으로 .claude/worktrees/feature-auth/를 만듭니다(대개 기본 브랜치입니다).
2. 새 worktree-feature-auth 브랜치를 만듭니다.
3. 이 폴더에서 세션을 시작합니다.

같은 저장소 루트 폴더에서 두 번째 터미널을 엽니다.

claude --worktree bugfix-123

끝입니다. Claude Code 세션 두 개, 디스크의 서로 다른 파일, 서로 다른 Git 브랜치입니다. 첫 번째 세션에서 인증 기능을 작성하고 두 번째 세션에서 실패한 테스트를 수정해도 물리적으로 서로 방해할 수 없습니다.

이름을 입력하고 싶지 않다면 Claude가 이름을 지어 줍니다.

claude --worktree
# → .claude/worktrees/bright-running-fox/ 같은 디렉터리를 만듭니다

Git 초보자를 위한 팁: .claude/worktrees/를 .gitignore에 추가하세요. 그렇지 않으면 기본 폴더에서 git status를 실행했을 때 모든 worktree의 내용이 추적되지 않는 파일로 표시됩니다.

# .gitignore
.claude/worktrees/

피해야 할 함정: 새 디렉터리에서 처음으로 --worktree를 실행하기 전에 일반 claude(플래그 없이)를 실행하고 작업 공간 신뢰 대화상자에서 허용해야 합니다. 그렇지 않으면 -p를 함께 사용해 헤드리스 모드로 실행하는 경우에도 플래그가 “trust not accepted” 오류와 함께 실패합니다.

worktree 위치와 찾는 방법#

기본 위치는 고정되어 있습니다. 저장소 루트의 .claude/worktrees/<value>/입니다. 프로젝트가 ~/dev/my-app/에 있으면 feature-auth worktree는 ~/dev/my-app/.claude/worktrees/feature-auth/에 생성됩니다.

저장소 외부에 worktree를 두는 경우처럼 표준적이지 않은 레이아웃에는 WorktreeCreate 훅을 사용할 수 있습니다. SVN과 Mercurial에 관한 아래 절에서 자세히 설명합니다.

Claude 세션 하나 안에서 기존 worktree로 전환할 수 있습니다. 채팅에 “.claude/worktrees/bugfix-123으로 전환”이라고 입력하면 Claude가 EnterWorktree 도구를 호출합니다. 현재 폴더는 그대로 유지되며 같은 방법으로 돌아올 수 있습니다.

표준 Git 명령은 기본 worktree와 수동으로 만든 worktree를 포함해 모든 worktree의 목록을 보여 줍니다.

git worktree list

출력은 다음과 비슷합니다.

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

.env와 비밀 정보 복사하기: .worktreeinclude 파일#

--worktree가 새 폴더를 만들면 Git에 커밋된 내용만 들어갑니다. API 키가 있는 .env와 로컬 설정이 있는 .env.local은 .gitignore에 있으므로 worktree에 없습니다. 그래서 첫 npm run dev 실행이 “MISSING DATABASE_URL” 오류로 실패합니다.

직접 해결하려면 --worktree를 실행할 때마다 .env를 수동으로 복사하면 됩니다. 한 번은 잘되지만 다음에는 잊어버리기 쉽습니다. Anthropic의 해결책은 Git에서 무시되는 파일을 열거해 새 worktree마다 자동으로 복사하도록 프로젝트 루트에 .worktreeinclude 파일을 두는 것입니다.

저장소 루트에 .worktreeinclude 파일을 만듭니다.

.env
.env.local
config/secrets.json

문법은 .gitignore와 같습니다. glob 패턴을 사용할 수 있습니다.

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic은 사고를 방지하기 위한 명확한 규칙을 제시합니다.

다시 말해 .worktreeinclude로 package.json을 실수로 복사할 수는 없습니다. .gitignore에 들어 있지 않기 때문입니다. 여기에 어떤 패턴을 넣어도 안전합니다.

같은 .worktreeinclude를 세 가지 모드에서 사용할 수 있습니다. 수동 --worktree, 서브에이전트용 자동 worktree(아래 참고), Claude 데스크톱 앱 세션입니다.

코드 리뷰를 위해 pull request에서 worktree 만들기#

일반적인 코드 리뷰 상황을 생각해 봅시다. 동료가 PR을 보내서 코드를 살펴보고 테스트를 실행한 뒤 댓글을 남겨야 합니다. 일반 git checkout pull/1234/head를 사용하면 작업 복사본을 다시 전환해야 하고 활성 세션도 깨집니다.

--worktree 플래그를 사용하면 명령 하나로 됩니다.

claude --worktree "#1234"

이때 Claude Code는 git fetch origin pull/1234/head를 실행하고 .claude/worktrees/pr-1234/에 worktree를 만든 다음 PR 브랜치를 체크아웃합니다. 세션이 시작됩니다. 곧바로 “diff를 읽고, 테스트를 실행하고, 논리 오류를 찾아보세요”라고 요청할 수 있습니다. Claude가 작업하는 동안 main의 기본 세션은 계속 실행됩니다.

전체 pull request URL을 사용하는 대체 문법도 있습니다.

claude --worktree https://github.com/OWNER/REPO/pull/1234

실제 프로젝트에서는 claude --worktree "#N"과 자체 코드 리뷰어 서브에이전트를 조합하면 1~2분 안에 자동 리뷰를 받을 수 있습니다. 백그라운드에서 실행하고 기본 창에서 작업을 계속한 뒤 claude agents를 통해 결과를 확인하세요.

기준 브랜치: fresh 또는 head를 위한 worktree.baseRef#

기본 설정에서는 새 worktree가 모두 origin/HEAD에서 시작합니다. 장점은 CI에서 보게 될 내용과 반드시 일치하는 깨끗한 시작점이라는 것입니다. 단점은 현재 브랜치에 커밋하지 않은 변경 사항이나 원격을 앞선 로컬 커밋이 여러 개 있어도 새 worktree에는 포함되지 않는다는 점입니다.

현재 로컬 HEAD 커밋에서 worktree를 시작하려면 .claude/settings.json(또는 전역 설정)에 다음을 추가합니다.

{
  "worktree": {
    "baseRef": "head"
  }
}

이제 claude --worktree experimental-feature는 현재 로컬 HEAD에서 시작합니다. 아직 푸시하지 않은 로컬 커밋이 있는 기능에 유용하며 추적 중인 미커밋 수정은 포함하지 않습니다. 서브에이전트에 그 수정이 필요하면 보존한 뒤 명시적으로 옮기고 대상 diff를 확인하세요. 무시된 로컬 파일을 처리하는 .worktreeinclude와 혼동하지 마세요.

이 설정은 정확히 두 가지 값을 허용합니다. "fresh"(= origin/HEAD)와 "head"(= 로컬 HEAD)입니다. "feature-branch"나 커밋 해시 같은 임의 ref는 허용되지 않습니다. 선택지가 조합적으로 폭증하는 것을 방지하기 위한 의도적인 제한입니다.

서브에이전트 자동 격리하기: isolation: worktree#

Claude에게 “서브에이전트 세 개를 시작하세요. 하나는 데이터베이스를 읽고, 두 번째는 API를 살펴보고, 세 번째는 테스트를 확인하세요”라고 요청하면 기본적으로 세 에이전트 모두 작업 복사본에서 작업합니다. 둘이라도 동시에 같은 파일을 수정하면 충돌이 발생합니다. 각 에이전트에 자체 worktree를 자동으로 제공하면 해결됩니다.

방법 1: 말로 요청합니다. 대화에서 Claude에게 다음과 같이 입력합니다.

에이전트에 worktree를 사용하세요.

Claude는 이 세션에서 이후에 실행되는 모든 서브에이전트에 격리를 적용합니다.

방법 2: 서브에이전트 자체에 명시적으로 설정합니다. 서브에이전트 파일(예: .claude/agents/code-reviewer.md)의 frontmatter에 필드를 추가합니다.

---
name: code-reviewer
description: diff를 읽고 코드 리뷰 의견 작성
isolation: worktree
---

꼼꼼한 리뷰어가 되어 diff를 읽고 논리 오류를 찾아보세요...

이제 이 서브에이전트를 실행할 때마다 .claude/worktrees/에 임시 worktree가 만들어집니다. 서브에이전트가 아무것도 작성하지 않았다면 완료 시 폴더가 자동으로 삭제됩니다. 커밋하지 않은 변경 사항이 있으면 Claude가 보존할지 제거할지 묻습니다.

서브에이전트 worktree의 기준 브랜치는 --worktree와 같습니다. 기본값은 origin/HEAD이며, worktree.baseRef: head를 사용하면 로컬 HEAD입니다.

판단표: worktree, /bg, 서브에이전트, Agent View#

일반적인 조합은 다음과 같습니다.

• “기능 두 개를 수동으로 병렬 작업” — 터미널 두 개에서 각각 claude --worktree를 실행합니다. 가장 간단한 경우입니다.
• “밤새 리팩터링을 시작하고 앱은 닫기” — 완료 조건을 지정한 /bg + /goal입니다. 세션은 현재 창과 독립적으로 실행됩니다.
• “프롬프트 하나로 병렬 조사 세 가지” — isolation: worktree가 지정된 서브에이전트 세 개입니다. 각각 별도의 샌드박스에서 작업합니다.
• “지금 무엇이 실행 중이지?” — claude agents를 사용합니다. “running”, “blocked”, “done” 필터로 모든 세션을 보여 주는 대시보드입니다.

worktree 사용 시 흔히 하는 실수 5가지#

1. worktree를 시작했는데 .env가 없고 아무것도 작동하지 않습니다. 가장 흔한 문제입니다. worktree는 Git에서 무시되는 파일이 없는 새 체크아웃입니다. worktree 모드를 설정할 때 .env*와 필요한 로컬 설정이 포함된 .worktreeinclude 파일을 추가하면 해결됩니다. 파일이 .claude/가 아니라 저장소 루트에 있는지 확인하세요.

2. 메인 브랜치로 전환하려고 루트에서 cd를 실행했더니 worktree의 커밋하지 않은 변경 사항을 잃었습니다. 루트 폴더와 worktree는 서로 다른 작업 복사본입니다. cd로 돌아왔을 뿐입니다. worktree의 변경 사항은 그대로 있으며 사라지지 않았습니다. 하지만 worktree에 있다고 생각하면서 기본 폴더에서 git stash를 실행했다면 예상한 브랜치가 아니라 메인 브랜치에 stash가 만들어집니다.

3. 병렬 세션 5개를 시작했더니 각각 무엇을 하는지 기억나지 않습니다. Anthropic 문서는 대부분의 개발자가 인지적으로 2~3개보다 많은 세션을 감당하기 어렵다고 명시적으로 경고합니다. Agent View를 열어도 각 에이전트가 무엇을 하는지 바로 말할 수 없다면 과부하의 신호입니다. 동시에 실행하는 세션은 두 개로 제한하세요. 더 필요한 작업은 수동으로 하기보다 /goal과 서브에이전트로 조율해야 합니다.

4. -p(헤드리스)로 시작한 worktree는 자동으로 정리되지 않습니다. claude --worktree feature-x -p "do thing" 명령은 대화형 종료 프롬프트를 표시하지 않으므로 Claude가 “worktree를 제거할까요?”라고 묻는 시점이 없습니다. 이런 worktree는 쌓입니다. git worktree remove .claude/worktrees/feature-x로 수동 정리하거나 7일보다 오래된 항목을 제거하는 cron 스크립트를 사용하세요.

5. 새 폴더의 신뢰 대화상자. 저장소를 처음 열자마자 claude --worktree를 실행하면 명령이 실패합니다. 플래그 없이 claude를 실행하고 작업 공간 신뢰를 허용한 뒤 종료하세요. 그러면 --worktree가 작동합니다. 이는 Claude가 사용자의 동의 없이 다른 사람의 프로젝트에 접근하지 못하도록 의도된 동작입니다.

정리: 자동으로 삭제되는 항목#

정리 방식은 worktree에서 무엇을 했는지, 세션을 어떻게 시작했는지에 따라 달라집니다. Anthropic 문서에는 세 가지 상황이 나옵니다.

상황 1: 들어갔다가 아무것도 하지 않고 종료했습니다. worktree가 제거됐습니다.

상황 2: 작업했지만 커밋하지 않았습니다. 종료할 때 Claude가 “보존할까요, 제거할까요?”라고 묻습니다. “보존”을 선택하면 폴더와 브랜치가 나중을 위해 남습니다. “제거”를 선택하면 디렉터리와 함께 커밋하지 않은 변경 사항 및 새 커밋도 삭제됩니다. 파괴적인 작업이므로 습관적으로 “제거”를 누르지 마세요.

상황 3: -p(헤드리스)로 실행했고 명령이 끝나면서 종료됐습니다. worktree는 남아 있습니다. 직접 정리하세요.

git worktree remove .claude/worktrees/feature-x

또한 서브에이전트와 /bg 세션의 worktree는 cleanupPeriodDays일(설정값이며 기본값은 보통 30일)보다 오래되었고 동시에 저장되지 않은 작업이 없으면 백그라운드 정리 작업으로 자동 제거됩니다. --worktree에서 만든 worktree는 자동 정리 대상이 아니므로 직접 관리해야 합니다.

SVN, Perforce, Mercurial의 대안: WorktreeCreate 훅#

저장소가 Subversion이나 Mercurial을 사용하면 --worktree 플래그가 바로 작동하지 않습니다. Anthropic은 두 훅을 통해 확장점을 제공합니다. WorktreeCreate는 격리된 복사본을 만들고, WorktreeRemove는 이를 제거합니다.

공식 문서의 SVN 훅 예제입니다.

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

훅은 stdin에서 worktree 이름({ "name": "feature-auth" })을 읽고 미리 계산된 디렉터리에 svn checkout을 실행한 뒤 경로를 stdout에 출력합니다. Claude Code는 이 경로를 새 세션의 작업 디렉터리로 사용합니다.

중요한 주의 사항이 있습니다. 자체 훅을 사용하면 .worktreeinclude가 적용되지 않습니다. 새 폴더에 .env나 Git에서 무시되는 다른 파일이 필요하다면 훅 스크립트 안에서 복사하세요.

다음 단계: 병렬 작업과 관련된 메커니즘 세 가지#

Worktree는 파일을 격리합니다. /bg는 컨텍스트를 격리합니다. 서브에이전트는 작업을 격리합니다. 각 메커니즘은 하나의 문제를 해결합니다. 함께 사용하면 인지적 혼란 없이 세 개에서 다섯 개의 작업을 병렬로 진행할 수 있습니다. 이것이 2026년 고급 바이브 코딩의 기술 기반입니다.

이 주제는 자연스럽게 관련 주제 세 가지로 이어집니다. /goal과 Agent View를 사용해 자율 에이전트를 설정하는 방법, 작업에 맞는 서브에이전트를 직접 만드는 방법, Dynamic Workflows를 통해 수백 개의 에이전트를 실행하는 방법입니다.

Ailoot 열기.