GhostMarch_2 — 프로젝트 스캐폴딩 스냅샷

1. 주요 변경사항

• Assets/_Project/Scripts/ 하위에 10 개 모듈(Core, Data, Combat, Enemy, Network, Pickup, Player, Resonance, UI, Wave) 의 Assembly Definition 파일을 신규 추가하여 모듈 경계를 선언했다.
• 루트 CLAUDE.md 를 작성하여 문서 맵·아키텍처 요약·네트워크 원칙·금지 규칙·세션 시작 체크리스트를 한 곳으로 집약했다.
• Packages/manifest.json 의 NGO·Services 버전을 상향(NGO 2.3.3 → 2.11.0 등)하고, com.unity.transport / com.unity.services.core 를 전이 의존성 의존으로 전환해 명시 의존성을 제거했다.
• SaintsField·JSAM 패키지의 git 식별자를 owner/fork 변경에 맞춰 교체했다(com.tylertempdev.saintsfield → today.comes.saintsfield, com.jackyyang09.jsam → com.brogrammist.jsam).
• documents/dev/claude-code-setup.md 추가 및 dev-structure.md 의 패키지 버전 기술 동기화.

2. 코드 품질 리뷰

현재 커밋 범위에는 실제 .cs 코드가 전혀 포함되지 않았고, 변경은 전적으로 프로젝트 기반 구조(asmdef, 매니페스트, 문서) 설정이다. 따라서 “가독성·단일 책임·중복” 같은 코드 축보다는 경계 설계의 적절성 으로 평가한다. 결론부터 말하면, 계층을 선언해두고 코드를 그 위에 얹는 접근은 교육용 프로젝트에선 드문 수준의 좋은 출발이다. Data → Core → (Feature 모듈) → UI 순의 그래프가 CLAUDE.md 의 다이어그램과 거의 일치하고, autoReferenced: false 를 전 모듈에 일괄 적용한 것도 의도된 격리를 위해 옳은 선택이다.

다만 몇 가지 우려가 있다. 첫째, GhostMarch2.UI.asmdef 가 Player/Combat/Enemy/Wave/Pickup/Resonance/Network 를 모두 직접 참조한다. 이는 CLAUDE.md 에 명시된 “게임로직 → UI 직접 호출 금지 — EventBus 로 알림” 원칙과 정면으로 충돌할 수 있는 구조다. UI 가 그 모든 모듈의 타입을 직접 읽는 순간, 사실상 UI 가 최상위에서 모든 도메인 타입을 끌어안는 상위 계층이 되고, EventBus 경유 원칙이 형식화된다. UI 가 참조해야 할 것은 원칙적으로 Core(EventBus·이벤트 페이로드 타입)와 Data(뷰모델 SO) 뿐이어야 한다. 왜 문제인가: 개별 피처 모듈을 바꿀 때마다 UI 까지 재컴파일되고, UI 테스트가 네트워크·도메인 전체와 얽히며, 리팩터 비용이 기하급수로 커진다. 개선 제안: UI 는 Core 만 참조하고, 각 피처 모듈은 Core 의 이벤트 타입을 발행(publish)만 하도록 방향을 뒤집는다.

둘째, 모든 asmdef 가 실제 구현체 0 개 상태로 선언만 존재한다. 이 자체가 나쁜 것은 아니지만, 이 상태는 “경계 설계가 맞는지” 를 컴파일러가 검증해주지 못한다. 최소한 각 모듈에 placeholder 인터페이스/어셈블리 마커 클래스 하나씩을 넣어두면, 다른 모듈이 잘못 참조할 때 즉시 컴파일 오류로 드러난다.

셋째, 매니페스트에서 com.unity.transport 와 com.unity.services.core 를 제거했는데, NGO 2.11.0 이 내부 전이 의존성으로 이 둘을 끌어오는 것은 맞지만 버전 고정(lock) 이 풀린다는 뜻이기도 하다. Transport 같이 저수준 의존성은 메이저 업데이트에서 동작이 바뀌는 사례가 있어, 필요하면 packages-lock.json 을 커밋에 포함하거나 버전을 명시 고정하는 편이 재현성에 유리하다.

3. 진행도 평가

첫 리포트 기준 진행도는 초기 스캐폴딩 단계로 판단한다. 커밋 4 개 중 실제 구현 커밋은 0 개이며, 나머지는 구조 선언(asmdef)·패키지 정리·문서화로 분류된다. 이는 부정적인 신호가 아니다. 뱀서라이크 + 2 인 온라인 코옵이라는 난이도 높은 스코프에서, 모듈 경계와 네트워크 권한 원칙을 먼저 문서와 asmdef 로 박아 두는 것은 오히려 교과서적인 출발이다. 커밋 메시지도 feat/docs/fix prefix 를 일관되게 지키고 있고 단일 책임이 잘 분리돼 있다.

우려는 오히려 속도와 증명 쪽이다. 다음 리포트 구간까지 플레이어 이동 + 적 스폰 + 간단한 EventBus 호출이 실제로 컴파일·동작하는 것을 보여주지 못하면, 선언된 계층이 실전에서 흔들릴 때 유지될지 확인이 불가능하다. 남은 기간을 고려하면 “지금은 설계 부채가 작다” 보다 “아직 부채를 만들 코드가 없다” 에 가까우므로, 다음 구간에는 최소 동작 슬라이스(verticle slice)를 한 번 관통시키는 것을 권장한다.

4. 다음 권장사항

• Core/Data 에 최소 구현체 배치: EventBus 인터페이스, 공통 이벤트 페이로드 SO 1-2 개를 실제 코드로 넣어 asmdef 경계가 컴파일러로 검증되게 한다. 왜: 선언만 있는 경계는 첫 피처에서 거의 항상 무너진다.
• UI.asmdef 의존성 재검토: UI → Feature 모듈 참조를 끊고 Core 만 참조하도록 조정. 왜: CLAUDE.md 의 EventBus 원칙과 현재 UI asmdef 설계가 충돌한다.
• 플레이어 이동 + Input System 프로토타입: Player 모듈 안에서 Rigidbody2D 기반 이동을 Input System 으로 구현하여 “동작하는 첫 씬” 을 만든다. 왜: 조작감 감각 없이 밸런스 문서를 쓰면 수치가 전부 재작업된다.
• 네트워크 권한 모델을 문서로 고정: documents/dev/architecture.md 에 “무엇을 Host 가 결정하고 무엇을 Client 가 Predict 하는가” 표를 명시. 왜: NGO 는 규칙이 흔들리기 시작하면 디버깅이 기하급수로 비싸진다.
• spec 계열 문서 초안: _sample/docs 수준까지 가지 않아도 좋으니, 무기/적/웨이브 ID 체계 + 수치 필드 스키마만 먼저 정의한다. 왜: 콘텐츠가 코드로 내려가기 전에 테이블 형태로 잡아두어야 SO 스캐폴드가 재작업 없이 간다.

5. 문서화 상태

design (5/10): CLAUDE.md 는 문서 맵으로서 훌륭하고 아키텍처 다이어그램·네트워크 원칙·금지 규칙이 분명하다. 그러나 링크된 concept.md·game-design.md·content-list.md 등은 이번 커밋에 포함되지 않아 실제 내용 확인이 불가능하다. “귀행 1 이식” 이라는 전제 외에, 뱀서라이크 코어 루프에서 “왜 이 설계 선택이 필요한가” 의 의사결정 기록이 부족하다.

technical (6/10): asmdef 그래프·네트워크 원칙·빌드 환경 설정이 문서화되어 있고, dev-structure.md 가 패키지 버전을 실제와 동기화한 점은 좋다. 다만 architecture.md·tdd.md·rules.md 등 핵심 기술 문서가 이번 스냅샷에 실파일로 존재하지 않아 “문서 목차만 먼저 잡힌” 단계로 평가된다. 신규 유입이 코드 구조를 이해하려면 asmdef 의존성 그래프 문서가 실제로 있어야 한다.

spec (2/10): _sample/docs 의 레시피·레벨 사양서 수준의 콘텐츠 스펙 문서가 전무하다. 무기·몬스터·웨이브 수치 테이블, 씬 구성, 입력/상태/결과 매핑이 없으면 이후 SO 스캐폴드와 레벨 데이터가 모두 임기응변이 된다. 이 축이 가장 시급하다.

6. Backlog

• asmdef 만 존재하고 각 모듈 내부에 .cs 파일이 0 개 — 경계가 실제 코드로 검증되지 않음.
• UI.asmdef 가 거의 모든 게임 모듈(Player/Combat/Enemy/Wave/Pickup/Resonance/Network)을 참조 — EventBus 경유 원칙과 충돌, UI 가 상위 계층이 되는 구조적 위험.
• spec(콘텐츠 사양서) 계열 문서 부재 — 무기/적/웨이브 수치가 SO 로 진입할 근거 테이블이 없다.
• Packages/manifest.json 에서 com.unity.transport / com.unity.services.core 제거 — NGO 2.11.0 의 전이 의존성이 실제 빌드에서 문제없이 해결되는지 검증·기록 필요.
• SaintsField·JSAM 의 git URL owner/name 변경 사유(원본 fork 이전 등)가 문서에 남아있지 않음 — 추후 의존성 추적 어려움.
• CLAUDE.md 문서 목차가 참조하는 다수 문서(architecture.md, tdd.md, todo.md, rules.md, dev-plan.md, naming.md, asmdef-structure.md 등) 중 일부가 이번 커밋에 포함되지 않아 링크가 깨져 있을 가능성.