Claude Code를 도입한 팀이 처음 겪는 좌절은 대부분 비슷하다. 몇 시간짜리 디버깅 세션이 아무 경고 없이 날아가거나, 독립적인 작업인데도 순서대로 기다리느라 시간을 낭비하거나, 터미널을 오가며 컨텍스트가 쪼개진다. 이건 Claude Code가 나쁜 도구라서가 아니다. 팀이 아직 이 도구를 어떻게 길들여야 하는지 모르기 때문이다.
세 가지를 설정하면 달라진다. 컨텍스트 압축(Compaction) 대응 Hook, 병렬 세션 운영 패턴, 그리고 Claude Code와 궁합이 맞는 CLI 도구 스택. 이 중 하나라도 빠지면 팀은 도구의 잠재력을 절반도 못 쓴다.
1. Compaction Hook: 컨텍스트 손실은 막을 수 있다
Claude Code는 200K 토큰 컨텍스트 윈도우가 약 95%에 도달하면 자동으로 압축(Auto-Compaction)을 실행한다. 대화 전체를 요약된 형태로 줄이고, 원본은 삭제된다. 문제는 이 요약이 '손실 압축'이라는 점이다. 스택 트레이스는 '오류가 있었음'으로, 3단계 디버깅 체인은 '디버깅을 진행함'으로 뭉개진다. dev.to에 공개된 한 개발자의 사례에 따르면, 1,300회 이상의 세션을 운영하면서 수십 차례 이 문제를 겪었고, 3시간짜리 WebSocket 디버깅 세션 전체를 날린 뒤 Hook 시스템을 직접 구축했다.
해법은 Claude Code의 Hook 시스템을 이용하는 것이다. PreCompact와 PostCompact 두 Hook이 핵심이다.
- PreCompact: 압축 직전에 트리거되어 현재 세션의 전체 트랜스크립트를 SQLite에 저장한다. 요약이 아니라 모든 메시지, 툴 호출, 파일 내용, 오류 출력 전부다. 사람이 판단해서 고르는 게 아니기 때문에 나중에 필요한 것이 사라지는 일이 없다.
- PostCompact: 압축 완료 후 트리거되어 DB에서 관련 컨텍스트를 검색해 재주입한다. 전체 대화를 다시 넣으면 윈도우가 다시 꽉 차니, 프로젝트 요약·최근 세션 노트·유효한 결정 사항 등 구조화된 컨텍스트만 선별해 넣는다.
이 구조의 핵심은 자동화다. 개발자가 압축 타이밍을 예측하거나 수동으로 저장할 필요가 없다. Hook이 알아서 동작한다. DB 설정이 부담스럽다면 최소한 CLAUDE.md에 압축 프로토콜 지침을 명시하는 것만으로도 부분적인 효과를 볼 수 있다. 완전한 자동화는 아니지만, 아무것도 없는 것보다는 낫다.
팀 적용 시 주의점: Hook 코드 자체는 간단하다. 하지만 SQLite 스키마 설계와 PostCompact의 컨텍스트 선별 로직은 프로젝트 구조에 맞게 커스터마이징이 필요하다. 온보딩 초기에 팀 공용 Hook 템플릿을 만들어두는 것을 권장한다. 개발자마다 따로 만들면 결국 관리 포인트가 늘어난다.
2. 병렬 세션: 직렬 세금을 내지 마라
단일 Claude Code 세션은 본질적으로 직렬이다. 태스크 하나를 처리하고, 커밋하고, 다음으로 넘어간다. 문제는 많은 작업이 서로 의존성이 없다는 것이다. 인증 모듈 구현과 대시보드 스캐폴딩이 같은 파일을 건드리지 않는다면, 둘을 순서대로 실행할 이유가 없다. 20분 걸릴 작업을 10분으로 줄일 수 있는데 직렬로 기다리는 건 그냥 낭비다.
해법은 git worktree와 Claude Code의 --headless 모드 조합이다. 패턴은 이렇다.
git worktree add로 동일 레포에 두 번째 작업 디렉토리를 생성한다. 각 워크트리는 독립된 브랜치에서 체크아웃된다.claude --headless -p "[프롬프트]" &로 각 세션을 백그라운드에서 실행한다.wait으로 두 세션이 모두 완료되길 기다린다.- 두 브랜치를 병합하고 워크트리를 정리한다.
이 패턴의 장점은 완벽한 파일 격리다. 두 세션이 서로의 미완성 변경사항을 볼 수 없기 때문에 실행 중 파일 충돌이 없다. 단, 같은 함수를 서로 다른 방식으로 수정하면 병합 충돌이 발생한다. 이건 버그가 아니라 기능이다. 충돌이 명시적으로 드러나는 게, 자동으로 덮어써지는 것보다 훨씬 낫다.
수동 구현은 약 15줄의 셸 스크립트면 충분하다. 하지만 Ctrl+C로 중단하면 백그라운드 프로세스가 고아 상태로 남고, 정리를 빠뜨리면 스테일 워크트리가 레포를 어지럽힌다. 이를 자동화한 cast-parallel 스크립트(github.com/ek33450505/cast-parallel)가 공개되어 있다. 시그널 트랩, PID 기반 브랜치 네이밍, 병합 충돌 보존, 자동 정리를 처리해준다.
언제 쓸까: 6개 이상의 독립 배치가 있는 대형 플랜에 적합하다. 4개 미만이면 워크트리 설정·병합·정리 오버헤드가 이득을 먹는다. 그리고 반드시 dry-run으로 배치 독립성을 먼저 검증하라. 의존성 있는 배치를 병렬로 돌리면 실패한다. API 비용도 두 배라는 점을 잊지 말 것.
3. CLI 도구 스택: 환경이 워크플로우를 결정한다
Claude Code는 터미널 도구다. 터미널 환경이 정비되어 있을수록 Claude와의 협업도 매끄러워진다. 세팅할 가치가 있는 도구들을 추려보면 이렇다.
ripgrep: Claude Code가 코드베이스에서 무언가를 검색할 때 내부적으로 기본 사용하는 도구다. grep보다 압도적으로 빠르고, 대형 레포에서 차이가 극명하게 드러난다. 팀원 개인 머신에도 설치되어 있어야 일관된 경험이 보장된다.
tmux: Claude Code 세션과 에디터, Git UI를 하나의 터미널에서 패인으로 분리해 관리할 수 있다. Claude가 코드를 수정하는 동안 Lazygit 창을 열어 변경 사항을 실시간으로 검토하고, 필요하면 에디터에서 바로 수정하는 워크플로우가 가능해진다. 병렬 세션 운영과도 자연스럽게 연결된다.
Lazygit: Claude Code가 많은 파일을 변경했을 때, 전체 diff를 검토하고 원하는 것만 스테이징하는 작업이 훨씬 쉬워진다. AI가 생성한 코드를 그대로 커밋하는 팀은 없어야 한다. Lazygit은 그 검토 단계의 마찰을 줄인다.
GitHub CLI (gh): Claude에게 GitHub 접근 권한을 주든 안 주든, 개발자 본인이 터미널을 떠나지 않고 PR 생성·리뷰·병합을 처리할 수 있다는 것만으로도 충분히 가치 있다.
Composio (MCP 서버)는 팀마다 판단이 갈릴 수 있다. 500개 이상의 외부 앱을 Claude Code와 연결해주는 도구인데, 이메일 발송이나 슬랙 알림 같은 반복 커뮤니케이션을 자동화하는 데 쓸 수 있다. 하지만 외부 앱 접근 권한 범위를 팀 차원에서 먼저 정의하고 도입해야 한다. 도구가 강력할수록 권한 설계가 먼저다.
팀에 적용하는 순서
세 가지를 동시에 도입하면 부담스럽다. 우선순위를 정해야 한다.
1단계: ripgrep + tmux + Lazygit부터. 설치 비용이 낮고 즉시 효과가 나타난다. 이걸로 팀 전체의 터미널 환경을 표준화한다.
2단계: Compaction Hook 설정. 팀 공용 Hook 템플릿을 만들고 레포에 포함시킨다. 개발자가 긴 세션을 자주 돌리는 프로젝트부터 적용한다.
3단계: 병렬 세션 패턴. 독립 배치가 명확한 대형 플랜이 생겼을 때 시도한다. 처음엔 수동 스크립트로 검증하고, 익숙해지면 cast-parallel로 자동화한다.
도구 세팅보다 중요한 건 팀이 이 설정의 '이유'를 이해하는 것이다. Compaction이 왜 작동 방식인지, 병렬 세션이 왜 직렬보다 나은지, CLI 도구가 왜 Claude Code와 시너지를 내는지를 팀이 이해해야 상황에 맞게 응용할 수 있다. 설정 파일 복붙만 하는 팀은 다음 병목에서 또 멈춘다.