cmux로 Unity 블록 게임 팀 만들기
Block Blast 스타일의 심플한 그리드 퍼즐을 Unity로 만들 때, Claude Code 하나로는 분해되지 않는 작업들이 생깁니다. cmux의 멀티 세션 · worktree 격리를 활용해 7개의 전문 에이전트로 팀을 짜고, 오케스트레이터가 스펙 → 병렬 스프린트 → 통합 → QA 루프를 순환시키는 운영 전략을 정리합니다.
Unity 프로젝트는 병렬화를 강하게 보상하면서, 동시에 처벌도 합니다.
C# 스크립트는 worktree로 깔끔히 나뉘지만, Scene·Prefab·.meta는 머지가 깨지기 쉽습니다. 팀 구성보다 "무엇을 누구의 worktree에서 다루는가"를 먼저 정의해야 합니다.
1. 게임 스펙을 먼저 못 박는다
모든 워커가 같은 페이지에서 시작하려면 스펙이 코드보다 먼저 main에 들어가 있어야 합니다. Game Designer 에이전트가 단독으로docs/spec.md를 작성하고, 오케스트레이터가 머지한 시점부터 다른 에이전트의 작업이 시작됩니다.
핵심 규칙 (예시)
- 8×8 그리드, 3슬롯에 랜덤 도형 제공
- 슬롯이 비면 새 3개 생성, 배치 불가 시 게임오버
- 가로/세로 라인이 가득 차면 동시 소거
- 동시 다중 클리어는 콤보 배수 적용
비기능 요건
- 타겟: WebGL + Android, 60fps
- 입력: 드래그 1종으로 통일 (탭 배치 없음)
- 저장: PlayerPrefs 최고 점수 1개
- 로컬라이즈: 한국어/영어 (TextMeshPro)
왜 스펙이 먼저인가: 병렬 에이전트들은 서로의 출력을 보지 못합니다. 스펙이 흔들리면 머지 시점에 인터페이스 불일치가 폭발합니다. 스펙은 짧고 단정적이어야 하며, 의문점은 워커 시작 전에 오케스트레이터가 모두 해소해야 합니다.
2. 7개 역할의 cmux 에이전트 팀
cmux는 각 에이전트를 독립 worktree에서 실행시켜 파일 충돌 없이 동시 작업하도록 돕습니다. 역할은 7개로 정착했습니다 — 더 늘리면 오케스트레이터의 컨텍스트가 먼저 무너지고, 줄이면 한 워커가 Scene과 C# 양쪽을 만지며 머지 충돌을 일으킵니다.
| 역할 | Worktree | 주요 산출물 |
|---|---|---|
| Orchestrator | main | 메인 브랜치 / 통합 담당 |
| Game Designer | design/spec | 디자인 문서 전용 |
| Core Gameplay | feat/gameplay-core | Assets/Scripts/Gameplay |
| UI/Input | feat/ui-input | Assets/Scenes/Main, Assets/UI |
| Juice (VFX/SFX) | feat/juice | Assets/Art, Assets/Audio |
| QA / Evaluator | qa/playmode | Tests/, PlayMode 시나리오 |
| Build / CI | infra/ci | .github/workflows, ProjectSettings |
Orchestrator
- 스펙을 작업 단위로 분해하고 워커에게 위임
- 각 워커의 PR(또는 worktree diff)을 main에 머지
- 전체 진행 상황과 토큰 비용을 추적
Game Designer
- Block Blast 류 규칙 정의 (8x8 그리드, 3개 슬롯, 라인/컬럼 클리어)
- 스코어링·콤보·게임오버 조건 명세
- 난이도 곡선과 도형 풀(pool) 정의
Core Gameplay
- Grid·BlockShape·Placement·LineClear 로직 (POCO C#)
- Unity Test Framework EditMode 단위 테스트
- MonoBehaviour 의존성 최소화로 테스트 가능성 확보
UI/Input
- 드래그 앤 드롭, 그리드 하이라이트, HUD/스코어 표시
- uGUI 또는 UI Toolkit 중 단일 선택 후 일관 적용
- EventSystem과 Input System 설정
Juice (VFX/SFX)
- 라인 클리어 파티클·셰이크·트윈
- AudioMixer와 SFX 트리거 훅
- 프로파일링으로 모바일 타겟 60fps 유지
QA / Evaluator
- PlayMode 시나리오 테스트 (배치-클리어-스코어 경로)
- 각 워커의 머지 후 회귀 테스트 실행
- 스펙 대비 합격/불합격 보고서 생성
Build / CI
- Unity CLI 헤드리스 빌드(WebGL/Android) 자동화
- GameCI 액션, 캐시, 라이선스 활성화
- 빌드 산출물 아티팩트 업로드
3. Unity를 위한 Worktree 전략
cmux의 격리는 Git worktree 위에서 동작합니다. 일반 웹앱과 달리 Unity에는 텍스트 머지가 위험한 자산이 많아, 영역을 미리 나누어 두지 않으면 병렬 작업의 효익이 머지 비용으로 사라집니다.
C# 스크립트
네임스페이스와 폴더로 사전 분할. Core Gameplay는Game.Core, UI는Game.UI로 잠그고, asmdef로 의존 방향을 강제합니다.
Scene · Prefab
Scene은 단 하나의 워커(UI/Input)만 편집. 다른 워커는 Prefab 분리 + 코드에서 인스턴스화. ProjectSettings에서 Asset Serialization: Force Text와 SmartMerge를 활성화합니다.
.meta 파일
.meta는 항상 커밋. GUID 충돌을 피하려면 새 에셋 생성은 단일 워커에 위임하거나, 오케스트레이터가 통합 시 GUID 안정성을 검증합니다.
Library / Temp
gitignore 유지. 단, 각 worktree마다 Unity가 Library를 새로 굽기 때문에 첫 실행이 느립니다 — 워커 부팅 시 캐시 서버나 공유 Library 심볼릭 링크를 고려하세요.
4. 오케스트레이션 흐름
오케스트레이터는 직접 코드를 쓰지 않습니다. cmux 세션 사이를 오가며 상태를 수집하고, 위임·머지·차단 해제만 수행합니다. 1회 사이클은 보통 하루 분량으로 끊습니다.
Kickoff — 스펙과 인터페이스 합의
Game Designer가 spec.md를, 오케스트레이터가 Game.Core 공개 인터페이스(IGrid, IShapeProvider, IScoreService)의 스텁을 main에 먼저 머지합니다. 모든 워커는 이 스텁에 대해 코딩합니다.
Fan-out — 병렬 스프린트
Core Gameplay · UI/Input · Juice · Build/CI를 동시에 시작. cmux 세션 4개가 각 worktree에서 독립적으로 돌고, 오케스트레이터는 요약 메시지를 받기만 합니다.
Fan-in — 순서 있는 통합
머지 순서는 Core → UI → Juice → CI로 고정. Core가 먼저 들어가야 나머지의 컴파일이 보장됩니다. 충돌은 오케스트레이터가 단독 해결하거나, 해당 영역의 워커에게 재할당합니다.
Evaluate — QA 루프
QA 에이전트가 PlayMode 시나리오를 돌리고 합/불 보고서를 작성. 불합격 항목은 구체 피드백과 함께 원래 워커의 worktree로 되돌려져, 다음 사이클의 첫 작업이 됩니다.
5. Generator-Evaluator 루프를 PlayMode 테스트로
웹 프로젝트가 Playwright로 평가하듯, Unity는 Unity Test Framework의 PlayMode 테스트를 평가 채널로 씁니다. 시각/미학은 사람이 판단하더라도, "배치 → 클리어 → 점수 증가" 같은 핵심 인터랙션은 코드로 채점 가능합니다.
기능성 테스트
도형을 그리드에 배치하면 셀이 점유되는가? 라인이 차면 사라지는가? 게임오버 조건이 정확히 트리거되는가? 모두 PlayMode 시나리오로 스크립트화합니다.
성능 테스트
ProfilerMarker로 프레임당 GC alloc과 라인 클리어 처리 시간을 측정. 임계값을 넘기면 자동 실패시켜 Generator에게 피드백합니다.
UX 점검
드래그 시 그리드 하이라이트, 잘못된 배치 시 스냅백, 클리어 시 피드백. 이 항목은 사람 리뷰가 최종 판단이지만, QA 에이전트가 스크린샷 시퀀스를 모아 1차 검토합니다.
스펙 정합성
QA가 spec.md의 각 조항을 PlayMode 어서션으로 1:1 매핑. 신규 규칙은 spec.md 머지 시 동시에 테스트도 추가되어야 통과 처리됩니다.
6. 실행 체크리스트
프로젝트 셋업
- Asset Serialization: Force Text + SmartMerge 등록
- asmdef로 Game.Core / Game.UI / Game.Audio 분리
- CLAUDE.md에 폴더 소유권과 머지 순서 명시
- .gitignore에 Library, Temp, Logs, UserSettings
cmux 운영
- 역할마다 별도 worktree + 별도 cmux 세션
- 오케스트레이터 세션은 코드를 직접 쓰지 않음
- 각 워커에게 spec.md와 인터페이스 스텁만 컨텍스트로 제공
- 토큰/비용을 세션별로 추적해 폭주 시 조기 차단
머지 게이트
- EditMode + PlayMode 테스트 통과
- WebGL 헤드리스 빌드 통과
- Scene/Prefab을 만진 PR은 단일 워커만 허용
- QA 평가 보고서가 함께 첨부
7. 자주 빠지는 함정
병렬화에 욕심을 부린다
Block Blast 규모에서 워커 7개도 많을 수 있습니다. 첫 사이클은 Core + UI + QA 3개로 시작하고, 통합이 매끄러워지면 Juice·Build를 추가하세요. 동시성은 머지 비용을 지불해야 얻는 자원입니다.
Scene을 둘 이상의 워커가 만진다
Force Text + SmartMerge를 깔아도, 큰 Scene 충돌은 사람이 못 풉니다. Scene 편집 권한은 단 하나의 워커(보통 UI/Input)에 고정하고, 나머지는 Prefab과 코드 인스턴스화로 우회합니다.
오케스트레이터가 코딩을 시작한다
컨텍스트가 가장 빨리 무너지는 시나리오. 오케스트레이터는 위임·머지·중재만 수행하고, 코딩 욕구가 생기면 새 worker 세션을 띄우세요.
QA를 마지막에만 부른다
Generator-Evaluator의 효과는 사이클 중간에서 나옵니다. 매 머지 직후 QA를 돌려야, 다음 사이클의 워커가 정확한 피드백으로 시작할 수 있습니다.