Quick Reference

session은 대화 기록을 이어 주고, worktree는 파일 수정 공간을 분리합니다. 같은 파일을 병렬로 바꿀 가능성이 있으면 session만 여러 개 여는 대신 worktree를 나눕니다. session을 재개했다고 이전 파일 상태·권한·branch가 복원되는 것은 아닙니다.

# 현재 대화를 보존하고, 다른 해결책은 새 session에서 시도한다.
claude --resume auth-refactor --fork-session

# 같은 저장소에서 파일 변경을 격리한 병렬 작업을 시작한다.
claude --worktree feature-auth

session을 재개할 때

--continue는 현재 디렉터리의 가장 최근 대화를, 인자 없는 --resume은 picker를 엽니다. picker는 기본적으로 현재 worktree의 대화와 현재 디렉터리를 /add-dir로 추가한 대화를 보여 줍니다. 다른 worktree나 모든 프로젝트까지 넓히는 선택은 가능하지만, 관련 없는 프로젝트의 대화를 고르면 그 위치에서 재개할 명령을 안내할 수 있습니다.

대화 이름은 claude -n auth-refactor 또는 세션 안의 /rename auth-refactor로 정합니다. 같은 session을 두 터미널에서 그대로 재개하면 메시지가 한 transcript에 섞일 수 있습니다. 접근을 갈라야 하면 --fork-session으로 새 session ID를 만들고, 파일 변경도 겹칠 수 있으면 worktree까지 분리합니다.

대화 맥락만 갈라야 한다
  -> --resume <name> --fork-session

파일과 branch도 갈라야 한다
  -> --worktree <name>에서 새 session 시작

이미 재개한 뒤 파일이 달라졌다
  -> pwd, git branch --show-current, git status부터 다시 확인

worktree를 나누는 기준

claude --worktree feature-auth는 Git 저장소에서 격리된 worktree를 만들고 그 디렉터리에서 session을 시작합니다. 기본적으로 저장소 루트의 .claude/worktrees/<name>/ 아래에 만들며, branch 이름은 worktree-<name>입니다. 다른 위치나 생성 규칙이 필요하면 WorktreeCreate hook으로 바꿉니다.

worktree는 working tree와 branch를 분리하지만 Git object database와 일부 repository 상태는 공유합니다. ignored .env 파일, 로컬 database, 생성 cache는 새 worktree에 자동 복사되지 않을 수 있습니다. 필요한 비밀·개인 설정을 무심코 복사하지 말고, 테스트에 꼭 필요한 값만 안전한 제공 방식으로 준비합니다.

자주 틀리는 부분

재개 전 확인
1. 현재 디렉터리와 branch를 본다.
2. git status와 기존 diff를 읽는다.
3. 이전 session의 목표가 아직 맞는지 확인한다.

통합 전 확인
1. 각 worktree의 테스트와 diff를 따로 검토한다.
2. 변경을 한 branch에서 차례로 통합한다.
3. 최종 branch에서 다시 테스트한다.