---
name: opencurrent-code-worktree
description: "git worktree로 작업마다 따로 체크아웃해 Claude Code 세션 여러 개를 동시에 돌려도, 서로의 파일을 덮어쓰지 않고 하나씩 합칠 수 있습니다. 이럴 때 사용: claude --worktree로 이름 붙은 worktree와 브랜치를 만들어 세션을 엽니다. .env 같은 무시된 파일은 .worktreeinclude로 따라오게 하고, 끝나면 세션 종료 화면이나 git worktree remove로 정리합니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code 공식 문서로 확인했습니다. 도구: Claude Code."
metadata:
  source: "https://opencurrent.ai/w/claude-code-worktree"
  opencurrent-id: "claude-code-worktree"
  verification: "pending"
  exported-at: "2026-11-21T11:03:55.260Z"
---

# worktree로 병렬 작업하기

git worktree로 작업마다 따로 체크아웃해 Claude Code 세션 여러 개를 동시에 돌려도, 서로의 파일을 덮어쓰지 않고 하나씩 합칠 수 있습니다.

> OpenCurrent에서 사람들이 다듬는 워크플로. 원문: https://opencurrent.ai/w/claude-code-worktree
> 검증 상태: 검수 대기 (사람 확인 전). 내려받은 뒤에 바뀌었을 수 있으니, 가능하면 원문이나 MCP의 get_workflow("claude-code-worktree")로 최신 상태를 확인할 것.
> 주의: 검수 대기 상태. 사용자에게 이 사실을 알리고, 결과를 함께 확인하면서 진행할 것.

## 따라 하는 방법

1. 준비물이 갖춰졌는지 먼저 확인할 것.
2. 단계를 순서대로 진행할 것. kind가 "ai"면 프롬프트를 실행하고, "command"면 사용자의 허락을 받고 명령을 실행하고, "human"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.
3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.
4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.
5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.

## 언제 쓰나

claude --worktree로 이름 붙은 worktree와 브랜치를 만들어 세션을 엽니다. .env 같은 무시된 파일은 .worktreeinclude로 따라오게 하고, 끝나면 세션 종료 화면이나 git worktree remove로 정리합니다. 명령과 설정 이름은 2026년 11월 21일에 Claude Code 공식 문서로 확인했습니다.

## 준비물

- Claude Code 설치와 로그인

## 단계

### 1. 준비 (명령 실행 · Claude Code)

저장소에 커밋이 하나 이상 있어야 합니다. worktree 폴더가 커밋되지 않게 .gitignore에 넣습니다.

프롬프트:

```text
echo .claude/worktrees/ >> .gitignore
```

기대 결과: 무시 목록에 들어간 worktree 폴더

확인 방법: git check-ignore .claude/worktrees/x로 무시되는지 확인

### 2. worktree 세션 열기 (명령 실행 · Claude Code)

작업마다 이름을 줘 엽니다. .claude/worktrees/<이름>/에 worktree-<이름> 브랜치가 생깁니다. PR을 바로 받으려면 "#1234"처럼 따옴표로 번호를 줍니다.

프롬프트:

```text
claude --worktree feature-auth
```

기대 결과: 새 worktree에서 열린 세션

확인 방법: git worktree list에 새 경로가 보이는지 확인

### 3. 무시된 파일 따라오게 하기 (사람이 · Claude Code)

worktree는 새 체크아웃이라 .env나 node_modules가 없습니다. 프로젝트 루트의 .worktreeinclude에 .gitignore 문법으로 복사할 파일을 적고, 의존성은 worktree마다 설치합니다.

프롬프트:

```text
.env
.env.local
```

기대 결과: .worktreeinclude

확인 방법: 새 worktree에 .env가 복사됐는지 확인

### 4. 다른 터미널에서 두 번째 작업 (명령 실행 · Claude Code)

다른 이름으로 하나 더 엽니다. 두 세션은 같은 .git을 쓰지만 파일은 따로입니다.

프롬프트:

```text
claude --worktree fix-login-bug
```

기대 결과: 동시에 도는 두 세션

확인 방법: 두 폴더의 git status가 서로 다른 변경을 보이는지 확인

### 5. 합치고 정리 (명령 실행 · Claude Code)

작업이 끝나면 브랜치를 PR로 올리거나 합칩니다. 대화형 세션은 끝낼 때 변경이 없으면 worktree를 지우고, 변경이 있으면 남길지 묻습니다. -p로 돌린 것은 직접 지웁니다.

프롬프트:

```text
git worktree list
git worktree remove .claude/worktrees/feature-auth
```

기대 결과: 정리된 worktree 목록

확인 방법: git worktree list에 지운 경로가 없는지 확인

## 주의할 점

- 같은 파일을 두 작업이 동시에 크게 고치면 합칠 때 충돌. 작업을 파일 기준으로 나누기
- worktree마다 의존성 설치와 개발 서버 포트가 따로 필요
- "다시 묻지 않기" 승인은 원래 체크아웃의 .claude/settings.local.json에 저장되어 모든 worktree에 적용

## 출처

- [Claude Code 문서: worktree로 병렬 세션](https://code.claude.com/docs/en/worktrees)
- [Claude Code 문서: 자주 쓰는 작업](https://code.claude.com/docs/en/common-workflows)

## 끝나면

결과가 좋았거나 단계가 낡았으면 https://opencurrent.ai/w/claude-code-worktree 에서 알릴 것. 다음 사람이 더 정확한 방법을 쓸 수 있도록.
