Worktree 와 병렬 개발
여러 기능을 동시에 작업해도 충돌 없이
⏱ 예상 ~5분
01 · 읽기
두 가지 기능을 동시에 작업하면서 서로 파일을 밟지 않을 수 있다면 어떨까요? 보통 프로젝트의 한 branch 에는 파일 한 세트가 있어요. auth 구현을 절반쯤 했을 때 중요한 버그가 들어오면, 작업을 stash 하고, branch 를 바꾸고, 흐름을 잃어요.
Git worktree 가 이걸 풀어요. Worktree 는 별도 작업 디렉터리고, 메인 프로젝트와 같은 git 이력을 공유해요. 각 worktree 는 자기 branch 와 파일을 가져요. Claude Code 는 worktree 를 기본 지원해요 — 플래그 하나로 격리된 작업 공간을 띄울 수 있어요.
💡 상상해 봐요사무실에 책상이 하나가 아니라 둘이라고 상상해요. 각 책상에는 작업 중인 문서 사본이 있지만, 둘 다 같은 파일 캐비닛 (git 이력) 에 연결돼 있어요. 책상 1 에서 기능을 작업하고 책상 2 에서 버그를 고치면서, 그 사이에서 종이를 옮기지 않아요.
핵심 정리
- Worktree 는 같은 git repo 를 공유하는 별도 작업 디렉터리예요
- 각 worktree 는 자기 branch 와 파일을 가져요
- stash 하거나 branch 를 바꾸거나 흐름을 잃지 않아도 돼요
- Claude Code 는 --worktree 로 자동으로 worktree 를 만들어요
02 · 코드 예제
--worktree 플래그로 worktree 를 만들어요. 각각 자기 branch 와 디렉터리를 가져요.
worktree 만들기
# Start a Claude session in an isolated worktree
claude --worktree feature-auth
# Start another session for a bug fix
claude --worktree bugfix-login
# Auto-generate a random worktree name
claude --worktree
뒤에서 일어나는 일
Worktree location: .claude/worktrees/feature-auth/
Branch created: worktree-feature-auth
Files: Full copy of your project
Git history: Shared with main repo
각 worktree 는 .claude/worktrees/ 안에 자기 디렉터리, 자기 git branch 를 가져요. 두 Claude session 이 동시에 파일을 편집해도 충돌이 없어요. 끝나면, 변경 사항이 없는 worktree 는 자동으로 정리돼요.
03 · 읽기
Worktree 는 병렬 Claude session 에 특히 강력해요. 아래는 전형적 워크플로예요:
1. 메인 디렉터리에서 기능을 구현 중 2. 버그 리포트가 들어와요 — claude --worktree bugfix-123 3. Bugfix session 이 자기 사본에서 독립적으로 작업 4. 수정 끝, bugfix branch 를 main 으로 merge 5. 박자를 놓치지 않고 기능 작업 계속
Subagent 안에서도 worktree 를 쓸 수 있어요. Subagent 의 SKILL.md frontmatter 에 isolation: worktree 를 더하면 자동으로 자기 worktree 에서 작업해요 — 메인 작업 디렉터리에 영향 없이 파일을 편집해야 하는 작업에 좋아요.
핵심 정리
- 여러 Claude session 을 병렬로 실행, 각각 자기 worktree 에서
- 끝나면 worktree branch 를 다시 merge
- Subagent 는 isolation: worktree 로 worktree 를 쓸 수 있어요
- .claude/worktrees/ 를 .gitignore 에 추가하세요
04 · 읽기
정말 대규모 변경 — 파일 100 개에 걸친 function 이름 바꾸기, 또는 API 마이그레이션 — 에는 Claude Code가 /batch 명령을 제공해요. 작업을 독립 단위로 쪼개고, 각각에 subagent 를 생성하고, 각자 자기 worktree 에서 작업해요.
각 subagent 는 자기 조각에 대한 draft pull request 를 만들어요. 좋은 건 review 하고 merge 하고, 나머지는 반복해요. 이게 프로가 큰 리팩터를 다루는 방법이에요 — 독립적이고 review 가능한 조각으로 쪼개기.
핵심 정리
- /batch 는 큰 작업을 독립 단위로 쪼개요
- 각 단위는 자기 worktree 와 자기 subagent 를 가져요
- 각각이 review 를 위한 draft PR 을 만들어요
- 대규모 리팩터와 마이그레이션에 좋아요
05 · 퀴즈
Claude worktree session 이 끝나고 uncommit 된 변경이 없을 때 어떻게 될까요?
- Worktree 가 자동으로 정리돼요
- 수동으로 지우기 전까지 worktree 가 영원히 남아요
- Claude가 닫기 전에 commit 하라고 요청해요
- Worktree 가 백업 디렉터리로 옮겨져요
06 · 분류 드래그
이 병렬 worktree 워크플로 단계들을 올바른 순서로 놓으세요.
(이 섹션은 인터랙티브해요 — JavaScript를 켜 주세요.)
⚠ 전체 인터랙티브 경험에는 JavaScript가 필요해요. JavaScript를 켜고 새로 고침해 주세요.
※ 이 사이트는 독립 운영되는 교육 프로젝트로, Anthropic의 공식 제품이 아니에요. Claude™ 는 Anthropic, PBC 의 상표예요.