Claude Code 상세 사용법 59: worktree로 병렬 세션 안전하게 굴리기 | DAKER 커뮤니티

Claude Code 상세 사용법 59: worktree로 병렬 세션 안전하게 굴리기

Claude Code를 하루 종일 쓰면 한 세션이 기능 개발을 하는 동안 다른 세션이 버그를 고치게 하고 싶어집니다. 공식 common workflows와 worktrees 문서 기준으로 claude --worktree <name>은 별도 checkout과 branch를 만들어 병렬 Claude Code 세션의 파일 변경 충돌을 줄이는 방법입니다.

Mermaid 흐름으로 보는 병렬 작업

아래 Mermaid source처럼 한 checkout에서 섞지 말고 branch 단위로 격리합니다.

Mermaid source:
flowchart TD
  A[main checkout] --> B[worktree: auth-fix]
  A --> C[worktree: billing-ui]
  B --> D[targeted tests]
  C --> E[visual QA]
  D --> F[merge deliberately]
  E --> F

기본 실행

프로젝트 루트에서 이름을 붙여 시작합니다. 이름은 나중에 directory와 branch를 구분할 수 있게 결과 중심으로 짓습니다.

claude --worktree auth-timeout-fix
claude --worktree billing-empty-state

각 세션은 자기 branch에서 작업합니다. 한쪽에서 test snapshot을 고치고 다른 쪽에서 UI copy를 바꾸는 식으로 독립성이 있으면 효과가 큽니다. 같은 파일을 동시에 고칠 가능성이 높으면 worktree보다 먼저 계획을 나누는 편이 낫습니다.

시작 전에 baseline을 정리한다

worktree는 마법 복사가 아닙니다. main checkout의 uncommitted 변경, 로컬 .env, 생성 파일, 패키지 설치 상태를 확인해야 합니다.

git status --short
git branch --show-current

필요한 로컬 파일만 포함해야 한다면 공식 문서의 .worktreeinclude 패턴을 검토합니다. 비밀값은 무심코 복제하지 말고, 각 worktree에서 필요한 최소 환경만 주입하세요.

세션별 프롬프트를 작게 만든다

병렬 agentic coding은 “둘 다 알아서 해줘”가 아니라 독립 완료 조건을 주는 방식입니다.

auth-timeout-fix worktree에서만 작업해.
목표: 만료된 refresh token에서 logout race를 재현하는 테스트를 추가하고 통과시켜.
검증: npm test -- auth-session
범위 밖: billing, onboarding, schema migration

다른 worktree에는 전혀 다른 완료 조건을 줍니다. 그래야 나중에 diff를 비교하고 merge 순서를 정할 수 있습니다.

병합과 정리

각 worktree에서 테스트를 먼저 통과시킨 뒤 main checkout에서 diff를 읽습니다. 먼저 들어갈 branch, conflict 가능성, shared dependency 변경을 판단합니다.

git diff main...HEAD --stat
npm test

병합 후에는 남은 worktree를 정리합니다. 정리하지 않으면 오래된 branch와 node_modules가 쌓여 검색, 비용, context window까지 흐립니다.

실패 모드

첫째, 같은 파일을 두 세션이 고쳐 conflict가 폭발합니다. 둘째, .env나 untracked fixture가 없어 한쪽 테스트만 실패합니다. 셋째, 생성 파일과 dependency cache가 worktree마다 늘어 디스크와 검색이 무거워집니다. 넷째, session resume을 잘못 골라 다른 branch의 가정을 끌고 옵니다.

시니어 엔지니어의 결론

Claude Code worktree는 바이브코딩을 빠르게 만드는 기능이 아니라 병렬 변경의 경계를 선명하게 만드는 기능입니다. branch 이름, 완료 조건, 테스트 자동화, cleanup까지 묶어야 클로드 코드 기반 AI 코딩이 팀 리뷰 가능한 CLI 자동화와 개발 생산성 향상으로 이어집니다.

참고: Anthropic Claude Code worktrees, common workflows, sessions, llms.txt 문서를 2026-06-14 Asia/Seoul 기준으로 확인했습니다.