Claude Code 세션 간 통신으로 컨텍스트 한계 깨는 법 — 독립 윈도우 3개 실전 설정

Claude Code로 큰 프로젝트를 진행하다 보면 컨텍스트가 금방 포화됩니다. 지난주 대시보드 리팩토링 중 세 번째 컴포넌트 작업에서 첫 설계를 까먹었어요. 200K 토큰 윈도우도 파일 여러 개 열면 순식간에 찹니다.

이 글을 읽고 나면 마스터 세션에서 기획·문서를 관리하고 코딩은 워크트리별 독립 세션에 맡기는 구조를 만들 수 있어요. 각 세션이 독립 컨텍스트 윈도우를 가지니까 손실이 거의 사라지더라고요. 저는 이 방식으로 5시간 연속 자율 실행을 세 번 돌렸습니다.

준비물

먼저 필요한 환경을 챙기세요.

• Claude Code 구독 (프로 플랜 권장 — 무료는 세션당 메시지 제한이 있어요)
• Git 2.25 이상 (워크트리 기능 사용)
• VSCode 또는 터미널 (세션 여러 개를 띄울 수 있는 환경)
• 프로젝트 루트에 .claude/ 폴더 (세션 간 통신용 핸드오프 파일 저장소)

구독 플랜은 공식 페이지에서 확인하세요. 제가 테스트한 시점 기준으로 프로 플랜은 세션당 제한이 훨씬 느슨했어요.

마스터 세션은 어떻게 설정하나요?

마스터 세션은 전체 구조를 보는 지휘소입니다. 여기서는 코드를 직접 건드리지 않고 기획·문서·체크리스트만 관리해요.

1. 핸드오프 구조 만들기

프로젝트 루트에 .claude/handoffs/ 폴더를 생성합니다. 이 폴더가 세션 간 데이터 교환 허브예요.

mkdir -p .claude/handoffs
touch .claude/handoffs/task-list.md
touch .claude/handoffs/architecture.md

마스터 세션에서 Claude에게 이렇게 요청하세요.

"이 프로젝트의 전체 아키텍처를 .claude/handoffs/architecture.md에 정리해줘. 
각 모듈의 책임과 의존성을 명확히 써줘."

Claude가 구조를 분석해서 파일로 남기면 이게 다른 세션의 나침반이 돼요.

2. 태스크 분해 및 핸드오프 작성

다음으로 작업을 독립 단위로 쪼갭니다. Claude에게 태스크 목록 작성을 맡기면 됩니다.

"task-list.md에 작업 3개를 독립 태스크로 분해해줘. 
각 태스크마다 필요한 컨텍스트 파일 목록도 적어줘."

생성된 핸드오프 파일은 이런 형태로 나옵니다.

Task 1: 인증 모듈 구현
- 파일: src/auth/login.ts, src/auth/session.ts
- 의존성: architecture.md 섹션 2
- 완료 조건: 로그인 성공 시 JWT 발급

Task 2: 대시보드 UI
- 파일: src/components/Dashboard.tsx
- 의존성: architecture.md 섹션 3
- 완료 조건: 3개 위젯 렌더링

각 태스크가 다른 세션에서 독립 실행됩니다. 저는 인증·대시보드·API 레이어 세 개로 나눴어요.

워크트리별 독립 세션은 어떻게 시작하나요?

이제 Git 워크트리로 작업 공간을 물리적으로 분리합니다. 각 워크트리가 독립 세션의 집이에요.

git worktree add ../myproject-auth auth-task
git worktree add ../myproject-dashboard dashboard-task

두 개 브랜치를 만들었습니다. ../myproject-auth와 ../myproject-dashboard 폴더가 생겼어요.

핸드오프 공유 연결 (필수 단계)

워크트리마다 .claude/ 폴더가 독립 복사되면 마스터 업데이트가 워커에게 안 보입니다. 저는 첫날 이 단계를 건너뛰어서 2시간을 날렸어요. 각 워크트리에서 .claude/를 심볼릭 링크로 연결해야 합니다.

cd ../myproject-auth
rm -rf .claude
ln -s ../myproject/.claude .claude

cd ../myproject-dashboard
rm -rf .claude
ln -s ../myproject/.claude .claude

이제 모든 워크트리가 같은 .claude/handoffs/를 봐요. 마스터가 architecture.md를 갱신하면 워커 세션에 즉시 반영됩니다.

각 워크트리에서 Claude Code를 별도로 실행하세요. VSCode라면 폴더를 새 창으로 열고 각 창에서 Claude 세션을 시작하면 됩니다.

첫 번째 워크트리(auth)에서 다음 명령으로 작업을 시작합니다.

".claude/handoffs/task-list.md의 Task 1을 읽고 인증 모듈을 구현해줘. 
완료되면 결과를 .claude/handoffs/auth-result.md에 써줘."

작업이 끝나면 auth-result.md에 구현 내용·테스트 결과·남은 이슈가 정리됩니다. 저는 이 파일로 진행 상황을 추적했어요.

두 번째 워크트리(dashboard)에는 Task 2를 맡깁니다. 각 세션이 독립 윈도우를 쓰니까 간섭이 없어요. 저는 세 세션을 동시에 돌렸는데 각 세션이 50K 토큰씩 써도 전체는 150K로 분산됐어요. 단일 세션은 금방 포화되지만 나눠 쓰니까 여유가 생겼습니다.

자동 게이트는 어떻게 설정하나요?

세션이 몇 시간씩 자율로 돌아가려면 코드 체크 게이트가 필요해요. 결과물이 엉망이면 자동으로 멈춰야죠.

1. 린트 게이트 추가

각 워크트리 루트에 .claude/gates/lint.sh 스크립트를 만드세요. 세션이 코드 수정 후 실행해서 FAIL이 나오면 변경을 되돌립니다.

#!/bin/bash
npm run lint
if [ $? -ne 0 ]; then
  echo "FAIL: 린트 에러 발생"
  exit 1
fi
echo "PASS: 린트 통과"
exit 0

타입 체크 게이트(tsc --noEmit)도 추가했더니 타입 에러 누적을 막았어요.

2. 테스트 게이트

유닛 테스트가 있다면 테스트 게이트도 유용합니다.

#!/bin/bash
npm test -- --coverage
if [ $? -ne 0 ]; then
  echo "FAIL: 테스트 실패"
  exit 1
fi
echo "PASS: 테스트 통과"
exit 0

이 게이트를 켜두고 5시간 자율 실행을 돌렸을 때, 중간에 세 번 테스트가 실패해서 자동으로 롤백됐어요. 사람이 안 봐도 품질이 유지됐어요.

흔한 실수와 해결법

세션이 서로 같은 파일을 동시에 수정해서 충돌이 났어요

Task를 나눌 때 파일 단위로 완전 분리하지 않으면 이런 일이 생겨요. 저는 utils.ts를 두 세션이 동시에 건드려서 머지 충돌 3개를 손으로 풀었어요.

해결: 태스크 분해 시 파일 경로가 안 겹치게 하세요. 공통 유틸은 미리 마스터에서 확정하고 잠그는 게 낫습니다.

게이트 스크립트에 실행 권한이 없어서 매번 실패했어요

chmod +x .claude/gates/*.sh를 잊으면 게이트를 못 돌려요. 저는 10번 시도 끝에 눈치챘어요.

해결: 게이트 스크립트를 만들자마자 실행 권한을 주세요. Git 커밋 시 권한도 보존됩니다.

워크트리 설정 후 핸드오프가 안 보인다면

앞 단계에서 심볼릭 링크 연결을 건너뛰었다면 각 워크트리가 독립 복사본을 갖게 돼요. 마스터 업데이트가 워커 세션에 안 보이는 증상이 나타납니다.

다음 단계

이 워크플로우를 설정하면 프로젝트가 커져도 컨텍스트 부족에 안 막혀요. 저는 다음 단계로 CI/CD 파이프라인도 독립 세션에 맡길 계획입니다.

핵심은 기획과 실행 분리예요. 마스터 세션은 지도를 그리고, 워커 세션은 지도를 보고 달립니다. 각자 독립 컨텍스트를 쓰니까 효율이 3배는 올라요.

지금 당장 .claude/handoffs/ 폴더를 만들고 첫 핸드오프를 써보세요. 한 번 경험하면 단일 세션으로 안 돌아가요.

자주 묻는 질문

Q. 세션이 몇 개까지 동시에 돌릴 수 있나요?

A. 저는 3개까지 안정적으로 돌렸어요. 그 이상은 핸드오프 관리가 복잡해져서 마스터가 추적을 놓쳐요. 태스크 5개 이상이면 배치로 나눠 순차 실행이 낫더라고요.

Q. 무료 플랜으로도 가능한가요?

A. 가능하지만 세션당 메시지 제한으로 자율 실행이 짧아요. 무료로 테스트했을 때 1시간 만에 한도가 찼어요. 프로 플랜이면 5시간 이상도 문제없죠.

Q. 워크트리 대신 브랜치만 따로 체크아웃하면 안 되나요?

A. 브랜치 전환은 같은 폴더에서 파일이 바뀌니까 세션이 혼란스러워해요. 워크트리는 물리적으로 다른 경로라 각 세션이 독립 작업할 수 있죠. 충돌도 훨씬 적어요.

Q. 마스터 세션도 코딩을 하면 안 되나요?

A. 하지 말라는 건 아니지만 컨텍스트가 섞여 비효율적이에요. 마스터는 구조·문서·체크리스트에만 집중하고 코드는 워커에게 맡기는 게 윈도우 활용도가 높아요. 역할을 섞었다가 컨텍스트가 다시 포화됐어요.