바른생활해보자

[AI] MCP(Model Context Protocol) - AI의 USB

HONGGG — Tue, 7 Apr 2026 14:13:10 +0900

AI가 똑똑해지는 것만으로는 부족하다.
외부 세계와 연결되어야 진짜 일을 할 수 있다.
MCP는 그 연결의 표준이다.

MCP란 무엇인가

MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 공개한 오픈 표준 프로토콜이다.

AI 모델이 외부 도구, 데이터베이스, API, 파일 시스템 등과 소통하는 방식을 하나로 통일한다.

USB-C가 등장하기 전, 안드로이드는 마이크로 USB, 아이폰은 라이트닝, 카메라는 미니 USB를 썼다. 기기마다 케이블이 달랐고 USB-C는 이 혼란을 하나의 규격으로 정리했다.

MCP는 AI 세계에서 같은 일을 한다.

이전에는 Claude에 Google Drive를 연결하려면 전용 커넥터를 만들고, GPT에 같은 Google Drive를 연결하려면 또 다른 커넥터를 만들어야 했다.

AI 모델 N개와 도구 M개가 있으면 N×M개의 커넥터가 필요했다.

MCP는 이것을 N+M으로 줄인다. 도구 쪽에서 MCP 서버 하나만 만들면, MCP를 지원하는 모든 AI 클라이언트가 그 도구를 사용할 수 있다.

왜 MCP가 중요한가

AI 똑똑하지만 손이 없다

LLM은 강력하지만 태생적 한계가 있다. 학습 데이터 이후의 정보를 모르고, 외부 시스템에 접근할 수 없으며, 실제 작업(파일 생성, 이메일 발송, 데이터베이스 쿼리 등)을 수행할 수 없다.

이전까지는 이 문제를 해결하기 위해 각 도구마다 맞춤형 API 연동 코드를 작성했다.

MCP 이전 vs 이후

항목	MCP 이전	MCP 이후
통합 방식	도구마다 맞춤 커넥터 개발	표준 프로토콜로 한 번만 개발
유지보수	AI 모델 변경 시 커넥터 전체 수정	MCP 서버는 모델과 무관하게 동작
호환성	특정 AI 플랫폼에 종속	모든 MCP 호환 클라이언트에서 사용
개발 비용	N×M (모델 수 × 도구 수)	N+M

업계 채택 현황

MCP는 더 이상 Anthropic만의 프로토콜이 아니다.

OpenAI, Google DeepMind, Microsoft, AWS, Cloudflare가 모두 지원하며, Linux Foundation 산하 Agentic AI Foundation(AAIF)에서 관리된다.

2026년 기준으로 Gartner는 API 게이트웨이 벤더의 75%, iPaaS 벤더의 50%가 MCP 기능을 갖출 것을 전망한다고 한다.

MCP의 작동 원리

아키텍처 구조

MCP는 클라이언트-서버 구조를 따른다. 5개 레이어로 구성된다.

애플리케이션 레이어
(Claude, ChatGPT 등)
	↓
MCP 클라이언트
(기능 탐색, 요청 라우팅)
	↓
전송 레이어
(stdio, HTTP/SSE, WebSocket)
	↓
MCP 서버
(리소스, 도구, 프롬프트)
	↓
데이터 소스
(파일, API, 데이터베이스)

핵심 개념 3가지

리소스(Resources)

MCP 서버가 AI에게 제공하는 데이터다. 파일 내용, 데이터베이스 레코드, API 응답 등이 리소스에 해당한다.

AI가 "읽을 수 있는 것"이라고 생각하면 된다.

도구(Tools)

AI가 "실행할 수 있는 것"이다.

파일 생성, 이메일 발송, 데이터베이스 쿼리, 외부 API 호출 등 실제 동작을 수행하는 함수다.

AI 모델이 도구를 발견하고, 파라미터를 채워 호출하면 MCP 서버가 실행하고 결과를 돌려준다.

프롬프트(Prompts)

MCP 서버가 제공하는 미리 정의된 프롬프트 템플릿이다.

특정 작업에 최적화된 지침을 AI에게 전달하여 일관된 품질을 보장한다.

전송 방식

stdio (표준 입출력)

MCP 서버가 로컬 프로세스로 실행된다. Claude Code에서 로컬 도구를 연결할 때 주로 사용한다. 설정이 간단하고 빠르다.

Streamable HTTP

MCP 서버가 원격 서비스로 실행된다. 웹 기반 배포, 팀 공유, 클라우드 환경에 적합하다. 2026년 로드맵의 핵심 개선 영역이기도 하다.

MCP 서버의 실제 사용 사례

개발 워크플로우

GitHub MCP 서버 : AI가 이슈 조회, PR 생성, 코드 리뷰를 직접 수행
데이터베이스 MCP 서버 : 자연어로 SQL 쿼리 실행, 결과 분석
파일시스템 MCP 서버 : 프로젝트 파일 읽기, 수정, 생성

비즈니스 자동화

Slack MCP 서버 : 배포 알림, 빌드 실패 통지 자동화
Google Drive MCP 서버 : 문서 검색, 요약, 편집
Jira MCP 서버 : 티켓 생성, 상태 업데이트, 스프린트 관리

게임 개발에서의 활용

Unity/Unreal 빌드 시스템과 연동하여 자동 빌드 트리거
에셋 데이터베이스 조회 및 관리
버그 트래커 연동으로 이슈 자동 분류

Claude Code에서 MCP 서버 설정하기

기본 설정 구조

Claude Code에서 MCP 서버는 settings.json에 설정한다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

설정 위치별 용도

위치	용도
~/.claude/settings.json	모든 프로젝트에서 사용할 MCP 서버
.claude/settings.json	팀이 공유하는 프로젝트 전용 MCP 서버
.claude/settings.local.json	개인 프로젝트 오버라이드

서브에이전트에서 MCP 사용

Claude Code의 서브에이전트(.claude/agents/*.md)에서 특정 MCP 서버만 연결할 수도 있다.

이렇게 하면 db-analyst 에이전트는 postgres MCP 서버만 사용하게 되어, 권한 범위를 최소화할 수 있다.

---
name: db-analyst
description: 데이터베이스 분석 전담 에이전트
mcpServers:
  - postgres-server
model: sonnet
---

MCP의 보안 고려사항

알려진 위험

프롬프트 인젝션: 악의적 데이터가 MCP 서버를 통해 AI의 지시를 조작할 수 있다
도구 권한 남용: 여러 도구를 조합하여 데이터를 유출할 가능성이 있다
유사 도구 공격: 신뢰할 수 있는 도구와 이름이 비슷한 악성 도구가 대체될 수 있다

방어 원칙

최소 권한 원칙: 에이전트에 필요한 MCP 서버만 연결
샌드박스 환경: AI가 승인된 데이터와 동작에만 접근 가능하도록 격리
명시적 컨텍스트 선언: AI가 리소스 접근 전에 의도와 맥락을 명시
권한 범위 지정: AI 접근 권한을 기존 시스템 권한과 일치시키는 세분화된 제어

MCP 로드맵

1. 전송 진화와 확장성

Streamable HTTP 전송을 개선하여 MCP 서버가 수평 확장 가능하도록 한다.

로드밸런서와의 충돌 해결, 세션 관리 표준화가 핵심이다. 또한 .well-known URL을 통해 서버 메타데이터를 노출하는 MCP Server Card 표준을 도입하여, 연결 없이도 서버의 기능을 탐색할 수 있게 한다.

2. 에이전트 간 통신

에이전트가 다른 에이전트에게 작업을 위임하는 패턴이 늘어나면서, 작업 실패 시 재시도 의미론, 작업 라이프사이클 관리 등의 규격이 필요해졌다.

3. 거버넌스 성숙

오픈소스 프로젝트로서의 거버넌스 체계를 정비한다. 워킹그룹이 프로토콜 개발의 주요 수단이 되고, SEP(Spec Enhancement Proposal)를 통해 변경 사항을 관리한다.

4. 엔터프라이즈 준비

감사 추적, SSO 통합 인증, 게이트웨이 패턴, 설정 이식성 등 기업 환경에서 필요한 기능들을 정의한다.

대부분 핵심 스펙이 아닌 확장(extension)으로 구현될 예정이다.

MCP vs 기존 기술 비교

항목	REST API	OpenAPI	MCP
목적	범용 웹 서비스 통신	API 명세 표준화	AI 모델과 도구 연결 표준화
대상	모든 소프트웨어	API 개발자	AI 에이전트/모델
도구 탐색	수동 (문서 참조)	자동 (스펙 파싱)	자동 (프로토콜 내장)
양방향 통신	제한적	없음	지원
컨텍스트 관리	없음	없음	내장

MCP는 REST API를 대체하는 것이 아니다. MCP 서버 내부에서 실제 데이터 작업은 여전히 기존 API를 통해 이루어진다.

MCP는 그 위에 AI가 이해할 수 있는 표준 레이어를 씌운 것이다.

시작하기

Claude Code에서 기본 MCP 서버 사용해보기: 파일시스템 MCP 서버를 설정하고 Claude가 파일을 직접 읽고 쓰는 것을 체험
공식 레퍼런스 서버 탐색: GitHub MCP 서버 저장소에서 다양한 서버 구현 확인
나만의 MCP 서버 만들기: TypeScript 또는 Python SDK를 사용해 간단한 도구를 MCP 서버로 래핑
프로젝트에 통합: CLAUDE.md에 MCP 서버 사용 규칙을 문서화하고, settings.json에 서버를 등록

마무리

MCP는 AI가 "대화만 잘하는 챗봇"에서 "실제 업무를 수행하는 에이전트"로 진화하는 데 필요한 핵심 인프라다.

REST가 웹 서비스의 통신 방식을 통일했듯이, MCP는 AI와 외부 세계의 통신 방식을 통일하고 있다.

게임 개발자 관점에서 보면, CLAUDE.md가 "Claude에게 코딩 규칙을 가르치는 것"이라면 MCP는 "Claude에게 외부 도구를 사용하는 손을 달아주는 것"이다.

이 두 가지를 잘 조합하면 Claude Code를 단순한 코드 생성기가 아니라 프로젝트 전체를 이해하고 도구를 활용하는 개발 파트너로 만들 수 있다.

참고 자료

공식 문서 및 스펙

MCP 공식 사이트 (프로토콜 스펙, SDK 문서, 거버넌스 정보)
MCP GitHub 저장소 (TypeScript/Python SDK, 레퍼런스 서버 구현)
2026 MCP 로드맵 (전송 확장성, 에이전트 통신, 거버넌스, 엔터프라이즈 준비 4대 우선 영역)
MCP Roadmap 공식 페이지 (워킹그룹별 우선순위 및 SEP 가이드라인)
Claude Code Settings 공식 문서 (MCP 서버 설정 방법, 설정 계층 구조)

분석 및 가이드

Model Context Protocol — Wikipedia (MCP 개요, 채택 현황, 보안 이슈 요약)
MCP Complete Guide 2026 — DEV Community (아키텍처, 구현 패턴, 실전 적용 가이드)
MCP: The Standard That's Changing AI Integration — Dev Note (MCP 서버 구현 예제 코드 포함)
What Is MCP? Complete Beginner's Guide 2026 — SmarteAI (비개발자를 위한 MCP 개념 설명)
What is MCP? The 2026 Guide for SaaS PMs — Truto (SaaS 관점의 MCP 전략, Gartner 전망 인용)

업계 동향

MCP's Biggest Growing Pains — The New Stack (프로덕션 환경의 MCP 과제와 로드맵 분석)
2026: The Year for Enterprise-Ready MCP Adoption — CData (엔터프라이즈 MCP 도입 전략, 보안 및 거버넌스)

[Claude] Claude.md

HONGGG — Tue, 7 Apr 2026 04:28:09 +0900

Claude-Code 나만의 프로젝트를 이해하는 개발자로..

CLAUDE.md 개요

Claude Code는 매 세션마다 기억을 잃는다.

아무리 어제 훌륭한 대화를 했더라도, 오늘 새 세션을 열면 내 코드 스타일도, 프로젝트 구조도, 선호하는 도구도 모른다.

매번 같은 설명을 반복하는 것은 시간 낭비다.

CLAUDE.md는 이를 해결한다.

CLAUDE.md는 클로드가 세션 시작 시 자동으로 읽는 마크다운 파일로, 한 번 작성해두면 모든 대화에 자동 적용된다.

잘 쓴 CLAUDE.md 하나가 프롬프트 수십 줄보다 효과적이다.

핵심 원칙: 짧고, 구체적이고, 실행 가능하게

CLAUDE.md 작성에서 가장 중요한 원칙이 있다.

짧게 유지하라

100줄 이하가 이상적이다.

프론티어 사고 모델은 약 150~200개의 지침을 합리적으로 따를 수 있지만, 그 이상은 준수율이 급격히 떨어진다.

모든 것을 담으려 유혹을 참아야 한다.

구체적인 규칙을 작성하라

"pnpm 사용, npm 말고" 같은 구체적 규칙은 약 89%의 준수율을 보이는 반면, "깔끔한 코드를 작성하라" 같은 모호한 지침은 약 35%에 머문다.

제재는 대안과 함께

좋은 CLAUDE.md 파일들은 안전한 대안을 함께 제시한다는 것이다.

# 나쁜 예
- flag 파라미터 사용 금지

# 좋은 예
- flag 파라미터로 동작을 분기하지 말 것 — 함수를 분리

파일 계층 구조 이해하기

CLAUDE.md는 단일 파일이 아니라 계층 시스템이다.

나중에 로딩되는 파일이 더 높은 우선순위를 갖는다.

로딩 순서 (낮은 → 높은 우선순위)

순서	위치	용도
1	/etc/claude-code/CLAUDE.md	관리자 전역 정책 (오버라이드 불가)
2	~/.claude/CLAUDE.md	개인 글로벌 설정
3	{프로젝트 루트}/CLAUDE.md	팀 공유 프로젝트 규칙
4	.claude/CLAUDE.md	프로젝트 규칙 (서브디렉토리 버전)
5	CLAUDE.local.md	개인 프로젝트 오버라이드 (gitignore 대상)

윈도우 경로 정리

글로벌: C:\Users\{사용자명}\.claude\CLAUDE.md
글로벌 규칙 폴더: C:\Users\{사용자명}\.claude\rules\*.md
글로벌 설정: C:\Users\{사용자명}\.claude\settings.json

글로벌과 프로젝트를 섞지 마라

글로벌 파일에는 프로젝트와 무관한 개인 선호만, 프로젝트 파일에는 해당 프로젝트의 스택과 구조만 넣어야 한다.

이 두 가지가 섞이면 Claude가 매 작업마다 불필요한 컨텍스트를 짊어지게 된다.

글로벌 CLAUDE.md

글로벌 파일은 모든 프로젝트에 적용되는 나의 개발 원칙이다.

최상위 엔지니어들의 글로벌 파일에서 공통적으로 발견되는 항목들을 정리하면 다음과 같다.

언어 설정

간단하지만 매 세션마다 "한국어로 대답해줘"를 반복하지 않아도 된다.

- 대화와 설명은 한국어로 응답
- 코드 주석, 커밋 메시지, 변수명은 영어

코드 스타일 (범용)

여기서 핵심은 "모든 프로젝트에 적용되는가?"를 자문하는 것이다.

Unity 전용 규칙이나 특정 프레임워크 패턴은 여기에 넣지 않는다.

- 엄격한 타이핑 — 함수 반환값, 변수, 컬렉션 모두 타입 명시
- 단일 책임 원칙 — 하나의 함수는 하나의 일만 수행
- 새 로직 작성 전 기존 코드에 동일 로직이 있는지 먼저 검색
- 매직 넘버 금지 — 상수로 정의하고 이름을 부여

에러 처리

- 에러를 조용히 무시하지 말 것 — 항상 명시적으로 처리
- 포괄적 catch-all 금지 — 구체적 에러 타입 사용
- 에러 메시지에 원인과 조치 방법 포함

작업 행동 규칙

이 부분이 코딩 품질에 가장 큰 영향을 미친다.

Claude의 가장 흔한 실수는 "너무 많은 것을 한꺼번에 바꾸는 것"이다. 이 규칙 하나만 넣어도 코드 품질이 체감될 만큼 달라진다.

- 실패하면: 멈추고 → 원인 설명 → 확인 후 진행
- 변경 전 영향 범위 파악 — "다른 곳에서 안 쓴다"는 추측 금지, grep으로 증명
- 되돌릴 수 없는 작업은 반드시 확인 요청
- 한 번에 너무 많이 바꾸지 말 것 — 작은 단위로 검증하며 진행

금지사항

- 추측으로 패키지 버전이나 API 시그니처 지정 금지 — 확인 후 사용
- 요청하지 않은 리팩토링 금지 — 현재 작업 범위에만 집중
- "깔끔하게 정리했습니다" 같은 모호한 보고 금지 — 무엇을 변경했는지 구체적으로 명시

프로젝트 CLAUDE.md

프로젝트 파일에는 세 가지를 넣는다: 무엇(WHAT), 왜(WHY), 어떻게(HOW).

WHAT — 기술 스택과 구조

## 프로젝트 개요
Unity 2022.3 LTS, URP 기반의 3D 액션 게임

## 디렉토리 구조
- Assets/Scripts/Core — 게임 루프, 매니저
- Assets/Scripts/Combat — 전투 시스템
- Assets/Scripts/UI — UI 관련
- Assets/Prefabs — 프리팹
- Assets/ScriptableObjects — 데이터 에셋

WHY — 아키텍처 결정 사항

## 아키텍처 결정
- 싱글톤 대신 ScriptableObject 기반 이벤트 시스템 사용
  → 테스트 용이성과 씬 간 의존성 제거 목적
- ECS는 사용하지 않음 → MonoBehaviour 기반 유지

HOW — 빌드, 테스트, 워크플로우

## 명령어
- 테스트: Unity Test Runner (EditMode + PlayMode)
- 빌드: File > Build Settings > Windows x64

## 코딩 규칙
- MonoBehaviour 상속 클래스는 PascalCase
- SerializeField는 private + [SerializeField]
- GetComponent는 Awake()에서 캐싱, Update()에서 호출 금지
- Update()에서 GC 할당 금지 (new, LINQ, string 연결 등)

워크플로우

/init으로 시작하고, 깎아내기

프로젝트 디렉토리에서 /init 명령을 실행하면 Claude가 프로젝트를 분석해 CLAUDE.md 초안을 만들어준다.

하지만 생성된 파일은 보통 불필요한 내용이 많으므로, 필요한 것만 남기고 삭제하는 방식이 효과적이다.

백지에서 쓰는 것보다 깎아내는 게 쉽다.

실수 기반으로 점진적 추가

처음부터 완벽한 파일을 만들려 하지 말자.

Claude가 반복적으로 실수하는 패턴을 발견할 때마다 한 줄씩 추가하는 것이 가장 효과적이다.

예를 들어 Claude가 자꾸 var를 이 한 줄을 추가하면 된다.

- var 사용 금지 — 명시적 타입 선언 사용

rules/ 디렉토리 활용

글로벌 CLAUDE.md가 길어질 것 같으면 ~/.claude/rules/ 폴더에 주제별 .md 파일로 분리할 수 있다.

~/.claude/
├── CLAUDE.md          ← 핵심 규칙 (30~50줄)
└── rules/
    ├── git.md         ← Git 관련 규칙
    ├── error.md       ← 에러 처리 규칙
    └── naming.md      ← 네이밍 규칙

컨텍스트 관리

CLAUDE.md에 넣은 모든 내용은 매 대화마다 컨텍스트 윈도우를 차지한다.

불필요한 내용이 많을수록 Claude가 실제 작업에 쓸 수 있는 공간이 줄어든다.

또한 관련 없는 지침이 많으면 Claude가 파일 전체를 무시할 확률도 높아진다.

설정 파일과 역할 분리

CLAUDE.md에 넣으면 안 되는 것들도 있다.

권한, 도구 허용, 모델 선택 같은 하드웨어적 설정은 settings.json에 넣어야 한다.

CLAUDE.md는 "어떻게 코딩할 것인가"에 대한 지침이고, settings.json은 "무엇을 허용할 것인가"에 대한 설정이다.

내용 예제	입력
"pnpm 사용, npm 말고"	CLAUDE.md
"Bash 도구 허용"	settings.json
"커밋 메시지는 영어"	CLAUDE.md
"Co-Authored-By 제거"	settings.json (attribution.commit: "")
"테스트 먼저 실행"	CLAUDE.md
"모델은 sonnet 사용"	settings.json

CLAUDE.md에 절대 넣지 말아야 할 것

API 키, 비밀번호, 토큰
- CLAUDE.md는 컨텍스트에 로딩되므로 보안 위험
Claude가 이미 아는 것
- 표준 문법, 일반적인 라이브러리 API 설명
뻔한 지침
- "깨끗한 코드 작성", "주석 추가" 같은 당연한 내용
너무 긴 문서
- 상세한 아키텍처 문서는 별도 파일에 두고 @로 참조

사용량 관리

Claude Code는 사용량 제한이 있다. /status에서 Usage 탭을 확인하면 세션과 주간 사용량을 볼 수 있다.

Current session
- 현재 세션의 사용량. 매일 특정 시간에 리셋
Current week
- 주간 전체 사용량. 매주 리셋
세션이 100%가 되면 완전 차단이 아니라 속도 제한이 걸림
/extra-usage로 추가 사용량 활성화 가능]

컨텍스트 관리도 사용량에 영향을 미친다.

컨텍스트가 50%를 넘으면 /compact로 압축하고, 작업 전환 시에는 /clear로 리셋하는 습관을 들이자.

요약 체크리스트

~/.claude/CLAUDE.md에 개인 글로벌 규칙 작성 (50~100줄)
프로젝트 루트에서 /init 실행 후 불필요한 내용 삭제
사용하면서 Claude의 반복 실수를 발견할 때마다 한 줄씩 추가
파일이 길어지면 rules/ 디렉토리로 분리
주기적으로 검토하여 더 이상 필요 없는 규칙 제거

가장 효과적인 CLAUDE.md는 실제 마찰을 해결하는 파일이다.

이론적으로 완벽한 규칙집이 아니라, 내가 반복적으로 겪는 문제를 한 줄씩 해결해 나간 파일이 결국 가장 강력하다.

[Unity] #1 Profiler - 프로파일러 모듈

HONGGG — Fri, 3 Apr 2026 18:20:02 +0900

Unity Profiler 기본 항목

숫자를 해석하는 법

지난 글에서는 왜 최적화보다 프로파일링이 먼저인지 이야기했다.
핵심은 단순했다. 감으로 문제를 고치기 전에, 먼저 무엇이 실제 병목인지 읽을 수 있어야 한다는 것이다.

이번 글은 Unity Profiler에서 반드시 읽을 수 있어야 하는 기본 항목들에 대한 글이다.

Profiler를 처음 열면 CPU, GPU, Rendering, Memory, Audio, Physics, UI, Timeline, Hierarchy 등 여러 정보가 한꺼번에 보이기에, 아무것도 읽히지 않는 경우가 있다.

프로파일러 기본 모듈 리스트

우선 욕심을 줄이고, "모든 걸 다 본다"가 아니라 "가장 중요한 것부터 순서대로 읽는다"는 접근이 필요하다.

Unity Profiler의 핵심 항목이 무엇인지 이해한다
각 항목이 어떤 종류의 비용을 의미하는지 구분한다
실제 게임 성능 문제를 볼 때 어떤 순서로 읽어야 하는지 감을 잡는다

이는 "Profiler를 어디부터 읽어야 하는지 아는 사람"이 되는 것이 이번 단계의 목표를 가진다.

CPU Usage, Timeline, Hierarchy의 역할 차이 알기
GC Alloc이 왜 중요한지 알기
Rendering 수치를 단순 시각 정보가 아니라 비용 정보 보기
성능 문제를 볼 때 어떤 순서로 Profiler를 열어봐야 할지 알기

Profiler 확인 방법

"일단 뭐가 제일 높게 찍히는지 보면 되는 거 아닌가?"

위 인용란의 문장은 반은 맞고, 반은 틀리다.

큰 값은 분명 중요하다. 하지만 숫자 하나만 보고 결론을 내리면 쉽게 오판한다.

예로 어떤 프레임에서 CPU Usage가 높게 나왔다고 다음 사실들이 무시되면 안된다.

CPU 전체가 높은 것인가?
메인 스레드만 높은 것인가?
특정 함수 하나가 튄 것인가?
GC 때문에 순간적으로 멈춘 것인가?
렌더링 준비 비용이 큰 것인가?
로딩 후처리가 그 프레임에 몰린 것인가?

즉, 프로파일러는 "정답을 주는 창"이 아니라 질문을 좁혀가는 도구다.

CPU Usage - 가장 큰 지도

Profiler에서 가장 먼저 보게 되는 항목 중 하나가 CPU Usage다.
이 항목은 말 그대로 CPU에서 프레임이 어떻게 소비되고 있는지를 큰 분류로 보여준다.

런타임에 발생하는 CPU 점유율 표시

왜 CPU Usage가 중요할까?

대부분의 게임 플레이 문제는 결국 CPU에서 체감되기 때문이다.

입력 처리
게임 로직
애니메이션 업데이트
물리 처리
UI 갱신
렌더링 준비
데이터 바인딩
로딩 후처리

위 같은 대부분의 작업은 우선 CPU에서 돌아간다.
그래서 성능 문제가 생겼을 때, 가장 먼저 "이번 프레임이 CPU 쪽 문제인가?"를 확인하는 출발점이 된다.

초반에는 세부 분류를 모두 외우려 하기보다, "지금 병목이 스크립트 쪽인지, 렌더 준비 쪽인지, GC 쪽인지" 정도만 구분할 수 있어도 충분하다.

사용량이 가장 높은 항목	따라오는 의문
Scripts 점유율 과도	코드 실행량이 많나? 하나의 코드에서 발생하나?
Rendering 점유율 과도	그리는 준비 비용이 큰가? 어떤 렌더링 리소스가 가장 크게 비중을 차지했나?
GC 점유율 과도	메모리 할당/회수 문제가 발생하나? 메모리 리크가 발생하고 있나?
Main Thread 점유율 과도	메인 스레드가 프레임을 잡아 먹고 있나? 불필요한 반복 비용에 잡혀있는가?

CPU Usage는 정답을 주지는 않지만, 문제의 대분류를 찾을 수 있다.
아직 정답을 주지는 않지만, 어디를 더 깊게 파야 하는지를 알려준다.

Timeline - 프레임 안에서 무슨 일이 순서대로 일어났는지 보는 창

CPU Usage가 큰 지도라면, Timeline은 그 지도를 확대해서 보여주는 도구다.

Timeline의 가장 큰 장점은 프레임 안에서 어떤 작업이 어떤 순서로, 얼마나 길게 실행되었는지를 시간축으로 보여준다는 점이다.

이게 왜 중요할까?

실제 성능 문제는 "무엇이 느린가"보다 "언제, 어떤 맥락에서 느려졌는가"가 더 중요할 때가 많다.

예로 팝업을 여는 순간 프레임이 튄다고 가정해면, Timeline을 보면 이런 흐름이 드러날 수 있다.

팝업 Open 프로세스

버튼 입력 처리
스크립트에서 팝업 Open 호출
데이터 바인딩
텍스트 갱신
UI 리빌드
렌더링 준비
프레임 종료

이 순서가 보이면 우리는 단순히 "UI가 느리다"가 아니라 "팝업 Open 이후 데이터 바인딩과 UI 리빌드가 같은 프레임에 겹쳤다"라고 말할 수 있게 된다.

Timeline은 이런 경우에 특히 강력하다.

어떤 이벤트 직후 스파이크가 생길 때
여러 시스템이 한 프레임에 몰려 있을 때
스레드별 실행 흐름을 보고 싶을 때
원인과 결과의 순서를 확인하고 싶을 때

처음에는 너무 많은 줄이 보여서 복잡해 보이지만, 초반에는 아래처럼만 보면 된다.

Main Thread에서 가장 긴 구간이 무엇인가
Render Thread는 어떤 상태인가
특정 이벤트 직후 어떤 마커가 이어서 나타나는가
GC가 끼어드는 시점은 언제인가

즉, Timeline은 프레임 내부의 사건 기록이다.

Hierarchy - 무엇이 많이 쌓였는지 보기 좋은 집계표

Timeline이 시간 순서 중심이라면, Hierarchy는 비용 누적 중심이다.

Hierarchy는 어떤 함수나 마커가 총 얼마의 시간을 차지했는지 보기 쉽다.
시간축보다 구조적으로 정리되어 보이기 때문에, 초반에는 오히려 Timeline보다 읽기 쉬울 수 있다.

Hierarchy 장점

각 함수들에 사용되는 가장 큰 비용을 빨리 찾고 싶을 때
호출 구조를 따라가며 누적 비용을 보고 싶을 때
특정 시스템이 전체 프레임에서 얼마를 차지하는지 확인하고 싶을 때

예를 들면...

PlayerLoop
BehaviourUpdate
Canvas.SendWillRenderCanvases
Camera.Render
Physics.Simulate

같은 상위 항목 아래에 어떤 비용이 쌓이는지 보기 좋다.

Hierarchy는 특히 "무엇이 많이 쌓였는가"를 볼 때 좋지만, 반면 "어떤 순서로 일어났는가"는 Timeline이 더 잘 보여준다.

두 창은 서로 경쟁 관계가 아니라 보완 관계다.

Timeline	Hierarchy
사건의 순서와 맥락	비용의 누적과 크기

프로파일링 초반에 Timeline으로 맥락을 보고, Hierarchy로 크기를 검증하는 습관을 들여보자.

GC Alloc - 최적화를 놓치는 주원인

게임이 버벅일 때 사람들은 종종 렌더링, 이펙트, 복잡한 로직만 의심한다.
그런데 실제로는 의외로 자주 GC Alloc가 핵심 원인이다.

GC Alloc은 프레임 중 발생한 메모리 할당을 보여준다.

여기서 중요한 것은 "메모리를 썼다"는 사실보다, 그 메모리 할당이 이후 GC를 유발해 프레임을 끊기게 만들 수 있다는 점이다.

자주 나오는 원인은 다음과 같다.

문자열 합치기
임시 리스트 생성
LINQ 사용
foreach 박싱
람다 캡처
JSON 파싱 후 임시 객체 생성
UI 바인딩 시 반복적인 객체 생성

예를 들어 팝업을 열 때 프레임이 튄다고 할때, 겉으로 보면 UI 문제처럼 보일 수 있다.
하지만 실제로는 팝업을 열면서 리스트를 새로 만들고, 문자열을 가공하고, 데이터를 매핑하는 과정에서 GC Alloc이 커질 수도 있다.

이 경우 병목은 "UI 렌더"가 아니라 UI를 그리기 전에 데이터를 준비하는 코드일 수 있다.

초반에 반드시 익혀야 할 습관은 이것이다.

"스파이크 프레임이 나오면, CPU 마커만 보지 말고 GC Alloc도 같이 본다."

GC Alloc은 수치가 작아 보여도 무시하면 안 된다. 상시로 조금씩 쌓이는 할당은 결국 큰 GC로 돌아올 수 있기 때문이다.

Rendering - CPU에서 렌더링 준비 비용을 보는 관점

Profiler의 Rendering 관련 항목은 "GPU가 얼마나 바쁜가"와는 조금 다르다.

많은 경우 Unity Profiler에서 먼저 보게 되는 것은 CPU가 렌더링을 준비하는 비용이다.

여기서 중요한 건 다음과 같은 시그널이다.

Draw Calls 증가
Batches 증가
SetPass Calls 증가
Visible objects 증가

이 값들이 중요한 이유는, 게임이 복잡해질수록 단순히 "보이는 것이 많다"가 아니라 얼마나 비효율적으로 그리기 준비를 하고 있는가가 문제로 드러나기 때문이다.

예를 들어

같은 머티리얼을 못 묶어서 배치가 쪼개질 수 있다
UI가 여러 마스크와 다른 텍스처 조합으로 인해 배치가 깨질 수 있다
파티클과 이펙트가 Draw Call을 많이 늘릴 수 있다
장면 전환 시 한 프레임에 렌더링 준비가 몰릴 수 있다

Rendering 수치는 단독으로 보면 막연할 수 있기에 CPU Usage, Timeline과 같이 봐야 해석이 쉬워진다.

예로, Canvas.BuildBatch가 높고 Batches도 같이 늘었다면 UI 구조와 렌더링 준비 비용이 연결되어 있다는 뜻으로 볼 수 있다. 즉, Rendering은 단순 시각 효과의 문제가 아니라 프레임을 준비하는 과정의 비용을 읽는 창이다.

Memory - 느려짐이 아니라, 느려질 준비가 되어 있는지 보는 창

Memory는 어떤 프레임이 느렸는지를 직접 보여주는 창이라기보다, 앞으로 문제가 생길 여지를 보여주는 창에 가깝다.

메모리 사용량이 계속 증가하거나, 특정 시점마다 큰 할당과 해제가 반복되면 나중에 GC나 로딩 스파이크, 심지어 메모리 부족 문제로 이어질 수 있다.

너무 깊게 들어가기에 페이지가 새로 필요하기에, 적어도 다음 정도는 볼 수 있어야 한다.

메모리 사용량이 지속적으로 증가하는가
씬 전환 후 메모리가 정상적으로 내려오는가
특정 기능 실행 시 큰 임시 할당이 생기는가
객체가 예상보다 오래 살아남는가 = 객체 예상 평균생존기간 초과

메모리는 당장 프레임 하나만 보고 판단하기 어렵기 때문에, CPU나 GC 문제와 연결해서 보는 것이 중요하다.

로딩 후 메모리 급증
이후 GC 스파이크 발생
플레이 중 주기적 hitch 발생

이렇게 연결되면, 단순한 순간 병목이 아니라 메모리 라이프사이클 문제일 수 있다는 힌트를 준다.

Frame Debugger - 실제로 어떻게 그려졌는지 확인하는 도구

Profiler가 시간 기준 분석 도구라면, Frame Debugger는 렌더 순서 분석 도구다.

Frame Debugger는 한 프레임 안에서 실제 Draw call이 어떻게 발생했는지를 단계별로 보여준다.

그래서 "왜 draw call이 늘었는가", "왜 배치가 안 묶였는가"를 볼 때 매우 유용하다.

이 도구는 특히 이런 상황에서 강하다.

UI 배치가 이상하게 많이 쪼개질 때
머티리얼이 섞여 draw call이 늘 때
마스크와 클리핑이 많이 걸릴 때
특정 오브젝트가 예상보다 자주 그려질 때
Overdraw를 의심할 때

Frame Debugger는 숫자보다 실제 그려지는 순서와 분리 이유를 보여준다는 점에서 강력하다.
Profiler에서 "왜 이 마커가 높지?"라는 질문이 생겼을 때, Frame Debugger가 그 이유를 시각적으로 설명해주는 경우가 많다.

읽기 순서

1. CPU Usage에서 큰 분류를 본다

이번 프레임이 CPU 병목인가?
Main Thread가 긴가?
Scripts / Rendering / GC 중 무엇이 눈에 띄는가?

2. Timeline으로 프레임 안의 사건 순서를 본다

스파이크가 정확히 언제 발생했는가?
어떤 이벤트 직후 비용이 몰렸는가?
여러 비용이 같은 프레임에 겹쳤는가?

3. Hierarchy로 누적 비용을 본다

가장 큰 비용을 차지하는 함수/마커는 무엇인가?
상위 구조 아래 어떤 비용이 쌓였는가?

4. GC Alloc을 확인한다

이 프레임의 문제에 메모리 할당이 끼어들었는가?

5. Rendering / UI / Frame Debugger로 세부 원인을 확인한다

draw call이 왜 늘었는가?
UI 배치가 왜 깨졌는가?
실제 그리는 순서가 어떻게 되어 있는가?

팝업을 열었는데 프레임이 튄다면

간단한 상황을 부여한다.

"게임 로비에서 인벤토리 팝업을 여는 순간 프레임이 튄다."

이때 Profiler를 어떻게 읽을까?

1. CPU Usage 확인

Main Thread가 튀었는가?
Scripts와 Rendering 중 어느 쪽이 더 큰가?
GC Alloc이 함께 발생했는가?

2. Timeline 확인

버튼 클릭 직후 어떤 호출이 이어졌는가?
팝업 Open 이후 데이터 바인딩이 들어갔는가?
UI 관련 마커가 뒤이어 나타나는가?

3. Hierarchy 확인

가장 큰 비용은 Canvas.BuildBatch인가?
Graphic.Rebuild인가?
데이터 처리 함수인가?
Instantiate인가?

4. 추가 분석

UI Details에서 Batches/Vertices가 얼마나 증가했는가?
Frame Debugger에서 draw call이 크게 쪼개졌는가?
GC Alloc이 높다면 문자열/리스트 생성이 있었는가?

막연히 "팝업이 무겁다"가 아니라 "팝업 Open 시 데이터 바인딩 + 텍스트 갱신 + UI 리빌드가 같은 프레임에 몰려 메인 스레드가 튄다"라고 해석할 수 있게 된다.

[Unity] #0 Profiler - 개요

HONGGG — Fri, 3 Apr 2026 17:17:11 +0900

Unity 프로파일링 학습 로드맵

최적화 기법을 외우기 전에, 프로파일러를 읽는 사람 되기

이 학습의 목표는 단순히 "최적화하는 법"을 아는 것이 아니다.
진짜 목표는 프로파일러에서 보이는 숫자와 마커를 보고, 현재 구조의 문제를 스스로 해석할 수 있는 능력을 만드는 것이다.

특히 이번 학습은 다음 질문에 답할 수 있도록 설계한다.

지금 프레임이 왜 느린가?
이 비용은 UI 때문인가, 로직 때문인가, 데이터 바인딩 때문인가?
팝업 On/Off 비용이 어느 정도면 괜찮고, 어느 정도면 구조를 바꿔야 하는가?
현재 UI 구조에서 어떤 설계가 더 유리한가?

학습 개요

성능 문제가 보이면 많은 경우 바로 해결책을 떠올린다.

객체 수를 줄여야 하나?
Canvas를 나눠야 하나?
로딩 방식을 바꿔야 하나?
Update를 줄여야 하나?
비동기로 바꿔야 하나?

위와 같은 조언은 많이 보이지만 실제로 어떤 비용이 발생하는지 모르면 그 판단은 거의 감에 가깝다.

예를 들어 프레임 드랍이 발생했다고 해보자.

겉으로 보기에는 "이펙트가 많아서 느린 것 같다"고 느껴질 수 있다.
하지만 실제 프로파일러를 열어보면 병목은 전혀 다른 곳에 있을 수 있다.

그래서 첫 단계의 핵심은 "최적화 기술"이 아니라 "측정의 언어"를 익히는 것이다.

프로파일러는 단순히 느린 구간을 보여주는 도구가 아니다.
프레임 안에서 어떤 시스템이 시간을 쓰고 있는지를 분해해서 보여주는 해석 도구다.

소프트웨어가 60FPS를 목표로 한다면 한 프레임은 16.67ms 안에 끝나야 한다.

초 단위 계산 : 1 / 60 = 0.0166666...s

밀리초(ms) 계산 : 1000ms / 60 = 16.67ms

즉, 어떤 UI 팝업을 여는 순간 8ms가 추가로 튄다면, 그것은 단순한 숫자가 아니라 전체 프레임 예산의 절반 가까이를 소비했다는 뜻이다. 이 해석이 가능해야 프로파일링이 시작된다.

이 단계의 목표는 하나다. "느리다"를 말하는 대신, "어느 프레임에서 무엇이 몇 ms 튀었다"라고 말할 수 있게 되는 것이다.

"프로파일링은"툴 사용법"이 아니라 "판단 체계"다.

유니티 프로파일러는 프로파일러 창에서 버튼 몇 개를 누르는 것으로 사용하는 것이 아니다.

툴 조작도 필수적이지만 실질적으로 해당 툴이 제공하는 숫자를 해석할 줄 아는것이 가장 중요하다.

프로파일링은 결국 다음과 같은 질문에 답하는 과정이다.

지금 느린 구간은 어느 프레임에서 발생했는가?
그 프레임에서 가장 큰 비용은 무엇인가?
그 비용은 CPU인가, GPU인가, 메모리인가?
이 비용은 일시적인가, 반복적인가?
사용자가 체감할 만큼 큰가?
목표 플랫폼 기준에서 허용 가능한 범위인가?
구조 문제인가, 구현 문제인가, 데이터 문제인가?

프로파일링 학습 마일스톤

1단계. 프로파일러가 무엇을 보여주는지 이해한다.

이 단계에서는 "메뉴 설명"보다, 각 항목이 무슨 종류의 비용을 뜻하는지를 익혀본다.

CPU Usage
Timeline
Hierarchy
Rendering
Memory
GC Alloc

2단계. 프레임 예산과 측정 기준을 세운다.

60FPS 기준 16.67ms
30FPS 기준 33.33ms
순간 스파이크와 상시 비용 구분
평균값과 최대값 구분

3단계. 실제 게임 기능 하나를 골라 본다.

기능 하나를 잡고, 그 기능이 일어나는 프레임을 정확히 찾아본다.

UI 팝업 전환
로비 진입
전투 시작
인벤토리 정렬
로딩 직후 연출 재생

4단계. 원인과 결과를 연결한다.

"팝업 On 시 Canvas 관련 마커 상승"
"로딩 직후 Instantiate 비용 상승"
"정렬 버튼 클릭 후 GC Alloc 증가"

5단계. 변경 전후를 비교한다.

프로파일링은 분석 후 구조를 바꾸거나 코드를 수정한 뒤, 변경 전과 변경 후를 비교해야 완성된다.

[Unity] 최적화 체크리스트

HONGGG — Fri, 3 Apr 2026 12:41:24 +0900

Unity 성능 최적화 체크리스트

측정 기준부터 고정해라.

어떤 씬을 측정할지 정한다.
어떤 기기에서 볼지 정한다.
측정 항목을 고정한다 : FPS, Main Thread ms, GC Alloc, Draw Call, SetPass, 메모리 사용량, 로딩 시간.
변경 전/후 수치를 반드시 기록한다.

CPU 병목부터 본다.

Update, LateUpdate, FixedUpdate에 불필요한 반복 로직이 없는지 본다.
GetComponent, Find, Camera.main 같은 반복 호출을 줄인다.
LINQ, boxing, 문자열 결합, delegate 캡처가 런타임 hot path에 없는지 본다.
이벤트 기반으로 바꿀 수 있는 풀링 로직을 찾는다.

GC Alloc을 관리한다.

프레임마다 new가 발생하는 코드가 없는지 본다.
로그 문자열 조합이 런타임에서 과하게 발생하지 않는지 본다.
컬렉션 재할당, 임시 배열 생성, ToList() 남발을 줄인다.
가능하면 전투/UI 핵심 루프는 GC Alloc 0B/frame을 목표로 한다.

UI를 별도로 본다.

Canvas를 너무 크게 묶지 않았는지 확인한다.
Layout Group, Content Size Fitter, 잦은 SetActive가 Rebuild를 유발하는지 본다.
ScrollView 항목 재사용이 되는지 본다.
텍스트 변경이 빈번한 UI를 묶어서 관리하는지 본다.

로딩과 Addressables를 본다.

초기 로드가 과도하게 크지 않은지 본다.
프리로드와 지연 로드를 구분했는지 본다.
Handle 해제 누락이 없는지 본다.
Addressables 그룹이 너무 뭉쳐 있거나 너무 쪼개져 있지 않은지 본다.
씬 진입 시 동기 대기가 들어가 있는지 본다.

메모리와 리소스를 본다.

텍스처 크기와 압축이 적절한지 본다.
중복 로드되는 에셋이 없는지 본다.
참조가 끊기지 않아 해제 안 되는 객체가 없는지 본다.
오브젝트 풀링이 필요한 대상을 찾는다.

렌더링 비용도 분리해서 본다.

Draw Call, SetPass, Overdraw를 확인한다.
머티리얼/아틀라스 분리가 비효율적이지 않은지 본다.
반투명 UI가 겹쳐 과도한 Overdraw를 만들지 않는지 본다.

[개발] AI 시대 나는 무엇을 해야할까

HONGGG — Sat, 28 Mar 2026 20:48:26 +0900

트렌드는 빠르게 변한다.

원래 기술의 발전속도는 기하급수적이지만, 대 AI시대가 열리고 그 속도는 상상을 초월하는 수준에 달한다.

원래 개발자 3~4명 아니 우습게 10명분의 작업이 월 30만 원짜리 AI 멤버십이면 상단 한 수준으로 개발되는 시대가 왔다.

해본 적도 없는 작업도 프롬프트로 요구사항만 적으면 알아서 개발이 되어버린다.

초기에는 AI에게 기능 위주 개발을 맡겼다면, 이제는 앱 전체에 구조까지 전부 맡기는 수준이다. (실제로 그렇게 일하는 분들도 봤다.)

물론, 금융이나 개인정보와 같은 수준 있는 보안과 복잡한 절차/기능이 필요한 콘텐츠에는 AI에게 전체 설계를 맡기지는 않겠지만, 자잘한 기능 구현정도는 코드 리뷰 및 QA 과정을 더욱 강화하여 사용할 수 있을 정도로도 보인다. (이쪽 전문가는 아니라 자세히는 모른다.)

나 또한 게으른 편이라 AI의 발전에 엄청난 윤택함을 느끼고 있다. 하지만 반대로 나의 일반적 작업의 대부분이 대체되는 것도 충분히 느껴지고 있다.

그렇다면 무엇을 해야 할까? 고민을 해보고 당연하지만 기억해야하는 대답을 적어볼까 한다.

할 줄 아는 것이 당연하게 되는 세상

나는 지금 시대가 무엇인가를 해보고 싶다면 누구나 간단하게 개발로 찍먹을 해볼 수 있는 시대라고 본다.

이 말은 곧, 기능 구현의 시간이 쉽고 단축되었다고 본다.

개발자였던 친한 형이 GPT조차 없던 시절 이런 말을 한 적이 있다.

"누구에게나 무한한 시간이 주어지면 못 만드는 건 없다."

나도 다수 동의하는 말이다. 하지만 안타깝게도 우리에게는 무한한 시간이 주어지지 않는다.

이는 '콘텐츠 구상 > 필요 기능 추산 > 구조 설계 > 구현 > 테스트 > 검증 > 3자 QA'과정을 시간과 비용의 제약 때문에 개발자라는 직군이 필요했던 부분이 되었다.

하지만 지금은 이 흐름 상당 부분이 AI 보조하에 대체될 수 있게 되었다.

그럼 기능 구현에 대한 부분은 전적으로 AI에게 의존하면 되는가?

이건 개인적으로는 이는 AI를 사용하는 사람의 생각의 깊이와 폭의 차이는 사람마다 다를 것이다.

예를 들어, 다음 소프트웨어를 개발한다 치자.

이쑤시개의 개수를 세는 기능을 만들어라.

정말 간단하게는 '이미지가 주어지면 해당 이미지에서 확인가능한 이쑤시개의 개수를 세는 프로그램을 만들어야 한다.'로 시작할 수 있다.

여기서 다음과 같이 추가 질문을 할 수 있다. (= 추가질문은 프롬프트에 추가적으로 적을 수 있는 지시문이 될 수 있다.)

이미지 포맷은 일정한가?
촬영 환경은 고정인가?
객체 위치는 항상 동일한가?
결과는 어디에 저장되는가?
서버가 필요한가?
인증은 필요한가?

이런 고민들을 계속하다 보면 쓸 때 없는 고민들이 다수 있다. 그래도 가아끔 설계 의도와 배경을 알고 있는 사람만이 할 수 있는 질문들도 나올 수가 있다. 그리고 이는 시스템 설계 영역으로 이어질 거다.

물론 이러한 질문 수준도 아는 만큼만 나온다. 그래서 직접 공부/경험해야 하는 거다.

이러한 질문을 정리하고 기능의 원자성을 가능한 보장 하여 차후 구조가 바뀌더라도 설계 자체가 흔들리지는 않을 정도의 노력은 해봐야 한다.

AI를 적극적으로 사용하되 그 프롬프트에 지시하기까지의 생각은 정리해보아야 한다.

요즘은 프롬프트마저도 자동 생성해 주는 기능들도 있다. 만약 본인의 생각의 깊이와 폭이 넓지 않다면(나부터) 이런 기능들로 놓치고 있는 부분들까지 대비하도록 쓸 수 있을 듯하지만 AI는 방향을 정하지 않는다.

AI는 매우 빠르게 답을 만들어내지만 그 답이 “맞는 방향인지”는 판단하지 않는다.
같은 기능을 만들어도 누군가는 재사용 가능한 구조를 만들고 누군가는 한 번 쓰고 버릴 코드를 만든다.

이런 판단을 잘해보려 노력해야겠다.

우리의 최종적 역할은 구현자가 아니다.

유명한 개발자 유튜버분들 영상을 보다가 "기능을 구현할 수는 있지만 자신이 만든 것도 이해하지도 못하고 버그의 원인도 못 찾는 사람들이 있다."라는 말을 들은 적이 있다.

이제 코드 작성, PR생성, 프로젝트 생성마저도 대신해주는 바이브 코딩이 되는 시대에는 더 와닿는 말이 된 것 같다.

물론 나도 이런 적이 한 번도 없었다고는 양심이 찔려 말할 수는 없다.

일회용 코드, 공유하기 힘든 코드에 대한 부끄러움을 스스로 느끼는 것이 시작일 것이다. ('공유될 일이 절대 없다'하여도)

그렇기에 AI를 잘 쓰는 사람과 그렇지 못한 사람의 차이는 프롬프트가 아니라 설계에서 갈리는 것 같다.

같은 기능을 만들어도 누군가는 확장 가능한 구조를 만들 것이고, 누군가는 다시 버려야 하는 코드를 만든다.

무엇을 만들어야 하는지
왜 그렇게 만들어야 하는지
어떤 확장성을 고려해야 하는지

이 부분은 여전히 사람의 영역으로 보인다.

우리는 무엇을 해야 하는가?

AI를 사용하지 말자고 이 글을 쓰는 것이 아니다. 오히려 적극적 활용을 추천한다.

단, 한 가지 전제만 있으면 될듯하다.

고민하지 않고 쓰지 말기

요구사항을 명확하게 정의할 것
질문을 깊게 던질 것
구조를 먼저 설계할 것
결과를 반드시 이해할 것

이제는 시간이 없어도 무엇인가를 만들 수 있는 시대가 왔다.

다만, 그 '무엇인가'를 제대로 만들 수 있는가는 여전히 사람에게 달려 있다.

[회고] Unity asmdef 세분화 회고

HONGGG — Tue, 17 Mar 2026 16:51:05 +0900

Unity asmdef 세분화 회고 : 설계 회고

이 글은 실제 분할 과정에서 무엇을 버리고 무엇을 남겨야 하는지를 정리한 실전 초안이다.
독립성 없는 코드는 asmdef 분할 이전에 이미 구조적으로 불안한 코드다.

한 줄 요약

asmdef는 성능 최적화 버튼이 아니라, 아키텍처 품질 검사기다.
분할이 안 된다면 asmdef 문제가 아니라 의존성 설계 문제다.
단방향 참조 제약은 불편하지만, 그 덕분에 인터페이스/이벤트/레지스트리 같은 건강한 우회 패턴이 강제된다.

왜 분할이 막히는가 : 독립성 붕괴 징후

징후	실제로 벌어지는 일	결과
기능 경계 침범	한 클래스가 UI, 데이터, 게임로직, 네트워크까지 동시에 만짐	컴파일 의존성 폭증
양방향 호출 습관	A가 B를 알고, B도 A를 직접 참조	asmdef 단방향 참조와 충돌
전역 싱글톤 남용	어디서나 접근 가능한 매니저가 서로 뒤엉킴	테스트/교체/분리 불가
DTO에 로직 침투	데이터 컨테이너가 서비스 호출까지 수행	Data asmdef 독립성 붕괴

"이건 편해서 넣었다"는 이유로 참조를 추가했다면, 거의 항상 기술부채이다.
asmdef 그래프를 그렸을 때 화살표가 복잡해지는 순간, 코드 책임이 잘못 배치된 것이다.

정의해본 asmdef 범주

asmdef	책임(해야 할 일)	금지(하면 안 되는 일)
Hong.Core	공통 유틸, 도메인 공통 인터페이스, 이벤트 계약	UI/씬 전용 로직 직접 참조
Hong.Data	순수 데이터 컨테이너, 직렬화 모델	Unity 컴포넌트/서비스 직접 호출
Hong.*(Feature)	기능별 유스케이스/오케스트레이션	Feature 간 순환 참조
Hong.Presentation	View, Presenter/Controller, 사용자 입력 연결	Data 레이어 내부 구현 침투
Hong.Backend	네트워크 구현체	상위 레이어 역참조

개인적으로 그려본 asmdef 그래프

단방향 참조를 우회하는 3가지 패턴

1) 하위 공용 어셈블리에 인터페이스를 두는 방식

구현은 상위에, 계약(인터페이스)은 하위에 둔다.
상위 기능은 하위 계약만 바라본다.
두 기능을 연결해주는 과정이 필요하다.

namespace Hong.Core.Contracts {
    public interface IGoldService {
        public int CurrentGold { get; }
        public bool TrySpend(int amount);
    }
}

Hong.Core
  - IGoldService
Hong.A
  - AManager (IGoldService를 사용)
Hong.B
  - BManager : IGoldService

2) 공통 이벤트(메시지) 기반 호출

직접 참조 대신 이벤트를 발행/구독한다.
호출 대상 존재 여부를 몰라도 동작하므로 결합도를 낮춘다.

using System;

namespace Hong.Core.Events {
    public sealed class GameEventBus {
        Action<int> goldChanged;
        public void PublishGoldChanged(int value) => goldChanged?.Invoke(value);
        public void SubscribeGoldChanged(Action<int> handler) => goldChanged += handler;
        public void UnsubscribeGoldChanged(Action<int> handler) => goldChanged -= handler;
    }
}

3) Registry/Locator로 런타임 연결

컴파일 타임 참조를 줄이고 런타임에 구현체를 바인딩한다.
단, 무분별한 서비스 로케이터 남용은 또 다른 전역 의존성이 된다.

using System;
using System.Collections.Generic;

namespace Hong.Core.Runtime {
    public static class ServiceRegistry {
        static readonly Dictionary<Type, object> map = new Dictionary<Type, object>();

        public static void Register<T>(T service) where T : class {
            var key = typeof(T);
            map[key] = service;
        }

        public static bool TryResolve<T>(out T service) where T : class {
            var key = typeof(T);
            if (map.TryGetValue(key, out var value) == false) {
                service = null;
                return false;
            }

            service = value as T;
            return service != null;
        }
    }
}

예제) "상점 구매" 흐름을 asmdef 친화적으로 나누기

A. 분할 전(문제 구조)

ShopUI가 InventoryManager, SaveManager, NetworkManager, PlayerController를 직접 호출.
- 결과 : UI asmdef가 거의 모든 asmdef를 참조하게 됨.

B. 분할 후(개선 구조)

Hong.Core.Contracts  <- 인터페이스/이벤트 계약
Hong.Data            <- ItemData, WalletData (순수 데이터)
Hong.Shop    		<- ShopPurchaseUseCase
Hong.Presentation    <- ShopViewPresenter
Hong.Infrastructure  <- WalletService, SaveRepository 구현

C. 의존성 방향 표

From	To	이유
Presentation	Core.Contracts, Feature.Shop	입력 전달/결과 표시
Feature.Shop	Core.Contracts, Data	유스케이스 수행
Infrastructure	Core.Contracts, Data	계약 구현/저장
Data	(없음)	순수 컨테이너 유지

D. 핵심 유스케이스 예시 코드

아래 코드는 "UI는 유스케이스만 호출"하고, "유스케이스는 계약만 의존"하도록 만든 최소 형태다.

using Hong.Core.Contracts;
using Hong.Data;

namespace Hong.Feature.Shop {
    public sealed class ShopPurchaseUseCase {
        readonly IGoldService goldService;
        readonly IInventoryService inventoryService;

        public ShopPurchaseUseCase(IGoldService goldService, IInventoryService inventoryService) {
            this.goldService = goldService;
            this.inventoryService = inventoryService;
        }

        public PurchaseResult Purchase(ItemData item) {
            if (item == null) return PurchaseResult.Fail("Item is null");
            if (goldService.TrySpend(item.Price) == false) return PurchaseResult.Fail("Not enough gold");

            inventoryService.Add(item.Id, 1);
            return PurchaseResult.Success();
        }
    }
}

실무 체크리스트

Data asmdef에 UnityEngine 참조가 없는가?
Feature 계층이 UI 타입(MonoBehaviour, TMP_Text 등)을 모르는가?
한 asmdef의 public API가 다른 asmdef 내부 구현 클래스를 노출하지 않는가?
순환 참조를 인터페이스/이벤트/레지스트리로 해소했는가?
"편의상" 추가한 참조를 근거와 함께 설명할 수 있는가?

회고

독립성을 지키지 않으면 asmdef 분할은 사실상 불가능하다.
- 설계가 먼저고, asmdef는 그 결과를 검증하는 도구다.
asmdef 분할은 기존 코드의 책임을 다시 묻게 만든다.
- Core/Data/Feature 경계를 재정의하면서 불필요한 결합을 발견하게 된다.
단방향 참조 제약은 귀찮지만, 결국 구조를 건강하게 만든다.
- 인터페이스, 이벤트, 레지스트리 패턴은 선택이 아니라 필수에 가깝다.

마무리

"asmdef를 나눴더니 빌드가 빨라졌다"는 결과는 부수효과
진짜 성과는 코드가 자기 책임을 지키도록 강제된 것
분할 경험은, 결국 아키텍처는 기술이 아니라 습관

[Architech] 유니티로 배우는 MVC

HONGGG — Mon, 1 Dec 2025 13:56:44 +0900

Unity MVC 패턴 예제 – Player Health System

학습 목적

Unity에서도 Model / View / Controller 를 명확히 분리할 수 있음을 이해한다.
유지보수성과 확장성이 높은 구조를 경험한다.
순수 C# 로직(Model) 과 Unity 엔진 요소(View) 의 역할 차이를 체험한다.
UI 변경이 로직에 영향을 주지 않는 구조를 설계한다.

MVC 핵심 개념 설명

MVC 패턴이란 무엇인가?

MVC(Model–View–Controller) 패턴은 소프트웨어를 구성할 때, 데이터(Model), 화면(View), 흐름 제어(Controller) 를 명확하게 분리하여 유지보수성을 높이고 확장성을 확보하는 대표적인 아키텍처 패턴이다.

Unity는 구조상 “MonoBehaviour 안에 모든 로직이 섞이는” 형태가 되기 쉽다.

그렇기 때문에 MVC를 의도적으로 적용하면 UI와 게임 로직의 결합을 최소화할 수 있고, 변경이 잦은 부분(UX/UI)과 안정적이어야 하는 부분(로직)을 분리할 수 있다는 장점이 있다.

MVC를 나누는 이유

게임과 UI 개발은 다음과 같은 문제가 자주 발생한다.

UI가 바뀌면 게임 로직 코드도 함께 수정해야 한다.
로직에 버그가 있어도 UI가 섞여 있어 디버깅이 어렵다.
단위 테스트 작성이 불가능하다.
여러 시스템이 하나의 클래스에서 서로 참조하며 높은 결합도가 생긴다.

MVC는 이를 해결하기 위해 다음과 같은 목표를 갖는다.

관심사 분리(SoC: Separation of Concerns)
- "데이터는 Model이 책임진다"
- "표시는 View가 책임진다"
- "흐름 제어는 Controller가 책임진다"
UI 변경이 로직에 영향을 주지 않는 구조
로직을 테스트 가능한 형태로 격리
클래스 책임이 명확해져 유지보수성이 크게 향상

MVC 구성 요소

Model

“데이터와 규칙”

캐릭터 체력, 공격력 같은 데이터
데미지 계산 같은 비즈니스 로직
체력이 변하면 이벤트(Action) 으로 외부에 알림

특징

UnityEngine API를 사용하지 않음
순수 C# 로직
View나 Controller를 모름 (완전 독립적)

View

“화면 표시 전담”

UI 요소(Text, Slider, Image 등)를 화면에 보여줌
Model로부터 전달된 데이터를 시각적으로 표현
로직 계산은 절대 하지 않음

특징

MonoBehaviour 기반
UI 변경만 담당
Model·Controller 로직을 알 필요 없음
View는 UI가 변경될 때에도 Model이나 Controller 수정 없이 교체가 가능해진다.

Controller

“입력과 흐름 제어 담당”

입력 처리
Model 변경 → 이벤트 수신 → View 갱신
전체 흐름을 제어

특징

View와 Model 간의 직접 연결을 관리
게임 동작 전체의 orchestration 담당
UI와 로직을 이어주는 Glue Layer

MVC 데이터 흐름

입력(Input)
     ↓
Controller
     ↓
Model (상태 변경)
     ↓ 이벤트 발생
Controller (이벤트 수신)
     ↓
View (UI 갱신)

MVC는 이 구조 덕분에 다음과 같은 이점이 생긴다.

입력 방식을 바꿔도 모델은 그대로 유지
UI 스킨을 교체해도 로직은 그대로 유지
Controller가 연결체계를 변경해도 각 레이어는 독립적으로 유지

장단점

장점	설명
구조가 단순하고 초기 구축이 빠르다	UI가 몇 개 없고 로직이 단순한 프로젝트에서는 MVC가 매우 빠르게 적용된다.
View 로직이 Controller에 몰림 (초기 학습곡선 낮음)	<입력 → Controller → Model → View> 이 구조만 이해하면 빠르게 개발할 수 있다.
Unity의 전통적 개발 방식과 어울림	MonoBehaviour 안에 “입력 처리 + 로직 + UI 업데이트”가 섞이는 기본 Unity 스타일과 유사하다.
아주 작은 게임, UI가 적은 프로젝트에 최적	간단한 미니게임 1~2개의 UI만 있는 간단한 프로토타입 System 구조가 없는 개발 방식

단점	설명
프로젝트 규모가 조금만 커져도 Controller가 비대해진다	Controller가 다음 <입력, 로직 호출, 모듈 변경/관리, 뷰 업데이트, 여러 UI 동기화> 전부 처리하게 됨
UI가 늘어날수록 로직 변경 비용이 폭증	Controller가 View를 직접 갱신하므로 UI가 여러 개일 때 깊이 결합되고 UI 교체 시 Controller를 반드시 수정해야 함
Model은 재사용하기 어렵고, 테스트하기 매우 어렵다	Controller에 Model 흐름이 박혀 있음 UI가 없어도 Model을 테스트하기 어려움 UI 구조가 바뀌면 Model/Controller가 줄줄이 바뀜

실행 방법

Canvas 아래에 Text + Slider 생성
PlayerHealthView 를 추가하고 Text/Slider 연결
빈 GameObject → PlayerHealthController 추가
View 레퍼런스를 Drag & Drop
인풋매니저(신버젼 커스텀 설정 필요)에서 각 Damage/Heal이 동작할 키를 바인드
실행:
- Down/S → 데미지
- Up/W → 회복

컨트롤러

using UnityEngine;
using UnityEngine.Assertions;
using UnityEngine.InputSystem;
using HUtil.Logger;
using HUtil.Inspector;

namespace SWU.Architech.MVC {
    public class MvcHealthController : MonoBehaviour {
        #region 필드
        [HTitle("Input")]
        [SerializeField]
        InputActionReference damageAction;
        [SerializeField]
        InputActionReference healAction;

        [HTitle("View Reference")]
        [SerializeField]
        MvcHealthView view;

        [HTitle("초기 체력 설정")]
        [SerializeField]
        int maxHealth = 100;

        [HTitle("테스트용 데미지/회복 값")]
        [SerializeField]
        int damagePerHit = 10;
        [SerializeField]
        int healPerKey = 5;

        MvcHealthModel model;
        #endregion

        #region 프로퍼티
        public MvcHealthModel Model => model;
        private InputAction _DamageAction => damageAction != null ? damageAction.action : null;
        private InputAction _HealAction => healAction != null ? healAction.action : null;
        #endregion

        #region 생성자 / 초기화 함수
        private void _Initialize() {
            if (maxHealth <= 0) maxHealth = 1;

            model = new MvcHealthModel(maxHealth);
            model.OnHealthChanged += _OnHealthChanged;
            model.OnDead += _OnDead;

            if (view != null) view.Initialize(model.Current, model.Max);
        }

        private void _RegisterInput() {
            if (_DamageAction != null) {
                _DamageAction.performed += _OnDamagePerformed;
                _DamageAction.Enable();
            }

            if (_HealAction != null) {
                _HealAction.performed += _OnHealPerformed;
                _HealAction.Enable();
            }
        }

       private void _UnregisterInput() {
            if (_DamageAction != null) {
                _DamageAction.performed -= _OnDamagePerformed;
                _DamageAction.Disable();
            }

            if (_HealAction != null) {
                _HealAction.performed -= _OnHealPerformed;
                _HealAction.Disable();
            }
        }
        #endregion

        #region 유니티 라이프 사이클 함수
        private void Awake() {
            _Initialize();
        }

        private void OnEnable() {
            _RegisterInput();
        }

        private void OnDisable() {
            _UnregisterInput();
        }
        #endregion

        #region 멤버 함수
        public void ApplyDamage(int amount) {
            Assert.IsNotNull(model, "Model shouldn't be null");
            model.Damage(amount);
        }

        public void ApplyHeal(int amount) {
            Assert.IsNotNull(model, "Model shouldn't be null");
            model.Heal(amount);
        }

        private void _OnDamagePerformed(InputAction.CallbackContext context) {
            if (!context.performed) return;
            ApplyDamage(damagePerHit);
        }

        private void _OnHealPerformed(InputAction.CallbackContext context) {
            if (!context.performed) return;
            ApplyHeal(healPerKey);
        }

        private void _OnHealthChanged(int current, int max) {
            Assert.IsNotNull(view, "view shouldn't be null");
            view.UpdateHealth(current, max);
        }

        private void _OnDead() {
            HLogger.Log("[MvcHealthController] MvcHealthView Dead");
        }
        #endregion

        #region 디버깅 변수 / 함수
    #if UNITY_EDITOR
        [ContextMenu("Test Damage")]
        public void TestDamage() {
            ApplyDamage(damagePerHit);
        }

        [ContextMenu("Test Heal")]
        public void TestHeal() {
            ApplyHeal(healPerKey);
        }
    #endif
        #endregion
    }
}

뷰

#if UNITY_EDITOR
/*
 * View는 “데이터가 주어졌을 때 어떻게 그릴지만” 알고 있음.
 * Model/Controller 로직은 전혀 모름 → 교체/디자인 변경이 쉬움.
 */
#endif

using UnityEngine;
using UnityEngine.UI;
using TMPro;
using HUtil.Logger;

namespace SWU.Architech.MVC {
    public class MvcHealthView : MonoBehaviour {
        #region 유니티 IMGUI 멤버 변수
        [SerializeField]
        TMP_Text healthText;
        [SerializeField]
        Slider healthSlider;
        #endregion

        #region 프로퍼티
        public TMP_Text HealthText => healthText;
        public Slider HealthSlider => healthSlider;
        #endregion

        #region 생성자 / 초기화 함수
        public void Initialize(int current, int max) {
            _UpdateHealthUi(current, max);
        }
        #endregion

        #region 멤버 함수
        public void UpdateHealth(int current, int max) {
            _UpdateHealthUi(current, max);
        }

        private void _UpdateHealthUi(int current, int max) {
            if (healthText != null) healthText.text = $"{current} / {max}";
            if (healthSlider != null) {
                healthSlider.maxValue = max;
                healthSlider.value = current;
            }
        }
        #endregion

        #region 디버깅 변수 / 함수
#if UNITY_EDITOR
        [ContextMenu("Log Current Health UI")]
        public void LogCurrentHealthUi() {
            HLogger.Log($"[MvcHealthView] text={healthText?.text}, slider={healthSlider?.value}");
        }
#endif
        #endregion
    }
}

모델

using System;

namespace SWU.Architech.MVC {
    public class MvcHealthModel {
        #region 프로퍼티
        public int Current { get; private set; }
        public int Max { get; private set; }
        #endregion

        #region 이벤트 대리자
        public Action<int, int> OnHealthChanged;
        public Action OnDead;
        #endregion

        #region 생성자 / 초기화 함수
        public MvcHealthModel(int max) {
            if (max <= 0) max = 1;
            Max = max;
            Current = max;
        }
        #endregion

        #region 멤버 함수
        public void Damage(int amount) {
            if (amount <= 0) return;

            int next = Math.Max(0, Current - amount);
            if (next == Current) return;

            Current = next;
            OnHealthChanged?.Invoke(Current, Max);

            if (Current <= 0) OnDead?.Invoke();
        }

        public void Heal(int amount) {
            if (amount <= 0) return;

            int next = Math.Min(Max, Current + amount);
            if (next == Current) return;

            Current = next;
            OnHealthChanged?.Invoke(Current, Max);
        }
        #endregion
    }
}

[Git] 서브모듈 적용법

HONGGG — Fri, 28 Nov 2025 19:20:18 +0900

Unity 프로젝트에 Git Submodule 기반 UPM 패키지를 적용하는 방법

Unity에서 공용 유틸 패키지나 엔진 확장 기능을 여러 프로젝트에서 공유하려면, 단순히 파일을 복사하는 방식으로는 버전 관리가 유지되지 않는다.

이 문제를 해결하기 위한 방법이 Git Submodule + Unity Local UPM 패키지 조합이다.

이번 글에서는 다음과 같은 사례를 기반으로 진행한다.

상위 프로젝트 : TestProject
- 하위 공용 레포 : HCUP-Unity
  - 레포에 포함된 3개의 UPM 패키지 : HGame, HUI, HUtil

TestProject/
└── Assets/
└── HCUP-Unity/
     └── HoHong123/
         ├── HGame/
         ├── HUI/
         └── HUtil/

아래 단계에 따라 진행하면, 여러 Unity 프로젝트에서 하나의 공용 패키지를 버전별로 안정적으로 관리하는 구조를 갖출 수 있다.

Submodule로 공용 레포 추가하기

원하는 버전의 레포를 Submodule로 가져온다.

서브모듈 호출

git submodule add https://github.com/HoHong123/HCUP-Unity.git HCUP-Unity

추가 후 버전을 고정한다.

브랜치 변경 → 버전 변경

cd HCUP-Unity
git fetch --tags
git checkout v0.2.1
cd ..

마지막으로 상위 레포에 커밋한다.

푸시

git add .gitmodules HCUP-Unity
git commit -m "Add HCUP-Unity as submodule at v0.2.1"
git push

Submodule 도입은 여기까지로 완료된다.

이제 Unity가 실제 패키지를 읽을 수 있도록 연결하는 작업이 필요하다.

Unity에서 Submodule 패키지 인식시키기

Unity는 Assets/ 폴더만 컴파일하는 것이 아니다.

Packages/ 아래에 위치한 UPM 패키지도 모두 자동 컴파일된다.

하지만 Unity가 “이 경로가 패키지다”라고 인식하기 위해서는 반드시 Packages/manifest.json에 선언을 해 주어야 한다.
이번 사례에서는 Submodule 내부에 3개의 패키지가 존재한다.

HCUP-Unity/
 └── HoHong123/
     ├── HGame/
     │   └── package.json
     ├── HUI/
     │   └── package.json
     └── HUtil/
         └── package.json

각 패키지 루트에는 package.json이 존재하며, 그 "name" 필드가 패키지의 ID 역할을 한다.

예시(HUtil):

{
  "name": "com.hohong123.hutil",
  "displayName": "Hohong123 HUtil",
  "version": "0.2.1",
  "unity": "2021.3"
}

manifest.json에 패키지 경로 등록

프로젝트/Packages/manifest.json을 열고 dependencies에 다음을 추가한다:

"com.hohong123.hgame": "file:../HCUP-Unity/HoHong123/HGame",
"com.hohong123.hui":   "file:../HCUP-Unity/HoHong123/HUI",
"com.hohong123.hutil": "file:../HCUP-Unity/HoHong123/HUtil"

중요:
manifest.json의 key는 package.json의 "name"과 반드시 완전히 일치해야 한다.
하나라도 다르면 Unity는 패키지를 불러올 수 없다.

패키지 로딩이 안 되면 대부분은 다음 중 하나이다.

manifest.json 저장 안 함
쉼표(,) 누락 또는 문법 에러
"name" 불일치
경로 오타 (HoHong123 / hutil 등)

Unity에서 패키지 로딩 확인하기

Unity를 다시 열거나 Package Manager를 열고 다음 위치에서 확인한다:

Window → Package Manager → Packages: In Project

Hohong123 HGame
Hohong123 HUI
Hohong123 HUtil

이 모두 뜨면 정상적으로 패키지가 인식된 것이다.

패키지가 뜨는 순간, 내부 C#은 자동으로 컴파일되고 네임스페이스로 조할 수 있다.

(단, Editor 전용 asmdef → Runtime 참조 불가 같은 Unity 규칙은 그대로 적용된다.)

현재 방식의 장점

1) 버전 고정이 가능하다

서브모듈은 특정 태그 또는 커밋에 고정할 수 있으므로 “패키지가 갑자기 깨지는” 상황을 방지할 수 있다.

2) 여러 프로젝트에서 동일 버전을 안정적으로 공유

프로젝트 A, B, C가 모두 v0.2.1 같은 동일 버전을 사용 가능.

3) 디렉토리 복사 없이 즉시 패키지 업데이트 가능

하위 레포에 새로운 버전을 생성하면:

cd HCUP-Unity
git fetch
git checkout v0.2.2

이렇게만 하면 상위 프로젝트의 패키지가 자동으로 업데이트된다.

4) Unity의 UPM 시스템을 그대로 활용

패키지 구조, asmdef 분리, Editor/Runtime 구성, 의존성 관리 등 Unity 표준 방식으로 유지된다.

Submodule 제거하기

Submodule을 잘못 추가하거나 충돌이 발생하면 .gitmodules, .git/modules/, 워킹트리 등 여러 곳에 잔여물이 남는다.

아래 명령으로 기존 흔적을 정리한다.

git rm -r HCUP-Unity          # 기존 폴더 제거
rm -rf .git/modules/HCUP-Unity

그리고 .gitmodules 파일을 열어 HCUP-Unity 관련 섹션이 있다면 삭제한다.

이 단계까지 마치면 상위 레포는 HCUP-Unity에 대한 어떠한 참조도 없는 “깨끗한 상태”가 된다.

Submodule 공유하기

팀작업을 한다면 서브모듈을 업데이트하는 것으로 끝나지 않는다.

깃레포에 서브모듈을 올려놓아도 이를 다른사람이 클론(Clone)하거나 풀(Pull)하면 서브모듈을 가져오는 것이 아닌, 해당 모듈을 다운받을 수 있는 링크가 .gitmodules에 등록되어 있는 상태가 된다.

즉, 프로젝트를 받은 사람이 서브모듈을 사용하기 위해서는 다음 과정이 추가적으로 필요하다.

# 처음 받는 경우(Clone) 1
git clone --recurse-submodules <repo-url>

# 처음 받는 경우(Clone) 2
git clone <repo-url>
git submodule update --init --recursive

# 업데이트 받을 때(Pull)
git pull
git submodule update --init --recursive

[Unity] 토스앱 빌드 (WebGL)

HONGGG — Tue, 18 Nov 2025 18:02:56 +0900

토스앱 빌드 과정 정리

토스 미니앱(Toss MiniApp)에 Unity WebGL 게임을 올리기

토스 미니앱(Toss MiniApp) 환경에 Unity WebGL 게임을 올리고, 모바일 환경에서 부드럽게 동작하도록 만드는 과정은 단순한 웹 배포보다 훨씬 까다롭다. 토스는 브라우저가 아닌 WebView + React Native 기반의 독립 실행 환경을 사용한다.

Unity 게임을 바로 WebGL로 빌드하면 토스 앱에 그대로 넣을 수 없다. 필요한 작업은 다음과 같다.

프로젝트 빌드

1. Unity 빌드 설정

Unity → Project Settings → Player → WebGL

프로젝트 세팅에 따라 WebGL 빌드 패키지를 다운받아야할 수도 있다.

2. WebGL 빌드에서 설정값을 변경해야한다.

Edit > Project Settings > Player > Publishing Settings

Compression Format : Disabled로 설정 (관련 포스트)
- 토스 WebView는 Brotli/Gzip 압축을 잘 지원하지 않음.
WebGL Memory Size 넉넉하게 설정

3. 빌드하기

File > Build Settings > Build

빌드 파일을 확인하여 빌드파일 내부 버전 확인 및 압축 확장자 확인.
- 필요에 따라 WebGLTemplate을 통해 개발자가 커스텀 빌드 세팅을 사용할 수 있다.

4. React 프로젝트 생성

1) VS Code로 신규 프로젝트 파일을 생성한다.

튜토리얼에는 스캐폴딩과 다양한 플러그인을 활용한 프로젝트 세팅부터 시작한다.

필요에 따라 바로 프로젝트를 만들수도 있다.

본인이 사용하는 패키지 매니저를 활용하여 프로젝트를 만든다.

프로젝트 생성

# npm
npm create vite unity-webgl-wrapper --template react-ts
# yarn
yarn create vite unity-webgl-wrapper --template react-ts

사용하는 패키지 매니저에 따라서 첫 생성시 선택하는 옵션의 수가 다를 수 있다. 별로 크게 중요한건 없다.

npm을 통한 생성

yarn을 통한 생성

위 과정을 통해 프로젝트 생성이 완료된다면 기본 리액트 프로젝트가 생성된다.

2) 프로젝트 디렉토리

생성한 프로젝트 디렉토리로 이동하여 토스앱 관련 패키지를 설치한다.

cd 프로젝트파일

패키지 다운로드

# npm
npm install @apps-in-toss/framework
# yarn
yarn add @apps-in-toss/framework

* VC 세팅에 따라 추가적인 플러그인 설치가 필요할 수 있습니다.

3) WebGL 빌드파일 전달

유니티에서 빌드한 WebGL 빌드파일 내부의 모든 값을 'root > public > unity' 디렉토리를 생성하여 넣는다.

5. Build - 번들 파일 생성하기

번들 파일은 .ait 확장자를 가진 파일을 의미하며 빌드된 프로젝트를 패키징한 결과물이다.

빌드는 다음 명령어를 사용한다.

# npm
npm run build
# yarn
yarn build

빌드 가이드

토스앱 게임 업로드에는 몇가지 규칙이 존재한다.

앱인토스 개발자센터

developers-apps-in-toss.toss.im

게임 미니앱은 다크모드(Inverted) 설정을 권장
- 말이 권장이지 다크모드가 아니면 출시 검토에서 걸린다.
앱 진입에 이름, 로고, 대표 색상 정상 동작 유무
토스 로그인 사용시, 즉시 로그인 유도 불가
과도한 로딩시간 불가
연령 등급 표기 필수
- 타 플렛폼에서 프로토타입 검수 후 받은 연령 등급 표기를 사용할 수 있다.
게임센터 적용시 정상 동작 확인 필수
게임의 각종 사운드가 앱이 비활성화된 상태에서는 플레이되지 않도록 설정
내비게이션바 사용 필수

대략적으로 중요한 것들은 위와 같다.

사용 파일

수정사항이 존재하는 파일들 위주로 작성.

App.css

#root {
  max-width: 1280px;
  margin: 0 auto;
  padding: 2rem;
  text-align: center;
}

.logo {
  height: 6em;
  padding: 1.5em;
  will-change: filter;
  transition: filter 300ms;
}
.logo:hover {
  filter: drop-shadow(0 0 2em #646cffaa);
}
.logo.react:hover {
  filter: drop-shadow(0 0 2em #61dafbaa);
}

@keyframes logo-spin {
  from {
    transform: rotate(0deg);
  }
  to {
    transform: rotate(360deg);
  }
}

@media (prefers-reduced-motion: no-preference) {
  a:nth-of-type(2) .logo {
    animation: logo-spin infinite 20s linear;
  }
}

.card {
  padding: 2em;
}

.read-the-docs {
  color: #888;
}

App.tsx

import './App.css'
import UnityCanvas from './UnityCanvas.tsx';
import { useEffect } from 'react';

declare global {
  interface Window {
    unityInstance?: any;
  }
}

function App() {
  useEffect(() => {
    const handler = () => {
      if (!window.unityInstance) return;
      const isVisible = !document.hidden;
      window.unityInstance.SendMessage(
        '[BM] WebReceiver',
        'ReceiveString',
        isVisible.toString(), // "true" / "false"
      );
    };

    // 리스너 등록
    document.addEventListener('visibilitychange', handler);
    // 필요하다면 최초 상태도 한 번 Unity에 알려주고 싶으면
    handler();
    // 언마운트 시 정리
    return () => { document.removeEventListener('visibilitychange', handler);};
  }, []);

  return (
    <div style={{
      position: 'fixed',
      inset: 0,
      display: 'grid',
      placeItems: 'center',
      background: '#000'
    }}>
      <div style={{
        width: 'min(100vw, calc(100vh * 9 / 16))',
        height: 'min(100vh, calc(100vw * 16 / 9))',
        aspectRatio: '9 / 16'
      }}>
        <UnityCanvas/>
      </div>
    </div>
  );
}

export default App;

index.css

:root {
  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
  line-height: 1.5;
  font-weight: 400;

  color-scheme: light dark;
  color: rgba(255, 255, 255, 0.87);
  background-color: #242424;

  font-synthesis: none;
  text-rendering: optimizeLegibility;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

a {
  font-weight: 500;
  color: #646cff;
  text-decoration: inherit;
}
a:hover {
  color: #535bf2;
}

body {
  margin: 0;
  min-width: 320px;
  min-height: 100vh;
}

h1 {
  font-size: 3.2em;
  line-height: 1.1;
}

button {
  border-radius: 8px;
  border: 1px solid transparent;
  padding: 0.6em 1.2em;
  font-size: 1em;
  font-weight: 500;
  font-family: inherit;
  background-color: #1a1a1a;
  cursor: pointer;
  transition: border-color 0.25s;
}
button:hover {
  border-color: #646cff;
}
button:focus,
button:focus-visible {
  outline: 4px auto -webkit-focus-ring-color;
}

@media (prefers-color-scheme: light) {
  :root {
    color: #213547;
    background-color: #ffffff;
  }
  a:hover {
    color: #747bff;
  }
  button {
    background-color: #f9f9f9;
  }
}

UnityCanvas.tsx

import { useEffect } from 'react';

declare global {
  interface Window {
    createUnityInstance: (
      canvas: HTMLCanvasElement,
      config: Record<string, unknown>
    ) => Promise<unknown>;
  }
}

const UnityCanvas = () => {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = '/unity/Build/{{{BUILD_LOADER}}}.loader.js';

    script.onload = () => {
      const canvas = document.createElement('canvas');
      canvas.id = 'unity-canvas';
      canvas.style.width = '100%';
      canvas.style.height = '100%';

      const container = document.getElementById('unity-container');
      if (!container) return;
      container.appendChild(canvas);

      window.createUnityInstance(canvas, {
          dataUrl: '/unity/Build/{{{BUILD_DATA}}}.data',
          frameworkUrl: '/unity/Build/{{{BUILD_FRAMEWORK}}}.framework.js',
          codeUrl: '/unity/Build/{{{BUILD_CODE}}}.wasm',
          streamingAssetsUrl: '/unity/StreamingAssets',
          companyName: 'Company',
          productName: 'Game Name',
          productVersion: '0.1',
        })
        .then((instance: any) => {
          window.unityInstance = instance;
        })
        .catch((err: any) => {
          console.error('Unity 인스턴스 생성 실패:', err);
        });
    };

    document.body.appendChild(script);

    return () => {
      document.removeEventListener('visibilitychange', () => {});
      document.body.removeChild(script);
    };
  }, []);

  return (
    <div
      id="unity-container"
      style={{ width: '100vw', height: '100vh', background: '#000' }}
    ></div>
  );
};

export default UnityCanvas;

tsconfig.app.json

  "include": ["src/**/*.tsx"]

백그라운드 사운드 이슈

토스앱을 모바일에서 숨김으로 설정할때, WebGL이 백그라운드에서 계속 실행되어 BGM이 앱을 닫은 상태에서도 지속 플레이되는 이슈가 있었다.

앱실행
무한반복 배경음 실행
앱 숨김
배경음 지속 재생

토스앱 자체가 웹뷰에 WebGL을 올린 것이기에 JS를 통한 통신으로 처리해야 한다.

이는 리액트 프로젝트에서 앱의 가시성(Visibility)가 변화할때마다 UnityCanvas.tsx에 설정된 unityInstance 내부에 <특정 게임오브젝트 + 해당 오브젝트가 가진 스크립트 컴포넌트의 public 함수 + 보낼 문자열> 형태로 전달된다.

유니티 웹메시지 리시버 설정

우선 다음은 예시 코드들이기에 JS 통신규약이라는 정의 자체가 없다.
실사용시 이에 대한 추가적인 규칙을 정하고 JS통신은 최소화하는 방향으로 개발하는 것이 옳다.

우선 언제든 웹의 메시지를 받을 수 있는 싱글톤 매니저를 생성

namespace Util.Web {
    public class WebExternalReceiverManager : SingletonBehaviour<WebExternalReceiverManager> {
        [UnityEngine.SerializeField]
        BaseExternalReceiver[] receivers;

        public event System.Action OnReceiveMessage;
        public event System.Action<string> OnReceiveString;

        public void ReceiveMessage() => OnReceiveMessage?.Invoke();
        public void ReceiveString(string message) => OnReceiveString?.Invoke(message);


        private void Start() {
            foreach (var reciver in receivers) {
                Register(reciver);
            }
        }

        private void OnDestroy() {
            foreach (var reciver in receivers) {
                Unregister(reciver);
            }
        }


        public void Register(IWebReceiver receiver) {
            Unregister(receiver);
            OnReceiveMessage += receiver.ReceiveMessage;
            OnReceiveString += receiver.ReceiveString;
        }

        public void Unregister(IWebReceiver receiver) {
            OnReceiveMessage -= receiver.ReceiveMessage;
            OnReceiveString -= receiver.ReceiveString;
        }
    }
}

매니저에서 메시지를 수신 받으면 각자의 기능을 동작하는 에이전트 클래스 생성
- 확장성을 위한 인터페이스
- 공통 함수를 모은 부모클래스
- 이벤트가 활성화되면 각자 할일을 하는 파생클래스들...

using UnityEngine;
using Util.Sound;
using Util.Web;

namespace Util.Web {
    public interface IWebReceiver {
        void ReceiveMessage();
        void ReceiveString(string message);
    }
}

namespace Util.Web {
    public class BaseExternalReceiver : MonoBehaviour, IWebReceiver {
        public virtual void ReceiveMessage() {}
        public virtual void ReceiveString(string message) {}
    }
}

namespace MA.Web {
    public class WebVisibilityReceiver : BaseExternalReceiver {
        private void Start() => WebExternalReceiverManager.Instance.Register(this);
        private void OnDestroy() => WebExternalReceiverManager.Instance.Unregister(this);

        #region BGM Control
        public override void ReceiveString(string boolean) {
            if (!bool.TryParse(boolean, out bool isVisible)) return;
            var sound = SoundManager.Instance;
            if (isVisible) {
                sound.ResumeBGM();
            }
            else {
                sound.PauseBGM();
            }
        }
        #endregion
    }
}

위와 같이 적용하면 유니티 IMGUI, 에디터, 코드 등 다양한 방식으로 웹메시지 핸들링이 가능하게 된다.

RN 설정

이제 유니티 WebGL에 메시지를 전달하는 이벤트를 등록해야 한다.

이를 위하여, App.tsx에서 useEffect를 사용하여 핸들러를 생성하고 이를 현재 앱에 리스너로 등록하는 방식을 사용한다.

App.tsx

import './App.css'
import UnityCanvas from './UnityCanvas.tsx';
import { useEffect } from 'react';

declare global {
  interface Window {
    unityInstance?: any;
  }
}

function App() {
  useEffect(() => {
    const handler = () => {
      if (!window.unityInstance) return;
      const isVisible = !document.hidden;
      window.unityInstance.SendMessage(
        '[BM] WebReceiver',
        'ReceiveString',
        isVisible.toString(), // "true" / "false"
      );
    };

    // 리스너 등록
    document.addEventListener('visibilitychange', handler);
    // 필요하다면 최초 상태도 한 번 Unity에 알려주고 싶으면
    handler();
    // 언마운트 시 정리
    return () => { document.removeEventListener('visibilitychange', handler);};
  }, []);

  return (
    <div style={{
      position: 'fixed',
      inset: 0,
      display: 'grid',
      placeItems: 'center',
      background: '#000'
    }}>
      <div style={{
        width: 'min(100vw, calc(100vh * 9 / 16))',
        height: 'min(100vh, calc(100vw * 16 / 9))',
        aspectRatio: '9 / 16'
      }}>
        <UnityCanvas/>
      </div>
    </div>
  );
}

export default App;

사운드 컨트롤

해당 이슈에서 시도해본 해결방안들은 다음과 같다.

오디오소스들 볼륨 최소화
오디오소스들 데시벨 최소화
오디오소스들 Pause/Unpause

이 과정에서 볼륨 및 데시벨과 같은 각 컴포넌트의 변수값 설정 변경은 Visibility 변경으로 설정이 변경되지 않는 이슈가 있었다.

단, 오디오소스 자체를 Pause/Unpause하는 부분은 정상동작하는 것으로 확인했다.

또한, SendMessage는 문자열 값만 전달이 가능한 것으로 isVisible이 boolean이라도 string으로 파싱하여 전달한다.

참조

앱인토스 개발자센터

developers-apps-in-toss.toss.im

앱인토스 개발자센터

developers-apps-in-toss.toss.im

앱인토스 개발자센터

developers-apps-in-toss.toss.im