claude-code-merge-queue: 병렬 AI 에이전트를 위한 로컬 머지 큐

병렬 AI 에이전트를 위한 로컬 직렬화

claude-code-merge-queue는 단일 코드베이스에서 작업하는 여러 병렬 Claude Code 에이전트를 관리하도록 설계된 로컬, 무비용 머지 큐입니다. 푸시 레이스, 중복된 무거운 빌드, 공유 리소스 테스트 플라키성 등 일반적인 동시성 문제를 방지하기 위해 코드 변경을 착륙, 빌드, 테스트하는 과정을 직렬화합니다.

클라우드 기반 머지 큐와 달리, 이 도구는 개발자의 로컬 머신에서 완전히 실행되므로 매 큐 시도마다 유료 Enterprise 플랜이나 GitHub Actions 분이 필요하지 않습니다.

핵심 기능 및 명령어

이 도구는 Claude Code의 기본 워크트리 생성과 직접 통합되며, 에이전트가 주도하는 변경의 수명 주기를 관리하기 위한 명령어 모음을 제공합니다:

착륙 및 동기화

  • land: FIFO(First-In-First-Out) 큐를 통해 통합 브랜치에 레인을 리베이스하고 푸시합니다. 이를 통해 두 에이전트가 동시에 푸시를 시도하는 상황을 방지합니다.
  • sync: 최신 착륙된 변경을 반영하도록 메인 체크아웃을 fast‑forward하고, lockfile이 변경된 경우 의존성을 재설치합니다.
  • promote: 인간 전용 명령어로, 통합 브랜치를 프로덕션에 배포합니다. 자동화된 프로덕션 배포를 방지하기 위해 에이전트 지시사항에서 명시적으로 제외됩니다.

개발 및 유지보수

  • build-lock: 머신 전체에서 모든 레인에 걸쳐 직렬화된 지정 빌드 명령을 실행해 리소스 경쟁을 방지합니다.
  • preview: 레인의 실시간 작업 트리(커밋되지 않은 변경 포함)를 메인 체크아웃에 미러링하여 전체 빌드 없이 즉시 인간이 검토할 수 있게 합니다.
  • port: 디렉터리 이름을 기반으로 특정 레인의 개발 서버 포트를 계산해 출력합니다.
  • prune: 이미 착륙된 레인의 워크트리를 정리합니다.

기술 구현 및 가드레일

설정 및 초기화

npx claude-code-merge-queue init 로 초기화하면 claude-code-merge-queue.config.mjs 파일을 생성하고 CLAUDE.md를 업데이트해 테스트가 통과하면 에이전트가 자체 작업을 착륙하도록 지시합니다. 또한 .claude/settings.json에 WorktreeCreate 훅을 연결하고, (가능한 경우 Husky를 통해) pre‑push 훅을 설정해 보호된 브랜치에 직접 git push 대신 land를 사용하도록 보장합니다.

안전 메커니즘

  • 비상 해치: 보호된 브랜치에 대한 차단을 우회하려면 사용자가 git push 시 환경 변수 CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1을 설정할 수 있습니다. 이는 보안 경계라기보다 관례 기반 가드레일입니다.
  • 크래시‑세이프 락: 락은 PID 생존 여부로 관리됩니다. 프로세스가 강제 종료(kill -9 등)되면 다음 프로세스가 죽은 PID를 감지하고 락을 회수해 타임아웃이 필요 없게 합니다.
  • 충돌 처리: land 과정에서 리베이스 충돌이 발생하면 도구가 git rebase --abort를 실행하고 작업 트리를 깨끗하게 유지합니다. 이후 에이전트는 CLAUDE.md에 따라 충돌을 해결하고 명령을 다시 실행하도록 지시받습니다.

비교: 로컬 vs. 클라우드 머지 큐

기능 GitHub 머지 큐 Claude Code 머지 큐
프라이빗 레포 지원 Enterprise Cloud 전용 모든 플랜, 모든 레포
비용 시도당 GitHub Actions 분 $0 (로컬 실행)
요구 사항 Pull Request 필요 직접 리베이스 + 푸시

제약 및 한계

  • 인간 검토 부재: checkCommand(예: npm run check)가 유일한 관문입니다. 명령이 통과하면 코드가 착륙됩니다. 병합 전 인간 승인을 위한 내장 메커니즘이 없습니다.
  • 단일 머신 범위: FIFO 큐는 로컬 임시 저장소에 보관됩니다. 여러 머신이 동시에 착륙을 시도하면 표준 Git 비‑fast‑forward 거부가 발생합니다.
  • 처리량 상한: 시간당 착륙 가능한 횟수는 checkCommand 실행 시간에 의해 제한됩니다. 예를 들어 4분짜리 테스트 스위트는 시간당 20건 이하의 착륙으로 제한됩니다.
  • 보안: 이 도구는 보안 경계가 아닙니다; 셸 접근 권한이 있는 사용자는 git push --no-verify 등으로 훅을 우회할 수 있습니다.

커뮤니티 시각

커뮤니티 사용자들은 에이전트 동시성을 관리하기 위한 대안으로 Git 대신 jj(Jujutsu)를 사용해 워크트리와 브랜치를 보다 유연하게 다루거나, 중복 테스트를 피하기 위해 콘텐츠 기반 다이제스트를 활용하는 맞춤형 배포 시스템을 구현하는 방안을 제시했습니다. 일부 개발자는 소규모 운영에서는 대화당 격리된 워크트리를 오케스트레이터 에이전트와 결합해 전용 머지 큐 도구 없이도 유사한 결과를 얻을 수 있다고 언급했습니다.

Sources