Ch3. 멀티세션 워크플로우

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

왜 멀티세션인가

단일 세션에서는 Claude 응답을 기다려야 하지만, 멀티세션에서는 다른 세션에서 동시에 작업을 진행할 수 있습니다.

git worktree: 핵심 도구

같은 레포지토리에서 여러 세션을 돌리면 파일 충돌이 발생합니다. git worktree로 독립된 작업 디렉토리를 만들면 충돌을 줄일 수 있습니다.

--worktree 플래그로 자동 격리

--worktree (-w) 플래그를 사용하면 Claude가 자동으로 격리된 git worktree를 생성하고 그 안에서 시작합니다. (v2.1.49)

# 자동으로 격리된 worktree에서 Claude 시작
claude --worktree

# 기존 방식: 수동으로 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

세션 중 worktree 진입/이탈

EnterWorktree / ExitWorktree 도구를 사용하면 세션 도중에 worktree에 진입하거나 이탈할 수 있습니다. (v2.1.72)

v2.1.105부터는 EnterWorktree(path)로 현재 저장소의 기존 worktree 경로를 직접 지정해 전환할 수 있습니다. 새 worktree를 만들지 않고 이미 준비된 격리 디렉토리로 이동시키고 싶을 때 유용합니다.

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

에이전트 frontmatter에 isolation: "worktree"를 지정하면 해당 에이전트가 항상 격리된 worktree에서 실행됩니다. (v2.1.50)

worktree 관리 명령어

# worktree 목록 확인
git worktree list

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

# 정리
git worktree prune

WorktreeCreate / WorktreeRemove 훅 이벤트

worktree 생성/제거 시 WorktreeCreate, WorktreeRemove 훅 이벤트가 발생합니다. 이를 활용해 worktree별 환경 설정이나 정리 작업을 자동화할 수 있습니다. (v2.1.50)

worktree.sparsePaths — sparse-checkout 지원 (v2.1.76)

worktree.sparsePaths 설정으로 worktree 모드에서 git sparse-checkout을 활성화할 수 있습니다. 대규모 모노레포에서 필요한 디렉토리만 체크아웃해 worktree 생성 속도와 디스크 사용량을 줄입니다.

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

--resume으로 worktree에서 작업하던 세션을 재개하면, 해당 worktree로 자동 전환됩니다. 이전에는 수동으로 worktree 디렉토리로 이동해야 했습니다.

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

같은 리포지토리의 git worktree 간에는 프로젝트 설정과 자동 메모리가 공유됩니다. 별도의 설정 복사 없이 일관된 환경에서 작업할 수 있습니다. (v2.1.63)

/branch로 대화 분기

/branch 명령(구 /fork)을 사용하면 현재 대화의 컨텍스트를 유지한 채 새 세션으로 분기할 수 있습니다. 같은 맥락에서 다른 방향을 탐색하고 싶을 때 유용합니다. (v2.1.71, v2.1.77에서 /fork → /branch 이름 변경, /fork는 별칭으로 유지)

백그라운드 에이전트 일괄 종료

Ctrl+F를 누르면 현재 실행 중인 백그라운드 에이전트를 일괄 종료할 수 있습니다. 실수 방지를 위해 2회 확인이 필요합니다. (v2.1.49)

세션 자동 이름 지정

플랜을 수락하면 플랜 콘텐츠에서 세션 이름이 자동 생성됩니다. (v2.1.77) -n/--name 플래그나 /rename을 사용하지 않아도 의미 있는 세션 이름이 부여됩니다.

--resume 성능 개선

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

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

tmux로 세션 영속화

터미널을 닫아도 세션이 유지되도록 tmux를 활용합니다.

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

# 세션 재연결
tmux attach -t auth

세션 수 가이드라인

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

참고 문서

• git worktree: https://git-scm.com/docs/git-worktree (영어)
• tmux: https://github.com/tmux/tmux/wiki (영어)