병렬 Claude Code 에이전트를 위한 로컬 머지 큐, 무엇을 노렸나

여러 개의 코딩 에이전트를 동시에 돌리는 방식은 이제 실험 단계를 지나 실무의 선택지로 들어오고 있다. 문제는 에이전트가 한 명이 아니라 여럿일 때 발생한다. 각 에이전트가 자기 브랜치에서 코드를 만들고, 빌드하고, 테스트하고, 통합 브랜치에 밀어넣는 과정을 동시에 진행하면 서로의 작업이 충돌한다. funador가 Show HN에 공개한 'claude-code-merge-queue'는 바로 이 지점을 겨냥한 로컬 머지 큐 도구다. 여러 에이전트의 랜딩(landing) 작업을 직렬화해 한 번에 하나씩만 통합 브랜치로 들어가도록 순서를 강제한다.

병렬 에이전트가 만드는 세 가지 사고

프로젝트가 정면으로 겨냥하는 문제는 세 가지다. 첫째는 푸시 경합(push race)으로, 두 에이전트가 거의 동시에 같은 통합 브랜치로 푸시하면서 서로의 커밋을 밀어내거나 히스토리를 꼬이게 만드는 상황이다. 둘째는 중복된 무거운 빌드다. 각 에이전트가 독립적으로 전체 빌드를 돌리면 같은 결과를 얻기 위해 CPU와 시간을 몇 배로 낭비한다. 셋째는 공유 자원 테스트의 불안정성(flakiness)으로, 여러 테스트가 같은 포트나 데이터베이스 같은 자원을 동시에 붙잡으면서 실제 버그가 아닌 우연한 실패가 발생하는 경우다. 랜딩을 직렬화한다는 것은 결국 이 세 가지가 구조적으로 일어날 수 없게 만든다는 뜻이다.

발상 자체는 새로운 것이 아니다. 랜딩을 순서대로 세우고, 병합 전에 테스트를 돌리고, 히스토리를 깨끗하게 유지한다는 개념은 GitHub의 머지 큐나 여러 CI 서비스가 이미 제공하는 기능이다. 이 도구의 차별점은 '어디서 도는가'에 있다. 남의 과금 클라우드가 아니라 개발자의 로컬 머신에서 무료로 돌린다는 것이 핵심 주장이다. 에이전트가 늘어날수록 클라우드 CI 비용도 함께 늘어나는 구조를 감안하면, 로컬에서 무료로 순서를 정리한다는 접근은 나름의 실무적 설득력을 가진다.

설정은 한 파일, 오류는 즉시

설정은 하나의 파일에 모두 담긴다. 저장소의 예제 파일에 모든 항목이 주석과 함께 정리돼 있고, 잘못된 설정은 명령이 그 파일을 읽어들이는 순간 곧바로 요란하게 실패하도록 설계됐다. 빈 브랜치 이름, 음수 포트, 그리고 프로덕션 브랜치와 통합 브랜치가 같은 값으로 지정된 경우처럼 흔한 실수를 잡아내며, 문제가 여러 개면 발견된 모든 문제를 한꺼번에 나열한다. 세 단계 뒤에서 원인 모를 에러로 터지는 대신 시작 지점에서 전부 드러내겠다는 의도다. 실무자 입장에서는 설정 디버깅에 쓰는 시간을 줄여주는 실용적인 선택이다.

강제력은 pre-push 훅으로 구현된다. 통합 브랜치로 직접 git push를 시도하면 훅이 이를 거부하고, 대신 실행해야 할 실제 명령을 안내한다. 즉 랜딩 절차를 거치지 않고는 통합 브랜치에 들어갈 수 없다. 같은 훅이 랜딩을 승인하기 전에 checkCommand를 실행하는데, checkCommand가 설정돼 있지 않으면 기본적으로 모든 푸시가 실패한다. 검증 없이는 아무것도 통과시키지 않겠다는 안전 우선의 기본값이다.

막힌 길에는 반드시 빠져나갈 문이 있다

다만 모든 차단에는 탈출구가 있다. 통합 브랜치든, 프로덕션 브랜치든, protectedBranches에 지정한 어떤 브랜치든 막힌 푸시에는 통과할 방법이 마련돼 있다. 환경 변수 하나면 되고, 별도의 프롬프트나 기억해야 할 이차 인증은 없다. 대신 일반적인 우회 플래그가 아니라 통과시키려는 특정 브랜치 이름을 직접 지정해야 한다. 손이 미끄러져 실수로 우회하는 일을 막으려는 장치다.

여기서 개발자가 분명히 선을 긋는 지점이 중요하다. 이것은 하드한 보증이 아니라 하나의 관례(convention)라는 점이다. 실수나 엉뚱한 푸시는 막아주지만, 스스로 환경 변수를 설정해버리는 적대적인 에이전트까지 통제하지는 못한다. 즉 이 도구는 보안 경계가 아니라 규율을 위한 장치이며, 신뢰할 수 있는 에이전트와 사람의 실수를 전제로 동작한다. 자율성이 높은 에이전트에게 이런 우회 능력이 있다면 관례는 언제든 무너질 수 있다는 점을 감안해 도입 여부를 판단해야 한다.

라이선스는 MIT이며, 개발자는 포크해서 이름을 바꾸고 설정 구조를 두고 논쟁하라는 것이 이 프로젝트의 취지라고 밝혔다. 정해진 정답을 제시하기보다 병렬 에이전트 시대에 랜딩 규율을 어떻게 잡을지에 대한 하나의 참조 구현으로 읽는 편이 적절하다. 팀 규모의 정식 머지 큐를 대체할 물건은 아니지만, 여러 에이전트를 로컬에서 굴리며 통합 브랜치가 자주 꼬이는 개발자라면 검토해볼 만한 가벼운 방어선이다.