Claude Code 병렬 세션 조율 — 코드·상태·분석을 같은 채널에 얹지 않기
서로 다른 worktree에서 일하는 코딩 에이전트의 코드, 휘발 작업 상태, 분석 문서를 분리해 공유하는 설계와 병렬 작업의 손익을 정리한다.
여러 터미널에서 Claude Code를 띄워 같은 저장소를 고치면 처음에는 실행 속도가 빨라 보인다. 하지만 A가 어떤 파일을 맡았는지 B가 모르고, B가 이미 내린 설계 결정을 A가 처음부터 다시 조사한다면 작업 시간보다 충돌과 통합 비용이 더 커진다.
여기서는 별도 세션을 서로 다른 Git worktree에 두는 경우를 생각한다. worktree와 clone의 차이는 별도 글의 주제다. 이 글은 그 위에서 무엇을 어떤 채널로 공유할 것인가를 다룬다. 핵심은 세션 대화 자체를 실시간 동기화하려 하지 않는 것이다.
같은 저장소를 봐도 세션의 생각은 공유되지 않는다
Git worktree는 같은 저장소의 이력을 참조하지만 작업 디렉터리와 브랜치는 분리할 수 있다. 다른 세션의 미커밋 수정은 자동으로 내 작업 디렉터리에 나타나지 않는다. 커밋한 내용도 다른 브랜치에 자동 반영되지 않으며 명시적 통합이 필요하다. 더 중요한 것은 대화·분석·수정 이유가 Git 객체가 아니라 각 세션의 컨텍스트 안에 있다는 점이다.
공유 대상을 세 층으로 나눴다.
| 대상 | 지속성 | 전달 경로 |
|---|---|---|
| 완료된 코드 | 커밋 뒤 보존 | 브랜치의 커밋을 명시적으로 merge·cherry-pick |
| 담당 파일·진행 상태 | 잠시만 필요 | 모든 worktree가 볼 수 있는 외부 상태 보드 |
| 설계 근거·분석 | 나중에도 필요 | 파일로 기록하고, 상태 보드에서 위치를 가리킴 |
이 분리는 “한 파일에 모든 것을 적자”보다 단순하다. 커밋은 결과물을 전달하고, 보드는 지금의 충돌을 막고, 문서는 왜 그런 결과를 택했는지 전달한다.
상태 보드는 커밋하지 않고 세션당 한 파일로
예를 들어 worktree들이 같은 부모 디렉터리에 있다면 그 부모에 별도 .sessions/ 폴더를 둘 수 있다. 부모가 저장소 바깥이라는 전제라 Git 브랜치에 포함되지 않는다. 위치가 다르면 공유 가능한 다른 임시 경로를 정하면 된다. 중요한 것은 모두가 같은 경로를 읽고, 각 세션은 자기 파일만 쓴다는 규칙이다.
1
2
3
4
5
6
project-worktrees/
├── .sessions/ ← 공유·휘발 상태, Git 저장소 바깥
│ ├── parser.md ← parser 세션만 갱신
│ └── api.md ← api 세션만 갱신
├── parser-worktree/
└── api-worktree/
1
2
3
4
5
6
# parser
- 담당: src/parser/
- 제외: src/api/의 공통 설정
- 상태: 파서 예외 처리 중
- 설계 기록: docs/parser-design.md (아직 통합 전)
- 갱신 시각: 14:30
하나의 보드 파일을 모두가 동시에 고치면 덮어쓰기 경쟁이 생긴다. 세션별 파일은 쓰기 경합을 줄이지만 실시간 합의나 파일 잠금을 제공하지 않는다. 세션이 끝났을 때 낡은 파일을 치우고, 담당 범위가 겹치면 편집 전에 사람 또는 조정자가 우선순위를 정해야 한다. 토큰·고객 정보·비공개 분석 본문도 휘발 보드에 넣지 않는다.
상태와 분석의 수명을 혼동하지 않기
“지금 이 파일을 고치는 중”은 보드의 한 줄이면 충분하다. 반면 “왜 이 API를 교체하는가”는 다음 세션도 알아야 하므로 저장소 문서에 남겨 커밋·통합한다. 아직 결론을 내리지 않은 초안은 양쪽이 읽을 수 있는 임시 파일에 둘 수 있지만, 채택한 설계라면 이력에 남겨야 한다. 계획 모드가 로컬에 저장한 파일도 저장되었다는 사실과 다른 세션이 자동으로 읽었다는 사실은 다르다. 보드에는 분석 내용 전체보다 문서 경로와 통합 상태를 적는다.
작업 순서도 명시적이다. 먼저 담당 범위를 배분하고, 독립 worktree에서 각자 수정한 뒤, 커밋을 통합하고, 통합하는 세션이 전체 변경을 확인한다. 같은 설정 파일을 둘 다 수정해야 한다면 병렬 구현보다 한 명에게 소유권을 주고 나머지는 조사·검토로 역할을 바꾸는 편이 낫다.
병렬화의 조건과 감지의 함정
서로 다른 모듈의 구현이나 구현·조사·검토의 역할 분리는 병렬 이득이 크다. 반대로 모두가 같은 작은 버그를 처음부터 조사하거나 같은 함수의 한 줄을 동시에 고친다면 맥락을 중복 소비한다. 언어 서버가 여러 개 뜨는 비용보다 파일 경계와 통합 비용이 더 큰 변수가 된다.
2026년 7월에는 git worktree list에서 둘 이상의 worktree가 보이면 병렬 조율을 시작하자는 규칙을 검토했다. 이것은 가능성의 신호이지 활동 중인 세션의 증명은 아니다. worktree가 남아 있어도 해당 세션은 종료됐을 수 있고, 같은 worktree에서 두 세션을 열 수도 있다. 사용자가 병렬 작업을 명시하거나 실제 상태 보드에서 유효한 담당자를 확인하는 일이 더 중요하다. 혼자 작업하는데 매번 보드를 관리하는 의례를 만들 필요는 없다.
Git은 코드의 공유를, 보드는 작업 상태의 가시성을, 문서는 지식의 지속성을 담당한다. 세션 컨텍스트를 마법처럼 공유하려 하기보다 어떤 정보가 어느 수명에 속하는지 먼저 정하면 병렬 작업이 안전해진다. 참고: Git worktree 공식 문서.