cmux-orchestrate

/cmux-orchestrate — cmux 기반 멀티-AI 팀 오케스트레이션

team-orchestrate와의 차이: Agent Teams API(flat) 대신 cmux 워크스페이스(물리 계층)를 사용. L1 리드가 자신의 L2 워커를 직접 스폰 → 진짜 3-Level 독립 프로세스.

---

아키텍처

현재 Claude 세션 (Level 0: team-lead)
  │  모니터링: cmux sidebar + .claude/collab/reports/
  │
  ├─ cmux workspace "arch-lead" (Level 1)
  │     process: claude or codex
  │     스폰: backend-builder 워크스페이스를 직접 생성
  │       └─ cmux workspace "backend-builder" (Level 2)
  │
  ├─ cmux workspace "design-lead" (Level 1)
  │     process: gemini or claude
  │     스폰: frontend-builder 워크스페이스를 직접 생성
  │       └─ cmux workspace "frontend-builder" (Level 2)
  │
  └─ cmux workspace "qa-lead" (Level 1)
        process: claude

핵심 원칙: 각 에이전트는 독립 프로세스 → 컨텍스트 격리 + 진짜 병렬

---

Prerequisites

# 1. cmux 사용 가능
cmux ping || { echo "cmux 필요"; exit 1; }

# 2. TASKS.md 존재
[ -f TASKS.md ] || { echo "/tasks-init로 먼저 생성"; exit 1; }

# 3. 소켓 접근 모드 확인 (에이전트가 사이드바를 쓰려면 allowAll 필요)
export CMUX_SOCKET_MODE=allowAll   # 또는 cmux 내부에서 실행 중이면 자동

---

기본 AI 라우팅

역할	기본 AI	이유
team-lead	claude	전략, 조율, 판단
arch-lead	claude	아키텍처 결정, 코드 리뷰
backend-builder	codex	코드 생성 최적화
design-lead	gemini	창의성, 비주얼 판단
frontend-builder	gemini	UI/UX 구현
qa-lead	claude	분석적 검증
reviewer	claude	코드 리뷰, 품질 판단

커스터마이징: references/ai-routing.md 참조

---

실행 순서

Step 1: TASKS.md 분석

# 도메인 추출
grep "domain:" TASKS.md | sort -u
# 예시 출력: backend, frontend, qa

분석 결과로 팀 토폴로지 결정:

• backend 도메인 → arch-lead + backend-builder
• frontend 도메인 → design-lead + frontend-builder
• qa 태그 → qa-lead
• 도메인 없음 → arch-lead만

Step 2: 협업 디렉토리 초기화

mkdir -p .claude/collab/{reports,requests,decisions,contexts,inbox}
# inbox: team-lead 수신함
# contexts: 각 에이전트용 브리핑 파일 (team-lead가 작성)

Step 3: 에이전트 컨텍스트 파일 작성

각 L1 리드용 브리핑 파일을 .claude/collab/contexts/ 에 작성. 내용: 역할, 담당 도메인 태스크 목록, 통신 규약, 워커 스폰 방법.

상세 프롬프트 템플릿: references/agent-prompts.md

Step 4: L1 리드 스폰 (병렬)

# arch-lead (claude)
ARCH_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $ARCH_WS "cd $(pwd)
"
cmux send --workspace $ARCH_WS \
  "claude --dangerously-skip-permissions -p \"\$(cat .claude/collab/contexts/arch-lead.md)\"
"
cmux set-status "arch-lead" "starting" --icon hammer --color "#ff9500"

# design-lead (gemini)
DESIGN_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $DESIGN_WS "cd $(pwd)
"
cmux send --workspace $DESIGN_WS \
  "gemini --yolo \"\$(cat .claude/collab/contexts/design-lead.md)\"
"
cmux set-status "design-lead" "starting" --icon brush --color "#5856d6"

# qa-lead (claude) — L1 리드들 스폰 후에 시작
QA_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $QA_WS "cd $(pwd)
"
cmux send --workspace $QA_WS \
  "claude --dangerously-skip-permissions -p \"\$(cat .claude/collab/contexts/qa-lead.md)\"
"
cmux set-status "qa-lead" "waiting" --icon checklist --color "#8e8e93"

Step 5: 모니터링 루프

team-lead는 블로킹 없이 아래를 반복 확인:

# 1. 사이드바 상태 확인
cmux sidebar-state

# 2. 리포트 파일 확인 (리드들이 완료 시 기록)
ls .claude/collab/reports/

# 3. team-lead 수신함 확인 (에이전트가 알림 전달 시)
ls .claude/collab/inbox/

긴급 이슈 → 리드가 cmux notify로 즉시 알림.

Step 6: 크로스 도메인 조율

리드 간 충돌/의존성 발생 시:

# team-lead가 해당 리드 워크스페이스에 지시 전달
cmux send --workspace $ARCH_WS \
  "API 스펙 변경 사항을 .claude/collab/requests/REQ-001.md 에 기록하고 design-lead에 공유
"

결정 사항 → .claude/collab/decisions/DEC-NNN.md 에 기록.

Step 7: 동적 팀 확장/축소

# 작업량 증가 → 워커 추가 스폰
EXTRA_WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $ARCH_WS \
  "WS=\$(cmux new-workspace 2>&1 | awk '{print \$2}') && cmux send --workspace \$WS \"cd $(pwd) && codex exec '\$(cat .claude/collab/contexts/backend-builder-2.md)'\"
"

# 완료된 워커 종료
cmux send --workspace $DONE_WS "exit
"
cmux close-workspace --workspace $DONE_WS
cmux clear-status "backend-builder"

Step 8: 종료

# 각 리드에 종료 신호
for WS in $ARCH_WS $DESIGN_WS $QA_WS; do
  cmux send --workspace $WS "exit
"
done

# 워크스페이스 정리
cmux close-workspace --workspace $ARCH_WS
cmux close-workspace --workspace $DESIGN_WS
cmux close-workspace --workspace $QA_WS

# 사이드바 클리어
cmux clear-status
cmux log --level success -- "Team disbanded. All tasks complete."

---

에이전트 내부 규약 (L1 리드 컨텍스트에 포함)

사이드바 상태 보고 (리드 → team-lead)

# 시작
cmux set-status "{role}" "active" --icon hammer --color "#ff9500"
cmux set-progress 0.0 --label "{role}: starting"

# 진행 중
cmux set-progress 0.4 --label "{role}: T1.2 in progress"

# Phase 완료
cmux set-status "{role}" "phase-1 done" --icon checkmark --color "#34c759"
cmux log --level success -- "{role}: Phase 1 complete (3/3 tasks)"

# 블로킹 이슈
cmux set-status "{role}" "BLOCKED" --icon warning --color "#ff3b30"
cmux notify --title "{role} BLOCKED" --body "크로스 도메인 의존성 발생. team-lead 확인 필요"

파일 기반 리포트 (리드 → team-lead)

# Phase 완료 시 리포트 작성
cat > .claude/collab/reports/$(date +%Y%m%d)-{role}-phase-N.md << 'EOF'
## {role} Phase N Report
- Completed: T1.1, T1.2, T1.3
- Decisions: ADR-001 작성
- Issues: 없음
- Next: Phase 2 대기
EOF

L1 → L2 워커 스폰 (리드가 직접)

# arch-lead가 backend-builder 스폰
WORKER_CTX=".claude/collab/contexts/backend-builder.md"
cat > $WORKER_CTX << 'EOF'
[워커 컨텍스트 - 담당 태스크, 테스트 명령, 보고 방법]
EOF

WS=$(cmux new-workspace 2>&1 | awk '{print $2}')
cmux send --workspace $WS "cd $(pwd) && codex exec \"\$(cat $WORKER_CTX)\"
"
cmux set-status "backend-builder" "spawned" --icon gear --color "#007aff"

워커 프롬프트 템플릿: references/agent-prompts.md

---

team-orchestrate와 비교

	team-orchestrate	cmux-orchestrate
에이전트 실행	Agent Teams API (in-process)	독립 프로세스 (cmux workspace)
계층 구조	논리적 (SendMessage 프로토콜)	물리적 (프로세스 계층)
지원 AI	Claude만	Claude + Gemini + Codex
컨텍스트	공유 (같은 프로세스)	격리 (독립 세션)
상태 모니터링	TaskList 폴링	cmux sidebar 실시간
장애 격리	한 에이전트 문제 → 전체 영향	독립 프로세스 → 격리됨
요구사항	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS	cmux (CMUX_SOCKET_MODE=allowAll)

---

Fallback

상황	동작
cmux 없음	/team-orchestrate (Agent Teams API 기반) 사용 권장
codex CLI 없음	Claude 워크스페이스가 대체
gemini CLI 없음	Claude 워크스페이스가 대체
워크스페이스 생성 실패	로그 기록 후 해당 역할 건너뜀
Agent 타임아웃 (5분)	Claude가 직접 해당 역할 수행

---

참고 파일

파일	내용
references/agent-prompts.md	각 역할별 컨텍스트 파일 템플릿
references/ai-routing.md	AI 모델 배정 커스터마이징 가이드