서론

Claude Code를 병렬로 실행하고 있는 분들에게 묻고 싶은 것이 있습니다. 세션을 늘릴수록 작업은 빠르게 진행되지만, 그만큼 "누가 지금 어디를 건드리고 있는지"를 완전히 파악하지 못하는 순간이 없었나요? 저의 경우, 출시 직전의 개인 개발 과정에서 실제로 발생했습니다.

출시 작업, 기능 구현 2~4개, 테스트 기반 정비, 운영 문서 업데이트. 이것을 하루에 최대 5개 세션을 병렬로 실행했습니다. 작업 자체는 매우 신속하게 진행되었지만, 그날 하루를 마치고 되돌아보니 3가지 종류의 사고가 일어났다는 것을 깨달았습니다.

발생한 3가지 사고

먼저, 당시의 운영 방식을 설명하겠습니다. 하나의 리포지토리(Repository)에 대해 Claude Code 세션을 여러 개 띄우고, 각각에 다른 작업을 맡깁니다. 작업 트리는 git worktree로 나누고, 완성된 작업은 세션마다 PR(Pull Request)로 만듭니다. 무엇을 했는지에 대한 기록은 일련번호를 매긴 작업 기록 파일(worklog)로 작업당 1개씩 남기고, 세션 간에 전달하고 싶은 내용은 handoff.md라는 하나의 공유 파일에 작성합니다. 당시에는 이런 방식으로 운영했습니다.

첫 번째는 작업 기록용 파일에 매기는 일련번호의 충돌입니다. 이 번호가 같은 날에 3번 충돌했습니다. 47번을 두 개의 세션이 각각 작성해 버렸고, 게다가 제가 착수하기 전에 머릿속으로 예약해 두었던 49번, 50번도 다른 세션에서 먼저 사용되었습니다.

두 번째는 세션 간 인수인계를 위해 두는 handoff.md의 충돌입니다. 이 파일에는 "최종 업데이트"라는 섹션을 두고, 각 세션이 자신의 작업 내용을 덧붙여 쓰는 방식으로 운영했습니다. 그런데 5개의 세션이 거의 동시에 같은 섹션을 수정하려고 했기 때문에, 머지 충돌(Merge Conflict)이 몇 번이나 발생했습니다.

세 번째는 worktree의 소실입니다. 리포지토리 안에 worktree를 만들고 있던 세션이 있었는데, 이를 다른 세션의 뒷정리 작업 중에 삭제되어 버렸습니다. 브랜치 자체는 push 되어 있었기에 실질적인 피해는 없었지만, 삭제된 순간에는 정말 가슴이 철렁했습니다.

세 가지 모두 기술적으로는 단순한 이야기입니다. 일련번호는 그저 숫자이고, handoff는 그저 Markdown이며, worktree는 그저 디렉토리입니다. 그럼에도 사고가 발생한 이유는, 5개의 세션이 "서로의 존재를 모르는" 상태로 같은 리포지토리를 건드렸기 때문이라고 생각합니다.

대화할 수 없는 동료라는 전제에 서기

인간 팀이라면 Slack으로 "거기 건드리고 계신가요?"라고 한마디 건넬 수 있습니다. 하지만 세션끼리는 대화할 수 없습니다. 따라서 충돌을 방지하려면 사전에 자원 할당을 결정해 두는 수밖에 없었습니다.

제가 한 일은 세션에 역할(Lane)을 부여하는 것이었습니다. 사령탑(메인 checkout을 전유하여 원격 조작과 머지 판단을 수행), 구현, 품질, 문서와 같은 방식으로 나눕니다. 누가 무엇을 건드려도 되는지를 사후에 확인하는 것이 아니라, 착수 전에 결정해 두었습니다.

사고와 규칙의 대응

3가지 사고에는 각각 대응하는 규칙을 한 줄씩 추가해 나갔습니다.

이 외에도, 같은 화면의 파일을 2개의 레인에서 동시에 건드리지 않기, package.json이나 마이그레이션(Migration)은 동시에 하나의 세션만 건드리기, 하나의 worktree는 1개 토픽당 1개 PR로 종료하기 등의 예방책도 추가했습니다. 모두 특별한 규칙이 아니라 파일, 번호, worktree별로 담당자를 정하고 있을 뿐입니다.

규칙을 "문서"에서 "스킬"로 만들기

규칙을 적은 절차서는 처음에는 지시문 안에 매번 복사해서 붙여넣었지만, 붙여넣는 것을 잊은 회차에 또 같은 사고가 발생했기에 그만두었습니다.

대신 절차 자체를 스킬(Skill)로서 고정화했습니다. 작업 시작 시의 정형 절차를 호출하는 /worktree-start, 검증과 기록을 4종 세트로 끝내고 PR을 만드는 단계에서 멈추는 /finish, 승인된 PR을 머지하고 뒷정리까지 수행하는 /land, 태스크를 분할하여 각 레인으로의 지시문을 만드는 /dispatch의 4가지입니다. 지시문에 매번 쓰는 운영 방식에서 스킬 이름을 한 번 호출하는 운영 방식으로 바꿈으로써, 누락이라는 사고의 싹 자체를 없앴습니다. 인간 팀에서 CI나 lint를 도입하는 것과 발상이 비슷하다고 생각합니다.

이 기술 자체도 리뷰 대상이 되었습니다. 제가 만든 /dispatch를 Codex에 리뷰하게 했더니, "PR 제목을 쉘 커맨드(shell command)에 직접 삽입하지 마라, 커맨드 인젝션 (command injection)의 여지가 있다", "토픽 이름은 허용 리스트 (allowlist)로 검증하라"는 지적이 돌아왔습니다. 운영 절차서라고 생각하고 작성한 것이었지만, 그 내용물은 쉘 스크립트 (shell script)였기에 코드와 마찬가지로 리뷰되어야 하는 대상이었다는 것을 이 지적을 통해 다시금 깨닫게 되었습니다.

그럼에도 남는 충돌은 머지 순서로 흡수한다

규칙을 아무리 잘 정비해도, 병렬 PR (parallel PR)이 동일한 파일을 건드리는 것 자체를 제로로 만들 수는 없습니다. 이 경우에는 먼저 머지 (merge)할 쪽을 사령탑이 결정하고, 후속 세션이 리베이스 (rebase)나 머지 (merge)를 통해 따라가는 방식으로 흡수하고 있습니다. 규칙을 통해 충돌 발생 자체를 방지하는 계층과, 발생한 충돌을 인간이 순서를 정해 해소하는 계층을 모두 갖추어 두는 이미지입니다.

규칙은 실제로 효과가 있었는가

규칙과 기술을 확립한 후 약 6주간 운용했습니다. 독립된 3가지 기능을 claude -p를 통한 헤드리스 (headless) 실행 3개로 병렬 구현하여 일괄적으로 랜드 (land)하는 방식의 운용도 시도해 보았습니다. 결과적으로 연번 충돌, 핸드오프 (handoff) 경합, 워크트리 (worktree) 소실이라는 3가지 사고는 재발하지 않았습니다. 워크트리 (worktree)를 리포지토리 (repository) 외부에 두기, 핸드오프 (handoff)는 사령탑만 집약하기, 워크로그 (worklog) 번호는 착수 시에 예약하기라는 각각의 규칙이 의도한 대로 기능했다는 실감이 듭니다.

이 기간 동안 새롭게 알게 된 점도 두 가지 있습니다.

하나는 연결이 도중에 끊기더라도 레인의 성과물은 워크트리 (worktree)에 남는다는 것입니다. 헤드리스 (headless) 실행 중 하나가 PR 생성 직전에 API 연결 단절로 인해 중단된 적이 있었는데, 구현과 테스트는 이미 완료된 상태였기에 사령탑이 그대로 검증과 PR 생성을 이어받아 완수할 수 있었습니다. 병렬로 실행 중인 세션 중 하나가 도중에 죽더라도 성과물까지 사라지는 것은 아니라는 점은, 헤드리스 (headless) 병렬 운용을 지속하는 데 있어 든든한 발견이었습니다.

또 다른 하나는 사령탑에 의한 리뷰라는 마지막 관문이 실제로 효과를 발휘한 장면이 있었다는 것입니다. CI 체크는 모두 통과(green)였지만, 랜드 (land)하기 전에 코멘트란을 확인해 보니 중대한 지적 사항이 2건 묻혀 있었습니다. 이 이야기는 사고 방지라기보다는 사고가 나기 직전에 잡아낸 사례에 가깝기에 별도의 글로 분리해 두었습니다.

마치며

돌이켜보면, 병렬 에이전트 (agent) 운용은 "주의하자"라는 마음가짐만으로 막을 수 있는 것이 아니라, 각각 담당자를 정하고 그것을 실행 가능한 형태로 구체화할 수밖에 없다고 생각합니다. 인간의 병렬 개발이 먼저 해왔던 일을, 대화할 수 없는 만큼 앞당겨서 하고 있을 뿐인 이야기일지도 모릅니다.

다만, 몇 세션부터 리뷰가 따라가지 못하게 되는가에 대해서는 아직 답을 내지 못했습니다. 5개 세션은 원활하게 돌아갔지만, 이것이 10개 세션에서도 똑같이 돌아갈지는 솔직히 아직 시도해 보지 못했습니다. 만약 저와 같이 병렬 에이전트 (agent) 운용을 하고 계신 분이 있다면, 세션 수를 어디까지 늘려 사용하고 계시는지 알려주시면 감사하겠습니다.

Discussion