Claude Code worktree 병렬 작업은 무엇을 나눌지부터 정한다

기능 하나를 맡기고 끝날 때까지 기다리다 보면 다른 작업도 동시에 돌리고 싶어진다. 터미널 탭을 하나 더 열고 같은 폴더에서 Claude를 하나 더 실행하는 것이 가장 쉬운 방법이다. 두 세션이 같은 파일을 고치기 전까지는 그렇다. 병렬 작업에서는 무엇을 나눌지부터 정한다. 파일 변경이 겹칠 수 있으면 worktree로 작업 폴더를 나누고, 같은 배경에서 방향만 갈라 보려면 대화를 분기하고, 짧은 질문과 오래 걸리는 명령은 메인 대화를 막지 않는 방식으로 처리한다. 여러 세션은 Agent View 한 화면에서 관리한다

3편까지 기존 코드를 정비했고, 이 글부터 새 기능을 추가한다. Git 브랜치와 병합의 기을 안다고 가정한다. 다 읽으면 worktree를 만들기 전에 무엇을 커밋·푸시해야 하는지, 대화 분기와 worktree 중 무엇을 쓸지 판단할 수 있다.

Agent View에서 여러 세션을 한 화면으로 본다

강의는 터미널 탭마다 Claude를 띄우던 방식 대신 Agent View를 소개한다. 현재 문서의 설명으로 Agent View는 백그라운드 세션 전체를 한 화면에 모아 무엇이 실행 중이고 무엇이 입력을 기다리며 무엇이 끝났는지 보여 준다(agent-view). 연구 미리보기(research preview) 단계의 기능이다

claude agents          # Agent View 열기
claude --bg "<프롬프트>" # 백그라운드 세션 바로 시작

세션 안에서 입력창이 비어 있을 때 왼쪽 방향키(←)를 누르면 현재 세션이 백그라운드로 가고 Agent View가 열린다. 강의에서 쓴 방법이 이것이다. Agent View에서 프롬프트를 입력하고 Enter를 누르면 새 백그라운드 세션이 생긴다. 상태는 Working, Needs input, Idle, Completed, Failed, Stopped로 표시된다

강의는 끝난 세션을 Ctrl+X로 목록에서 정리했다. 문서 기준으로 Ctrl+X는 끝난 세션 전용 키가 아니다. 한 번 누르면 세션을 멈추고, 2초 안에 한 번 더 누르면 삭제한다. 작업 중인 세션에서 실수로 두 번 누르지 않도록 주의한다

같은 파일을 건드리는 작업은 worktree로 나눈다

강의는 다크 모드와 반응형 디자인을 동시에 만든다. 일부러 고른 조합이다. 둘 다 Tailwind 클래스를 많이 건드리므로 같은 폴더에서 돌리면 한 세션의 변경을 다른 세션이 덮어쓸 가능성이 크다

worktree는 Git 기능이다. 하나의 저장소에 연결된 별도 작업 디렉터리를 만들고, 디렉터리마다 다른 브랜치를 체크아웃한다. 강의는 “프로젝트 복사본”이라고 비유하지만 저장소를 통째로 복제하는 git clone과는 다르다. 커밋 이력과 원격 설정은 .git을 공유하고, 작업 파일과 브랜치만 따로 가진다(git-worktree)

저장소 (.git 공유)
 ├── 메인 체크아웃          main 브랜치          ← 내가 작업
 ├── .claude/worktrees/dark-mode   worktree-dark-mode   ← 세션 A
 └── .claude/worktrees/responsive  worktree-responsive  ← 세션 B

그림처럼 세 디렉터리는 같은 저장소의 서로 다른 브랜치다. 세션 A와 B는 각자 자기 폴더의 파일만 고치므로 작업 중에는 충돌하지 않는다. 충돌은 나중에 브랜치를 합칠 때 한 번에 조정한다

만드는 방법은 두 가지다. 대화에서 요청에 “worktree를 사용해서”를 붙이면 Claude가 EnterWorktree 도구로 worktree를 만들고 그 안에서 일한다. 시작할 때 만들려면 --worktree(또는 -w)를 쓴다

worktree를 사용해서 웹사이트에 다크 모드를 추가해 줘.

claude --worktree responsive

기본 위치는 저장소 루트의 .claude/worktrees/<이름>/이고, 새 브랜치 이름은 worktree-<이름>이다(worktrees). 이름을 빼면 bright-running-fox 같은 이름이 자동으로 붙는다. 메인 체크아웃에서 이 폴더가 추적되지 않은 파일로 보이지 않도록 .claude/worktrees/를 .gitignore에 넣어 둔다

worktree는 커밋하지 않은 변경을 가져가지 않는다

강의에서 두 worktree가 돌기 시작한 뒤 강사가 실수를 발견한다. 앞서 한 리팩터링과 예약 취소 기능을 커밋하지 않았다. 그래서 두 세션은 초기 Clipper 코드 위에 다크 모드와 반응형을 입히고 있었다. 강사는 worktree가 “마지막으로 커밋된 상태”에서 출발한다고 설명하고, worktree를 만들기 전에 커밋하라고 정리한다

현재 문서는 한 단계 더 나간다. 출발점은 worktree.baseRef 설정이 정한다. 기본값 "fresh"는 원격 저장소의 기본 브랜치(보통 origin/main)에서 갈라진다(worktrees). 로컬에 커밋만 하고 푸시하지 않은 변경도 기본값에서는 worktree에 들어가지 않는다는 뜻이다. 원격이 없거나 origin/HEAD를 알 수 없을 때만 로컬 HEAD로 대신한다

`worktree.baseRef`	출발점	미커밋 변경	푸시 안 한 커밋
`"fresh"` (기본)	원격 기본 브랜치	포함 안 됨	포함 안 됨
`"head"`	현재 로컬 `HEAD`	포함 안 됨	포함됨

강의 프로젝트는 강의 저장소를 git clone해서 시작했으므로, 기본값이 "fresh"였다면 원격의 초기 코드에서 출발한 것도 설명이 된다. 강의 당시 버전의 동작이 어느 쪽이었는지는 확인할 수 없다. 현재 기준으로 진행 중인 작업 위에서 worktree를 만들려면 커밋한 뒤 푸시하거나, 설정을 "head"로 바꾼다

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

"head"도 커밋되지 않은 변경은 가져가지 않는다. 어느 설정이든 worktree를 만들기 전에 커밋하라는 강의의 결론은 유효하다

worktree에는 무엇이 없는가

worktree는 새로 체크아웃한 폴더라서 Git이 추적하지 않는 파일이 없다

node_modules 같은 의존성: worktree 안에서 다시 설치해야 한다
.env 같은 gitignore 대상 파일: 프로젝트 루트에 .worktreeinclude를 두면 새 worktree마다 복사된다
CLAUDE.local.md: 만든 worktree 안에만 존재한다(1편 참고)

.worktreeinclude는 .gitignore 문법을 쓰고, 패턴에 맞으면서 gitignore 대상인 파일만 복사한다

.env
.env.local

반대로 공유되는 것도 있다. v2.1.211부터 worktree 세션에서 Bash 명령에 “don’t ask again”을 고르면 메인 체크아웃의 .claude/settings.local.json에 저장되어 다른 worktree에도 적용된다

병합과 정리

두 작업이 끝나면 각 세션에 들어가 /diff로 변경을 확인한다. 강의는 결과가 만족스럽다고 가정하고 새 세션에 이렇게 요청했다

현재 작업 디렉터리의 커밋하지 않은 변경을 모두 커밋하고,
다크 모드와 반응형 브랜치를 병합하도록 도와줘.

git branch로 보면 기본 브랜치와 worktree용 브랜치 두 개가 있다. worktree는 작업 폴더이고, 합치는 대상은 그 안의 브랜치다. 둘 다 같은 Tailwind 코드를 건드렸으므로 병합 충돌을 조정하는 단계가 따른다

병합이 끝난 worktree는 지운다. 대화형 세션을 끝낼 때 worktree가 깨끗하면 이름 없는 세션은 worktree와 브랜치를 자동으로 지우고, 이름 붙인 세션은 먼저 묻는다. 변경이나 새 커밋이 남아 있으면 유지할지 지울지 묻는다. -p로 실행한 비대화형 세션은 정리하지 않으므로 git worktree remove로 직접 지운다(worktrees)

같은 배경에서 두 방향을 검토할 때는 대화를 분기한다

파일 대신 대화의 방향을 나누고 싶을 때도 있다. 강의의 예는 계정 없이 고객이 자기 예약을 찾게 해 달라는 CEO의 요청이다. Claude에게 구현 방법 두 가지를 묻고, A안과 B안을 각각 계획하게 한다

현재 Claude Code에는 대화를 가르는 명령이 두 개 있다(commands)

명령	동작	원래 대화
`/fork`	현재 대화를 새 백그라운드 세션으로 복사한다. 프롬프트를 주면 복사본이 바로 시작한다	그대로 이어서 쓴다
`/branch`	이 시점에서 대화의 가지를 만들고 그 가지로 전환한다	`/resume`으로 돌아간다

강의는 /fork로 “B안의 계획을 세워 줘”를 복사본에 보내고, 원래 대화에는 “A안의 계획을 세워 줘”를 보냈다. Agent View에서 두 세션이 나란히 진행된다. 강사의 비유로는 같은 과거를 공유하지만 앞으로 갈 길이 다른 대화다. /fork는 v2.1.212 이상이 필요하다

강사는 fork를 논의와 계획에만 쓰고, 두 안을 실제로 구현할 때는 worktree로 파일 변경을 나눈다고 했다. 분기한 대화들이 같은 폴더를 고치면 앞에서 본 덮어쓰기 문제가 그대로 생기기 때문이다

두 계획 중 하나를 골라야 할 때는 /export로 대화를 내보낸다. 파일 이름을 주면 바로 저장하고, 주지 않으면 클립보드 복사와 파일 저장 중 고르는 창이 뜬다. 결과는 일반 텍스트다. 강의는 두 계획 파일을 동료에게 보내거나, 더 강한 모델에게 주고 어느 쪽이 나은지 물어보는 방법을 소개한다

작업을 끊지 않고 묻고 기다린다

/btw

Claude가 긴 작업을 하는 중에 메시지를 보내면 작업이 끝날 때까지 대기열에 쌓인다. 짧게 궁금한 것이 생겼다면 /btw를 쓴다

/btw Cloudflare의 env가 뭐야?

/btw는 메인 작업을 끊지 않고 현재 대화의 맥락을 참고해 답한다. 현재 문서 기준으로 이 답변에는 파일 읽기, 명령 실행, 검색 같은 도구를 쓰지 않는다. 질문과 답은 대화 기록에 들어가지 않고 닫을 수 있는 오버레이로 뜬다(interactive-mode). 강의의 설명대로 새 작업을 시키는 기능은 아니다. 도구가 필요한 질문이면 오버레이에서 f를 눌러 도구를 쓰는 서브에이전트로 넘길 수 있다

백그라운드 명령과 /tasks

강의에서는 그동안 별도 탭에서 npm run dev를 켜 두었다. 개발 서버는 스스로 끝나지 않는 명령이다. Claude의 셸에서 실행한 뒤 Ctrl+B를 누르면 백그라운드로 넘어가고 메인 대화를 계속 쓸 수 있다. tmux 안에서는 두 번 누른다

/tasks는 현재 세션의 백그라운드 작업 목록을 보여 준다. 끝난 서브에이전트도 포함된다. 백그라운드 작업은 Claude Code를 종료하면 함께 정리된다(interactive-mode). 빌드나 오래 걸리는 테스트도 같은 방식으로 뒤에 보낼 수 있다

! 셸 모드

입력창 맨 앞에 !를 쓰면 Claude를 거치지 않고 셸 명령을 바로 실행한다. 강의에서는 커밋까지 스킬로 처리한 뒤 푸시만 직접 했다

! git push origin main

명령과 출력은 대화 컨텍스트에 들어간다. 현재 문서 기준으로 v2.1.186부터 Claude가 셸 모드의 출력에 자동으로 응답한다. 예전처럼 출력만 남기고 응답을 받지 않으려면 respondToBashCommands를 false로 둔다(interactive-mode). 셸 모드 명령은 Claude가 해석하거나 승인을 요청하지 않고, 엄격 샌드박스 모드가 아니면 샌드박스 밖에서 실행된다. 내가 직접 치는 명령이므로 되돌릴 수 없는 명령은 내가 확인한다

Remote Control로 자리를 비워도 세션을 이어 간다

Remote Control은 내 컴퓨터에서 실행 중인 Claude Code 세션을 Claude 모바일 앱이나 claude.ai/code에서 이어 쓰게 한다. 원격 서버에서 새로 실행하지 않고 로컬 세션에 연결한다

claude --remote-control   # 원격 제어를 켠 대화형 세션 (--rc)
/remote-control           # 실행 중인 세션에서 켜기 (/rc)

claude remote-control로 서버 모드를 띄우면 URL과 QR 코드도 받을 수 있다. 조건은 Pro·Max·Team·Enterprise 요금제와 /login 로그인이고, API 키로는 쓸 수 없다. Team과 Enterprise는 관리자가 먼저 켜야 한다. 컴퓨터가 켜져 있고 claude 프로세스가 계속 실행 중이어야 한다(remote-control)

강의에서는 휴대전화로 “simplified 라벨이 붙어 있는 열린 PR을 보여 줘”라고 입력하자 컴퓨터 화면에도 같은 메시지가 나타났다. 이어서 “전부 병합해 줘”라고 보냈다. 강사도 이것이 좋은 일인지는 각자 판단하라고 했다. 휴대전화 화면에서는 diff를 제대로 읽기 어렵다. 조사 진행 상황 확인, 코드 동작 질문, 리뷰 에이전트 실행처럼 되돌리기 쉬운 일에 쓰고, 병합처럼 되돌리기 어려운 일은 3편의 검증을 거친 뒤에 하는 편이 낫다

무엇을 나눌지로 도구를 고른다

나누고 싶은 것	도구
파일 변경 (같은 파일을 동시에 고칠 수 있다)	worktree
대화의 방향 (같은 배경, 다른 계획)	`/fork`, `/branch`
도구가 필요 없는 짧은 질문	`/btw`
끝나지 않거나 오래 걸리는 명령	`Ctrl+B`, `/tasks`
여러 세션의 상태 확인	Agent View (`claude agents`)
내가 있는 장소	Remote Control

병렬 작업을 시작하기 전에 두 작업이 같은 파일을 고칠 수 있는지 먼저 묻고, 그렇다면 커밋과 푸시를 마친 뒤 worktree로 나눈다

출처

nomadcoders

Claude Code 병렬 작업은 worktree로 파일을, 세션으로 대화를 나눈다