# Claude Code의 Git worktree: 병렬 세션

> --worktree, .worktreeinclude, worktree.baseRef, 서브에이전트 격리 사용법. 브랜치와의 차이, worktree 정리, 흔히 하는 실수를 알아봅니다.

Source: https://ailoot.ai/blog/ko/claude-code-git-worktree/
Canonical: https://ailoot.ai/blog/ko/claude-code-git-worktree/
Language: ko
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-045
Revision: sha256-1507ab548cf67049b961f5954ce1101fa213b88d5480b0cf60f143c7cb440c0f




[Ailoot 사용에 관한 실용적인 정보는 문서에서 확인할 수 있습니다](https://ailoot.ai/docs/).

## Claude Code의 git worktree란

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

Git worktree는 같은 저장소의 다른 브랜치를 위한 별도의 작업 디렉터리입니다. `claude --worktree <name>` 명령은 `.claude/worktrees/<name>/`에 worktree를 자동으로 만들고 그 안에서 Claude Code를 시작합니다. 터미널 두 개 → 세션 두 개 → 디스크의 서로 다른 파일, 간섭은 없습니다. Claude Code v2.0 이상에서 기본 제공되며, 비밀 정보는 `.worktreeinclude`로, 기준 브랜치 선택은 `worktree.baseRef`로 설정할 수 있습니다.

</div>

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

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

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

<figure>
<blockquote>
<p>각 Claude Code 세션을 자체 worktree에서 실행하면 한 세션의 편집 내용이 다른 세션의 파일에 영향을 주지 않습니다. 한 터미널에서 기능을 만들고 다른 터미널에서 버그를 수정할 수 있습니다.</p>
</blockquote>
<figcaption>— Anthropic Docs, https://code.claude.com/docs/en/worktrees</figcaption>
</figure>

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

일반 `git checkout`은 같은 폴더의 작업 복사본을 전환합니다. 이전 브랜치의 파일은 해당 브랜치로 돌아갈 때까지 디스크에서 사라집니다. `git worktree add`는 첫 번째 폴더 옆에 다른 브랜치를 위한 **두 번째 폴더**를 만듭니다. 두 브랜치가 동시에 디스크에 존재하며 간단히 `cd` 명령으로 오갈 수 있습니다. 내부적으로는 `.git` 저장소 하나를 사용하고 기록과 원격 저장소를 공유합니다. 작업 복사본만 여러 개 있는 것입니다.

</div>

표준 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`은 원래 폴더에 그대로 있고 개발 서버도 계속 실행됩니다.

| 항목 | `git checkout` 브랜치 | `git worktree add` |
|----|----|----|
| 작업 복사본 파일 | 덮어씀 | 새 폴더에 나타남 |
| 두 브랜치에서 병렬 작업 | 불가능 | 가능 |
| 커밋하지 않은 변경 사항 | `git stash` 필요 | 할 일 없음 |
| 전환 속도 | 차이의 크기에 따라 다름 | `cd`만 하면 됨 |
| 디스크 공간 | 1× | N× (브랜치마다 파일 복사본 하나) |

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

`claude --worktree feature-auth` 명령은 `.claude/worktrees/feature-auth/`에 worktree를 만들고 `origin/HEAD`에서 `worktree-feature-auth` 브랜치를 만든 다음 그곳에서 Claude Code를 시작합니다. 수동으로 `git worktree add`나 `cd`를 할 필요가 없습니다. 옆 터미널에서 다른 이름을 사용해 반복하면 독립된 세션 두 개를 얻을 수 있습니다. 이름을 생략하면(`claude --worktree`) Claude가 `bright-running-fox` 같은 무작위 이름을 생성합니다.

</div>

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

```bash
claude --worktree feature-auth
```

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

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

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

```bash
claude --worktree bugfix-123
```

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

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

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

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

```
# .gitignore
.claude/worktrees/
```

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

## worktree 위치와 찾는 방법

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

기본적으로 모든 worktree는 저장소 루트 옆의 `.claude/worktrees/<name>/`에 있습니다. 목록을 보려면 `git worktree list`를 실행하세요. worktree에 직접 들어가려면 `cd .claude/worktrees/feature-auth`를 사용하세요. Claude 세션 안에서 전환하려면 “다른 worktree로 전환”이라고 요청하면 됩니다. 내장 EnterWorktree 도구를 사용합니다. 이전 worktree는 디스크에서 그대로 유지됩니다.

</div>

기본 위치는 고정되어 있습니다. 저장소 루트의 `.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의 목록을 보여 줍니다.

```bash
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` 파일

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

worktree는 새로 체크아웃한 상태입니다. `.gitignore`에 포함된 파일(`.env`, `.env.local`, 로컬 설정)은 새 폴더에 없습니다. 이 파일이 없으면 `npm run dev`나 `prisma db push`가 실행되지 않습니다. 프로젝트 루트의 `.worktreeinclude` 파일은 `.gitignore` 문법을 사용하며 새 worktree마다 자동 복사할 파일을 Claude Code에 알려 줍니다. `--worktree`, 서브에이전트 worktree, 데스크톱 앱 세션에서 적용됩니다.

</div>

`--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은 사고를 방지하기 위한 명확한 규칙을 제시합니다.

<figure>
<blockquote>
<p>이 파일은 gitignore 문법을 사용합니다. 패턴에 일치하면서 Git에서도 무시되는 파일만 복사됩니다. Git에서 추적되는 파일은 복제되지 않습니다.</p>
</blockquote>
<figcaption>— Anthropic Docs, https://code.claude.com/docs/en/worktrees</figcaption>
</figure>

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

`claude --worktree "#1234"` 명령은 origin에서 pull request \#1234를 가져와 PR 브랜치가 있는 `.claude/worktrees/pr-1234/`에 worktree를 만듭니다. 전체 URL인 `claude --worktree https://github.com/OWNER/REPO/pull/1234`를 전달할 수도 있습니다. 코드 리뷰에 유용합니다. PR을 전용 폴더에서 열면 기본 저장소를 그대로 둔 채 Claude가 테스트를 실행하고 로그를 읽고 댓글을 작성할 수 있습니다.

</div>

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

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

```bash
claude --worktree "#1234"
```

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

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

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

기본적으로 worktree는 원격에서 마지막으로 동기화된 커밋인 `origin/HEAD`에서 브랜치를 만듭니다. 안전하고 “깨끗한” 시작점입니다. 로컬의 미푸시 커밋을 포함하려면 `worktree.baseRef: "head"`를 지정하세요. HEAD는 커밋을 가리킵니다. 추적 중인 미커밋 수정은 원래 작업 사본에 남으며 별도 명시적 이전이 필요합니다. 메인으로 전환하지 않고 서브에이전트가 현재 기능 브랜치 위에서 작업해야 할 때 유용합니다. `fresh` 또는 `head`만 허용하며 임의의 ref는 지원하지 않습니다.

</div>

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

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

```json
{
  "worktree": {
    "baseRef": "head"
  }
}
```

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

Claude Code의 서브에이전트는 코드 리뷰, 리팩터링, 조사처럼 하나의 작업을 수행하는 전문 에이전트입니다. 한 세션에서 여러 서브에이전트를 병렬로 실행하면 기본적으로 같은 폴더에서 작업하므로 서로의 파일을 덮어쓸 수 있습니다. 서브에이전트의 frontmatter에 `isolation: worktree`를 추가하면 각 서브에이전트에 임시 worktree가 제공되며, 커밋한 내용이 없으면 작업이 끝날 때 깔끔하게 제거됩니다.

</div>

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

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

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

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

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

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

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

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

혼동하기 쉬운 Claude Code 메커니즘 네 가지입니다. Worktree는 파일 격리(디스크)를 제공합니다. `/bg`는 백그라운드 세션(컨텍스트와 토큰)을 제공합니다. 서브에이전트는 특화된 일회성 에이전트(프롬프트와 도구)입니다. Agent View는 모든 세션의 대시보드(UI)입니다. 이들은 함께 사용할 수 있습니다. `/bg`는 worktree를 자동으로 만들고, `isolation: worktree`가 지정된 서브에이전트는 임시 worktree에서 시작하며, Agent View는 세 항목을 하나의 목록에 표시합니다.

</div>

| 도구 | 격리 대상 | 사용 시점 |
|----|----|----|
| `claude --worktree <name>` | 파일(별도 폴더와 브랜치) | 서로 다른 터미널에서 N개의 세션을 병렬로 수동 실행하고 싶을 때 |
| `/bg`(또는 `Ctrl+B`) | 컨텍스트와 시간 | 현재 창을 막지 않고 긴 작업을 진행하고 싶을 때. 내부적으로 worktree가 만들어짐 |
| `isolation: worktree`가 지정된 서브에이전트 | 한 세션 안의 파일 | 프롬프트 하나로 N개의 에이전트에 작업을 맡기고 서로 파일을 덮어쓰지 않도록 보호하고 싶을 때 |
| `claude agents`(Agent View) | 격리 대상 없음, UI임 | 실행 중, 일시 중지, 완료된 모든 세션을 대시보드 하나에서 확인하고 싶을 때 |
| `/goal` | 자율성 관리 | 턴 사이에 사용자 프롬프트 없이 Claude가 조건이 충족될 때까지 작업하게 하고 싶을 때 |

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

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

가장 흔한 문제는 `.worktreeinclude`를 잊어 환경이 작동하지 않는 것, worktree와 일반 브랜치를 혼동해 커밋하지 않은 변경 사항을 잃는 것, 병렬 세션 5개 이상을 실행하고 각각 어디서 무엇을 하는지 잊는 것, `cleanupPeriodDays`를 설정하지 않아 사용하지 않는 폴더가 쌓이는 것, 새 디렉터리의 신뢰 대화상자를 놓쳐 `--worktree`가 오류로 실패하는 것입니다.

</div>

**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가 사용자의 동의 없이 다른 사람의 프로젝트에 접근하지 못하도록 의도된 동작입니다.

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

변경 사항이 없는 `--worktree` worktree(커밋, 추적되지 않는 파일, 커밋하지 않은 변경 사항이 없음)는 종료 시 자동으로 제거됩니다. 변경 사항이 있으면 Claude가 묻습니다. 서브에이전트와 `/bg`의 worktree는 깨끗한 상태라면 설정의 `cleanupPeriodDays` 시간 초과에 따라 자동으로 제거됩니다. `-p`에서 만든 worktree는 전혀 정리되지 않으므로 `git worktree remove`로 직접 제거해야 합니다.

</div>

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

<figure>
<blockquote>
<p>worktree에 커밋하지 않은 변경 사항, 추적되지 않는 파일, 새 커밋이 없다면 세션을 종료할 때 worktree와 브랜치가 자동으로 제거됩니다. 세션에 이름이 있다면 Claude는 제거하는 대신 나중에 사용할 수 있도록 worktree를 보존할지 묻습니다.</p>
</blockquote>
<figcaption>— Anthropic Docs, https://code.claude.com/docs/en/worktrees</figcaption>
</figure>

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

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

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

```bash
git worktree remove .claude/worktrees/feature-x
```

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

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

worktree 모드는 기본적으로 `git worktree`를 사용합니다. SVN, Perforce, Mercurial 및 기타 VCS에서는 Claude Code 설정의 `WorktreeCreate`와 `WorktreeRemove` 훅을 통해 자체 메커니즘을 연결할 수 있습니다. 훅은 stdin으로 이름을 받고, 만든 디렉터리의 경로를 출력한 다음 종료 코드 0으로 끝나야 합니다. 자체 훅을 사용하면 `.worktreeinclude`는 처리되지 않으므로 훅 안에서 로컬 파일을 직접 복사해야 합니다.

</div>

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

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

```json
{
  "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에서 무시되는 다른 파일이 필요하다면 훅 스크립트 안에서 복사하세요.

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

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="섹션 핵심 요점">

핵심 요점

Worktree는 파일 격리를 제공합니다. `/bg`는 컨텍스트와 토큰 격리를 제공합니다. Subagent는 작업과 도구를 격리합니다. `/goal`은 조건이 충족될 때까지 자율성을 제공합니다. 각 메커니즘은 하나의 문제를 해결합니다. 함께 사용하면 인지적 혼란 없이 3~5개의 작업을 병렬로 진행할 수 있습니다. 다음으로 아래 링크를 통해 자율 모드, 사용자 지정 서브에이전트, 동적 워크플로에 관한 관련 가이드를 살펴보면 좋습니다.

</div>

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

이 주제는 자연스럽게 관련 주제 세 가지로 이어집니다. [`/goal`과 Agent View를 사용해 자율 에이전트를 설정하는 방법](https://ailoot.ai/blog/ko/claude-code-goal-agent-view/), [작업에 맞는 서브에이전트를 직접 만드는 방법](https://ailoot.ai/blog/ko/claude-code-subagents/), [Dynamic Workflows를 통해 수백 개의 에이전트를 실행하는 방법](https://ailoot.ai/blog/ko/claude-code-dynamic-workflows/)입니다.

<div class="section" role="doc-bibliography" aria-label="출처">

### 출처

- [worktree로 병렬 세션 실행하기 - Claude Code Docs](https://code.claude.com/docs/en/worktrees)
- [사용자 지정 서브에이전트 만들기 - Claude Code Docs](https://code.claude.com/docs/en/sub-agents)
- [Claude Code 변경 기록(2026년 5~6월)](https://code.claude.com/docs/en/changelog)
- [에이전트를 병렬로 실행하기 - Claude Code Docs](https://code.claude.com/docs/en/agents)
- [Agent View - Claude Code Docs](https://code.claude.com/docs/en/agent-view)
- [git worktree 매뉴얼 페이지](https://git-scm.com/docs/git-worktree)

</div>





[Ailoot 열기](https://ailoot.ai/).

## Claude Code의 Git worktree: 병렬 세션: 자주 묻는 질문

### baseRef head가 미커밋 변경도 새 worktree로 복사하나요?

아닙니다. 원격에 없는 로컬 커밋을 포함한 현재 HEAD 커밋에서 시작합니다. 추적 중인 미커밋 수정은 원래 사본에 남습니다. 필요한 WIP는 명시적으로 옮기고 새 worktree를 확인하세요.

### 새 worktree에 .env가 없는 이유는 무엇인가요?

새 체크아웃이므로 Git에서 무시한 로컬 파일은 없습니다. Claude Code의 `.worktreeinclude`는 복사할 무시 파일을 나열합니다. 사용자 WorktreeCreate 훅은 복사를 직접 처리해야 합니다. 작업에 꼭 필요한 파일만 포함하세요.


## Ailoot · 회사와 그 프로젝트 포트폴리오

Ailoot는 축적된 운영 경험, 폭넓은 고객 기반, 안정적인 서비스, 지속적인 KPI 관리를 바탕으로 합니다.

회사와 그 프로젝트 포트폴리오: 수백만 고객, 매월 수십억 규모의 매출.

Ailoot는 이러한 운영 경험을 고객의 제품, 에이전트, 애플리케이션, 자동화에서 AI 기능을 이용할 수 있는 API 접근에 활용합니다.