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 ```bash # 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 분석 ```bash # 도메인 추출 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: 협업 디렉토리 초기화 ```bash 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 리드 스폰 (병렬) ```bash # 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는 블로킹 없이 아래를 반복 확인: ```bash # 1. 사이드바 상태 확인 cmux sidebar-state # 2. 리포트 파일 확인 (리드들이 완료 시 기록) ls .claude/collab/reports/ # 3. team-lead 수신함 확인 (에이전트가 알림 전달 시) ls .claude/collab/inbox/ ``` 긴급 이슈 → 리드가 `cmux notify`로 즉시 알림. ### Step 6: 크로스 도메인 조율 리드 간 충돌/의존성 발생 시: ```bash # team-lead가 해당 리드 워크스페이스에 지시 전달 cmux send --workspace $ARCH_WS \ "API 스펙 변경 사항을 .claude/collab/requests/REQ-001.md 에 기록하고 design-lead에 공유 " ``` 결정 사항 → `.claude/collab/decisions/DEC-NNN.md` 에 기록. ### Step 7: 동적 팀 확장/축소 ```bash # 작업량 증가 → 워커 추가 스폰 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: 종료 ```bash # 각 리드에 종료 신호 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) ```bash # 시작 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) ```bash # 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 워커 스폰 (리드가 직접) ```bash # 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 모델 배정 커스터마이징 가이드 |