Ch3. 멀티세션 워크플로우

멀티세션은 여러 작업을 동시에 진행해 대기 시간을 줄이는 방식입니다. 작업끼리 간섭하지 않도록 작업 디렉토리를 분리하는 게 핵심입니다.

왜 멀티세션인가

단일 세션에서는 Claude 응답을 기다려야 하지만, 멀티세션에서는 한 세션이 도는 동안 다른 세션에서 작업을 이어갑니다.

Claude Code는 병렬 작업을 위해 크게 세 가지 메커니즘을 제공합니다.

• git worktree: 파일 편집을 디렉토리 단위로 격리
• agent view (claude agents): 여러 백그라운드 세션을 한 화면에서 디스패치·관리
• subagent / agent team: 한 세션 안에서 작업 자체를 분산·조율

이 챕터에서는 앞의 두 가지(worktree, agent view)를 다룹니다. subagent·agent team은 다음 챕터에서 설명합니다.

git worktree: 핵심 도구

같은 레포지토리에서 여러 세션을 돌리면 파일 충돌이 납니다. git worktree는 저장소 히스토리·리모트를 공유하면서 독립된 작업 디렉토리와 브랜치를 갖는 별도 체크아웃입니다. 세션마다 worktree를 나눠 두면 한 세션에서 기능을 구현하고 다른 세션에서 버그를 고쳐도 서로의 파일을 건드리지 않습니다.

--worktree 플래그로 자동 격리

--worktree(-w) 플래그에 이름을 넘기면 Claude가 격리된 worktree를 만들고 그 안에서 시작합니다. 기본적으로 worktree는 저장소 루트의 .claude/worktrees/<이름>/ 경로에 생성되며, 브랜치 이름은 worktree-<이름>입니다.

# 이름을 지정해 격리된 worktree에서 Claude 시작
claude --worktree feature-auth

# 다른 터미널에서 다른 이름으로 두 번째 격리 세션 시작
claude --worktree bugfix-123

# 이름을 생략하면 'bright-running-fox' 같은 이름이 자동 생성됨
claude --worktree

worktree는 기본적으로 저장소 기본 브랜치(origin/HEAD)에서 분기해 리모트와 같은 깨끗한 트리에서 시작합니다. 리모트가 없거나 fetch가 실패하면 현재 로컬 HEAD로 폴백합니다. 항상 로컬 HEAD에서 분기하려면 설정에서 worktree.baseRef를 "head"로 지정합니다 (허용 값은 "fresh" 또는 "head"뿐이며, 임의의 git ref는 받지 않습니다).

특정 PR에서 분기하려면 #을 붙인 PR 번호나 전체 GitHub PR URL을 넘기면 됩니다. 이 경우 worktree는 .claude/worktrees/pr-<번호>에 생성됩니다.

claude --worktree "#1234"

# 기존 방식: 수동으로 worktree 생성 (저장소 밖에 배치하거나 특정 브랜치를 체크아웃할 때 유용)
git worktree add ../project-feature-auth -b feature-auth
git worktree add ../project-feature-ui -b feature-ui

# 각 worktree에서 별도 Claude 세션 실행
cd ../project-feature-auth && claude
cd ../project-feature-ui && claude

gitignore된 파일을 worktree로 복사 — .worktreeinclude

worktree는 새 체크아웃이라 .env, .env.local 같은 untracked 파일이 들어 있지 않습니다. 프로젝트 루트에 .worktreeinclude 파일을 두면 Claude가 worktree를 만들 때 이런 파일을 자동으로 복사해 줍니다.

# .worktreeinclude (.gitignore 문법 사용)
.env
.env.local
config/secrets.json

패턴과 일치하면서 gitignore된 파일만 복사되므로 tracked 파일이 중복되지는 않습니다. 이 동작은 --worktree, subagent worktree, 데스크톱 앱의 병렬 세션 모두에 적용됩니다.

세션 중 worktree 진입/이탈

EnterWorktree / ExitWorktree 도구를 쓰면 세션 도중에 worktree로 들어가거나 나올 수 있습니다. (v2.1.72) 세션 중 "worktree에서 작업해 줘"라고 요청하면 Claude가 EnterWorktree로 worktree를 만들어 그 안으로 전환합니다. ExitWorktree는 worktree 세션을 종료하고 원래 디렉토리로 돌아옵니다.

EnterWorktree(path)에 경로를 넘기면 새 worktree를 만드는 대신 현재 저장소의 기존 worktree로 전환합니다. (v2.1.105) 이미 준비된 격리 디렉토리로 옮기고 싶을 때 유용합니다. 단, isolation: worktree 등으로 이미 자체 작업 디렉토리에서 도는 subagent에게는 이 두 도구가 제공되지 않습니다.

에이전트 정의에서 선언적 격리

subagent frontmatter에 isolation: worktree를 지정하면 그 에이전트는 늘 격리된 worktree에서 실행됩니다. (v2.1.50) 각 subagent는 임시 worktree를 받고, 변경 없이 종료하면 worktree가 자동으로 사라집니다. subagent worktree도 --worktree와 동일한 base 브랜치를 사용하므로, worktree.baseRef가 "head"가 아니면 기본 브랜치에서 분기합니다.

---
name: reviewer
description: 코드 리뷰 전담 에이전트
isolation: worktree
---

worktree 관리 명령어

# worktree 목록 확인
git worktree list

# worktree 제거 (작업 완료 후)
git worktree remove ../project-feature-auth

# 정리
git worktree prune

새 worktree마다 의존성 설치·가상환경 설정 같은 개발 환경 초기화는 직접 해 줘야 한다는 점을 잊지 마세요.

worktree 정리 동작

worktree 세션을 종료하면 변경 사항이 있는지에 따라 정리 방식이 달라집니다.

• 커밋 안 한 변경·untracked 파일·새 커밋이 모두 없으면: worktree와 브랜치가 자동 제거됩니다. 단, 세션에 이름이 지정돼 있으면 보존 여부를 묻습니다.
• 변경 사항이 있으면: 유지할지 제거할지 묻습니다. 제거하면 디렉토리·브랜치와 함께 커밋하지 않은 변경이 모두 사라집니다.
• 비대화형 실행(--worktree와 -p 조합): 종료 프롬프트가 없어 자동 정리되지 않으므로 git worktree remove로 직접 제거합니다.

WorktreeCreate / WorktreeRemove 훅 이벤트

worktree 생성/제거 시 WorktreeCreate, WorktreeRemove 훅 이벤트가 발생합니다. (v2.1.50) WorktreeCreate 훅은 기본 git worktree 로직을 통째로 대체하므로, SVN·Perforce·Mercurial 등 git 이외의 버전 관리에서도 worktree 격리를 구현할 수 있습니다. 다만 이 경우 .worktreeinclude는 처리되지 않으니 로컬 설정 파일 복사는 훅 스크립트 안에서 직접 해야 합니다.

worktree 세션 재개 시 자동 전환 (v2.1.81)

--resume으로 worktree에서 작업하던 세션을 재개하면, 해당 worktree로 자동 전환됩니다. 세션 피커(/resume)에서도 같은 저장소의 다른 worktree 세션을 고르면 제자리에서 그대로 재개됩니다. 세션 피커에서 Ctrl+W로 저장소의 모든 worktree 세션을, Ctrl+A로 머신의 모든 프로젝트 세션을 볼 수 있습니다.

프로젝트 설정·자동 메모리 공유

같은 리포지토리의 git worktree끼리는 프로젝트 설정과 자동 메모리를 공유합니다. (v2.1.63) 설정을 따로 복사하지 않아도 일관된 환경에서 작업할 수 있습니다.

agent view: 여러 백그라운드 세션을 한 화면에서 관리

claude agents로 여는 agent view는 모든 백그라운드 세션을 한 화면에서 관리하는 도구입니다. 무엇이 실행 중이고, 무엇이 입력을 기다리고, 무엇이 끝났는지 한눈에 보고 필요할 때만 끼어들면 됩니다. 각 백그라운드 세션은 터미널이 붙어 있지 않아도 계속 도는 온전한 Claude Code 대화입니다.

# agent view 열기
claude agents

# 특정 디렉토리 하위 세션만 보기 (v2.1.141+)
claude agents --cwd ~/projects/my-app

백그라운드 세션 디스패치

• agent view 입력창: 프롬프트를 입력하고 Enter를 누를 때마다 새 세션이 시작됩니다. 후속 메시지가 아니라 매번 별도 세션이 생성되어 병렬로 돕니다.
• 세션 내부에서: /background(별칭 /bg)로 현재 대화를 백그라운드로 보냅니다.
• 빈 프롬프트에서 ←: 현재 세션을 백그라운드로 보내고 agent view를 엽니다.
• 셸에서: claude --bg "<프롬프트>"로 곧장 백그라운드 세션을 시작합니다.

# 셸에서 백그라운드 세션 시작
claude --bg "flaky한 SettingsChangeDetector 테스트를 조사해 줘"

# 이름 지정 + 특정 subagent를 메인 에이전트로
claude --bg --name "flaky-test-fix" --agent code-reviewer "PR 1234 리뷰 코멘트 반영"

파일 편집 격리

agent view·/bg·claude --bg 중 무엇으로 시작했든 백그라운드 세션은 작업 디렉토리에서 출발합니다. 파일을 편집하기 직전에 Claude가 세션을 .claude/worktrees/ 하위의 격리된 worktree로 옮겨, 병렬 세션이 같은 체크아웃을 읽되 각자 자기 worktree에만 쓰게 합니다.

git이 어렵거나 부적절한 저장소에서는 worktree.bgIsolation을 "none"으로 설정해 이 격리를 끌 수 있습니다 (v2.1.143+). 이 경우 백그라운드 세션이 작업 사본을 직접 편집합니다.

{
  "worktree": {
    "bgIsolation": "none"
  }
}

백그라운드 세션 종료·삭제

셸에서는 다음 명령으로 백그라운드 세션을 관리합니다.

claude attach <id>     # 이 터미널에서 세션에 연결
claude logs <id>       # 최근 출력 보기
claude stop <id>       # 세션 중지 (claude kill 도 가능)
claude respawn <id>    # 대화를 유지한 채 재시작 (예: 업데이트된 바이너리 적용)
claude rm <id>         # 목록에서 제거 (변경 있는 worktree는 보존하고 경로를 출력)
claude agents --json   # 실행 중 세션을 JSON 배열로 출력

백그라운드 세션은 사용자별 supervisor 프로세스가 호스팅합니다. 터미널을 닫든 agent view를 닫든 계속 돕니다. 세션이 끝난 뒤 약 1시간 동안 연결 없이 방치되면 supervisor가 프로세스를 멈추는데, Ctrl+T로 고정(pin) 한 세션은 예외입니다. 다시 연결·미리보기·답장하면 멈췄던 지점부터 새 프로세스로 이어갑니다.

disableAgentView 설정을 true로 두거나 CLAUDE_CODE_DISABLE_AGENT_VIEW 환경변수를 설정하면 백그라운드 에이전트와 agent view를 완전히 끌 수 있습니다.

/branch로 대화 분기

/branch 명령(구 /fork)은 지금까지의 대화를 복사해 새 세션으로 분기하고, 원본은 그대로 둔 채 분기본으로 전환합니다. 같은 맥락에서 다른 방향을 탐색하고 싶을 때 유용합니다. (v2.1.71, v2.1.77에서 /fork → /branch 이름 변경)

/branch try-streaming-approach

명령줄에서는 --continue 또는 --resume에 --fork-session을 결합합니다.

claude --continue --fork-session

/branch 확인 메시지는 두 개의 세션 ID(새 분기본, 원본)를 출력합니다. 원본으로 돌아가려면 그 ID를 /resume에 넘기거나 세션 피커를 사용합니다. /branch·/rewind·--fork-session으로 만든 분기 세션은 세션 피커에서 루트 세션 아래에 묶여 표시됩니다.

세션 자동 이름 지정

플랜 모드에서 플랜을 수락하면, 이름을 미리 지정하지 않은 경우 플랜 콘텐츠에서 세션 이름이 자동 생성됩니다. (v2.1.77) 직접 이름을 붙이려면 시작 시 claude -n auth-refactor, 세션 중에는 /rename auth-refactor, 세션 피커에서는 Ctrl+R을 사용합니다. 이름을 지정해 두면 claude --resume <이름>이나 /resume <이름>으로 곧장 복귀할 수 있습니다.

--resume 성능 개선

--resume의 로딩 속도가 최대 45% 빨라졌으며, 피크 메모리 사용량이 ~100-150MB 절감되었습니다. (v2.1.77) fork가 많거나 대용량 세션에서 체감이 큽니다.

v2.1.110부터는 --resume / --continue가 만료되지 않은 scheduled task도 함께 복구합니다. /loop나 routine 계열 작업을 병행하는 장기 세션에서 복귀 비용이 줄어듭니다.

tmux로 세션 영속화

agent view를 쓰지 않는 환경이라면 터미널을 닫아도 세션이 살아 있도록 tmux를 활용할 수 있습니다. (백그라운드 세션은 supervisor가 영속화하므로 tmux 없이도 살아 있습니다.)

# 세션 생성
tmux new-session -s auth
tmux new-session -s ui

# 세션 재연결
tmux attach -t auth

세션 수 가이드라인

• 2개: 구현 + 리뷰/리서치 병행
• 3개: 서로 독립적인 기능 3개 병렬
• 4개 이상: 단순 반복 작업에서만 제한적으로 활용 (레이트 리밋 소모 주의)

참고 문서

• worktree로 병렬 세션 실행: https://code.claude.com/docs/en/worktrees (영어)
• agent view로 다중 에이전트 관리: https://code.claude.com/docs/en/agent-view (영어)
• 세션 관리: https://code.claude.com/docs/en/sessions (영어)
• git worktree: https://git-scm.com/docs/git-worktree (영어)
• tmux: https://github.com/tmux/tmux/wiki (영어)