Claude Code 병렬 에이전트로 Unity 프로젝트 전체 분석하기

배경

Unity WebGL 포커 게임 프로젝트(홀덤 게임, Assets 전체)의 분석과 문서화를 Claude Code에게 맡겼다.

방법

• Assets 아래를 6개 모듈로 나누고, 모듈마다 전문 에이전트를 하나씩 붙여 병렬로 분석시켰다.
  • 핵심 게임 로직
  • 유틸리티·UGUI
  • 임베디드 서버·디버그
  • 리소스·데이터·설정
  • 플러그인·에디터·셰이더
  • 에디터 도구
• 분석 도구는 Glob, Grep, Read만 썼다. 실행 없이 정적 코드 분석만 했다.
• 각 에이전트가 모듈별 중간 분석 문서를 .analysis/ 폴더에 남기고, 마지막에 문서 작성용 에이전트(doc-writer)가 이를 통합했다.

생성된 문서는 다음과 같다.

문서	내용	대상 독자
ARCHITECTURE.md	전체 시스템 아키텍처, 계층별 설명, 주요 컴포넌트, Mermaid 다이어그램, 디자인 패턴, 보안·성능 고려사항, 개선 권장사항	기술 리드, 시니어 개발자
README.md	프로젝트 개요, 주요 기능, 시작 가이드, 플랫폼별 빌드 방법, 개발 가이드	모든 개발자, 신규 팀원
.analysis/*.md	모듈별 상세 분석 6개	해당 모듈 담당 개발자

여기에 요약 보고서와 상세 보고서가 함께 나왔다.

분석 결과

프로젝트 개요

• Unity 2021.3+ LTS, C# 9.0, URP 12.x
• 타겟: WebGL(주), Android, iOS, Standalone
• 통신: Apache Thrift 0.13.0(RPC), Newtonsoft.Json 13.0
• 데이터: ScriptableObject
• 규모: 스크립트 200개 이상, 약 80,000줄, Thrift 메시지 90종 이상

아키텍처

5계층 구조로 정리되었다.

Presentation   - 메인 UI, UGUI 확장 컴포넌트
      ↓
Business Logic - 게임 상태 기계, AI 봇 시스템, 몬테 카를로 시뮬레이션
      ↓
Domain Model   - Player, Hand, Deck, Table
      ↓
Data           - Thrift 프로토콜, CardEvaluator
      ↓
Utility        - 사운드 풀링, 해상도 대응, 디버그 시스템

게임 흐름은 11단계 상태 기계로 관리된다.

Idle → BettingTime → Shuffle → Betting → Deal → Flop → Turn → River → ShowDown → Result → Settlement

에이전트가 짚어 낸 디자인 패턴은 State Machine, Singleton, Observer, Factory, Memento(오브젝트 활성 상태 저장·복원), Object Pool(사운드 오브젝트), Strategy(AI 봇 베팅 전략), Command(게임 액션 캡슐화)다.

강점으로 꼽힌 부분

• 서버 로직과 클라이언트 로직이 분리된 계층 구조
• Thrift 기반의 타입 안전한 메시지 통신
• 데이터 주도 설계: CSV를 ScriptableObject로 자동 변환해, 서로 다른 베팅 전략을 가진 AI 봇들을 코드 수정 없이 조정할 수 있다.
• 임베디드 서버 모드: WebGL 빌드에서 클라이언트 안에 게임 서버를 내장해 별도 서버 없이 오프라인·데모 모드로 돌릴 수 있다.
• 사운드 풀링, 조건부 컴파일, 4:3~22:9 다중 화면 비율 대응
• 덱 조작 치트 도구, 실시간 게임 상태 디버그 패널

개선 과제

우선순위	과제	내용
높음	대형 클래스 분리	메인 게임 클래스(약 1,900줄)를 상태·메시지·UI·애니메이션 컨트롤러로, 공용 유틸 클래스(약 27,000줄)를 문자열·금액 포맷·날짜·검증·네트워크·디버그 모듈로 분해
높음	단위 테스트 추가	클라이언트 코드에 테스트가 없다. 상태 전환, 베팅 로직, 카드 평가, AI 봇 로직을 Unity Test Framework로 테스트하고 CI에 통합
높음	치트 모드 보호	치트 도구가 조건부 컴파일로만 보호되고 런타임 검증이 없다. 릴리즈 빌드에서 완전히 제거하고 런타임 권한 검증 추가
중간	사운드 오브젝트 Update 루프	매 프레임 사운드 상태를 체크한다. 코루틴 주기 체크나 이벤트 기반으로 전환
중간	Resources 의존	Resources.LoadAll() 사용. Addressable Asset System과 비동기 로딩으로 전환
중간	몬테 카를로 시뮬레이션	10,000회 시뮬레이션이 메인 스레드를 막아 승률 계산 시 UI가 멈춘다. Unity Job System으로 병렬화
낮음	매직 넘버, WAV 압축	상수 분리, MP3·OGG 변환

치트 도구 보호에 대해 제시된 형태는 다음과 같다.

#if !UNITY_EDITOR && !DEVELOPMENT_BUILD
// 릴리즈 빌드에서 치트 기능 완전 제거
#else
// 개발/에디터 모드에서만 활성화
#endif

배운 점

• 모듈별로 에이전트를 나눠 병렬로 돌리고 마지막에 통합해, 약 80,000줄 규모의 프로젝트에서 한 번의 작업으로 구조 문서와 개선 과제 목록을 얻었다.
• 결과물은 정적 분석 기반이다. 보고서에는 작업량, 개선 효과(메모리·성능 향상 비율 등), 프로젝트 진행률, 별점 같은 수치가 함께 나왔지만, 실행이나 측정 없이 나온 추정치이므로 그대로 믿지 않고 사람이 확인해야 한다.