하나의 코디네이터와 다수의 실행자: 대규모 빌드를 위해 정착한 Claude Code 워크플로우
One coordinator, many executors: the Claude Code workflow we’ve settled on for large builds
핵심 요약
Claude Code를 활용해 코디네이터가 계획을 세우고 실행자들이 개별 작업을 수행하는 다중 에이전트 워크플로우를 소개합니다.
- 코디네이터 모델 — 코디네이터는 계획과 범위 설정만 담당하고 실제 코딩은 실행자에게 위임함
- 통신 채널 — 에이전트 간 직접 통신 대신 사람이 직접 중재하여 제어권을 유지함
- 리포지토리 메모리 — 대화 기록 대신 리포지토리에 상태와 결정을 기록하여 지속성을 확보함
- 모델 비용 최적화 — 작업 중요도에 따라 모델 등급을 차등 적용하여 효율성을 높임
범위, 컨텍스트, 의사결정이 개판 나지 않으면서 여러 개의 Claude Code 채팅을 활용해 더 큰 규모의 빌드를 돌리는 방법을 실험해 봤다.
우리가 정착한 모델은 코디네이터 하나에 실행자 여러 명을 두는 방식이다.
Claude 채팅 하나가 코디네이터가 되어 전체 단계를 총괄한다. 코디네이터는 코드를 직접 짜지 않는다. 전체 계획을 잡고, 작업을 단위별로 쪼개고, 각 작업자에게 브리핑을 내리고, 작업자가 다시 던져주는 피드백을 처리하고, 레포지토리의 프로젝트 상태를 최신으로 유지한다.
각 작업 단위는 별도의 새 채팅과 브랜치에서 진행된다. 브리핑에는 다음 내용이 포함된다.
-
목표
-
작업 범위
-
명확하게 제외할 범위
-
종료 조건(exit gate)
작업자는 딱 그 조건까지만 빌드하고 멈춘다.
만약 범위 밖의 문제를 발견해도 "친절하게" 고쳐주지 않는다. 파일이나 함수, 발견한 내용을 그대로 코디네이터한테 다시 던져준다.
채팅끼리는 서로 대화 안 함
이 부분이 아마 요즘 유행하는 멀티 에이전트 트렌드랑은 정반대일 거다.
내가 바로 소통 창구다.
작업자가 나한테 보고하면, 내가 그 내용을 코디네이터한테 전달한다. 코디네이터가 다음 할 일을 정하면, 내가 그 지시를 다시 전달하는 식이다.
에이전트끼리 직접 대화하게 두는 것보다 느려 보일 수 있는데, 실제로 해보면 아주 유용한 통제 지점이 생긴다. 작업자가 제멋대로 범위를 넓힐 수 없고, 모든 중요한 결정이 내려지기 전에 내가 평문으로 다 확인할 수 있다.
리뷰는 새로운 컨텍스트에서 진행
작업자가 작업을 끝내면 그대로 멈춘다.
구현 내용을 전혀 모르는 다른 Claude 채팅이 브랜치를 리뷰하고 심각도에 따라 결과를 반환한다.
코디네이터가 그 결과를 수정 사항으로 만들면, 원래 작업자가 그걸 고치고, 리뷰어가 다시 확인한다.
일반적인 리뷰가 깔끔하게 끝나면, 딱 한 번 제한된 멀티 에이전트 리뷰를 돌린다. 에이전트 숫자는 고정하고, 딱 한 라운드만 한다. 리뷰어의 리뷰어를 검토하는 무한 루프 같은 건 없다.
그다음 내가 배포하고 프로덕션 환경을 체크한다.
그리고 리뷰 끝난 커밋은 절대 수정 안 한다. 리뷰 이후에 바뀐 건 무조건 새 커밋을 찍어서, 단계별로 뭐가 바뀌었는지 아주 쉽게 볼 수 있게 한다.
모델 비용은 작업에 맞춰서
모든 작업에 무조건 제일 좋은 모델을 쓰는 짓도 그만뒀다.
코디네이터는 계획, 아키텍처, 범위 결정 같은 레버리지가 가장 큰 일을 하니까 제일 좋은 모델을 쓴다.
구현 단계는 그보다 한 단계 낮은 모델을 써도 충분하다.
기계적인 체크는 더 싼 모델로 돌린다.
중요한 규칙은 품질은 고정하고, 모델 비용을 변수로 둔다는 거다. 만약 싼 모델이 특정 유형의 작업을 계속 놓치면, 그 작업은 더 좋은 모델로 격상시키고 왜 그랬는지 기록을 남긴다.
Claude랑 Codex를 양자택일하는 게 아니라, Claude가 짠 코드를 Codex로 한 번 더 검토하는 식으로도 활용한다.
레포지토리가 곧 기억이다
또 하나 크게 바뀐 건 중요한 건 뭐든 채팅 기록 밖으로 빼냈다는 점이다.
결정 사항, 상태, 작업 반환, 리뷰 결과, 운영 절차까지 전부 레포지토리에 박아 넣는다.
목표는 완전히 새로운 채팅창을 열어도 다음 달에 와서 현재 상태를 읽고, 이전 대화 내용 없이도 프로젝트를 이어서 할 수 있게 만드는 거다.