Claude Code를 위한 Orchestrator-Worker 시스템을 구축한 방법

Source: Dev.to

문제

여러 레포(백엔드, 프론트엔드, 어드민, 인프라)를 동시에 작업할 때는 다음이 필요합니다:

• 코드를 절대 건드리지 않는 코디네이터
• 하나의 작업에만 집중하는 워커
• 세션 간 깔끔한 핸드오프

Claude Copilot이 메모리와 작업 인프라를 제공했습니다. 나는 여기에 코디네이션 레이어를 추가해야 했습니다.

내가 만든 것

Orchestrator (조정만 하고 실행은 하지 않음)

• 모든 레포의 상태를 추적
• 어떤 워커 명령을 실행할지 알려줌
• 스프린트 보드와 인보이스 업데이트
• Notion과 동기화

Workers (격리된 실행)

• git worktree에서 실행 (브랜치 전환 충돌 없음)
• git flow(feature/ 브랜치) 사용
• 메모리를 통해 진행 상황 보고
• 엄격한 start/done 명령 보유

Makefile‑based

Python 의존성 없이, 다음과 같이 사용:

make worker-new REPO=backend TASK=fix-migration

핵심 설계 결정

1. Human‑in‑the‑loop
   워커는 자동으로 생성되지 않습니다. 언제 시작할지 직접 결정해 제어권을 유지하면서도 작업을 병렬화합니다.

2. Git flow native
   모든 작업은 feature 브랜치이며, git flow feature finish 로 정상적으로 종료됩니다. 고아 브랜치나 머지 혼란이 없습니다.

3. 엄격한 역할 경계
   Orchestrator는 절대 코드를 작성할 수 없습니다 – 프롬프트로 강제합니다:

   ## CRITICAL: Your Role Boundaries
   
   **You COORDINATE. You do NOT EXECUTE.**
   
   ### You do NOT:
   - Write code or fix bugs (workers do this)
   - Work directly in sub‑repos (workers do this)
   - Create feature branches for tasks (workers do this)

4. Worktree isolation
   각 워커는 별도의 git worktree에서 실행됩니다. 브랜치 전환, stash 관리, 충돌이 없습니다. 워커는 진정으로 병렬 실행이 가능합니다.

흐름

┌─────────────────┐     ┌─────────────────┐
│   ORCHESTRATOR  │     │     WORKER      │
│   (main repo)   │     │   (worktree)    │
├─────────────────┤     ├─────────────────┤
│ • Track status  │────▶│ • feature/task  │
│ • Assign tasks  │     │ • Write code    │
│ • Update Notion │◀────│ • Report done   │
│ • Never code    │     │ • Cleanup       │
└─────────────────┘     └─────────────────┘

사용해 보기

모든 내용은 내 Claude Copilot 포크에 있습니다:

🔗

핵심 파일

• templates/Makefile.orchestrator – 오케스트레이션 명령
• .claude/commands/orchestrator.md – 오케스트레이터 동작
• .claude/commands/worker.md – 워커 동작
• docs/ORCHESTRATOR-WORKER-FLOWCHART.md – 전체 시스템 다이어그램

앞으로의 계획

• 워커 간 진행 상황 보고 개선
• 워크트리 간 자동 충돌 감지
• Notion 연동 강화

비슷한 멀티‑세션 코디네이션 문제를 해결하고 계신 분들의 피드백을 기다립니다. 여러분은 어떤 접근 방식을 사용하고 계신가요?

Built on top of Claude Copilot by Everyone Needs a Copilot