대규모 유니티 프로젝트에서 AI 코딩 도구 쓰는 법 — 구조, 가드레일, 검증의 세 기둥

코드가 수만 줄을 넘으면 AI 코딩 도구는 길을 잃습니다. ASMDEF와 의존성 주입으로 맥락을 좁히고, 규칙 파일로 유니티 안티 패턴을 막고, 다이어그램과 신뢰 등급으로 AI 코드를 검증하는 대규모 유니티 프로젝트용 에이전틱 워크플로를 정리했습니다.

2026년 6월 27일에버스톤12분 분량AI · 개발게임 개발 · 퍼블리싱

대규모 유니티 프로젝트에서 AI 코딩 도구 쓰는 법 — 구조, 가드레일, 검증의 세 기둥 대표 이미지

AI 코딩 도구는 작은 예제에서는 잘 작동하지만, 코드가 수만 줄을 넘는 유니티 프로젝트에서는 맥락을 놓치고 엔진 특성을 무시한 코드를 내놓기 쉽습니다. 이 자료는 해법을 구조로 맥락을 좁히고, 규칙으로 오작동을 막고, 시각화로 빠르게 검증하는 세 기둥으로 정리합니다. 개발자의 역할은 코드를 치는 사람에서 설계하고 감사하는 사람으로 옮겨 간다는 것이 결론입니다.

이 문서는 NotebookLM(노트북 LM)으로 자료를 조사해 만든 문서입니다.

대규모 프로젝트에서 AI가 실패하는 이유는 컨텍스트 한계, 정상 경로 편향, 유니티 특성 무시입니다
도구는 용도별로 나눕니다. IDE 내장형, 터미널 에이전트형, 에디터 연동형
ASMDEF와 의존성 주입으로 모듈 경계를 나누면 AI가 봐야 할 범위가 줄어듭니다
프로젝트 문서와 유니티 전용 금지 규칙을 파일로 두고, 컴파일 오류는 AI가 스스로 고치게 합니다
AI가 쓴 코드는 다이어그램으로 검토하고, 실행 이력에 따라 신뢰 등급을 올립니다

왜 큰 프로젝트에서 AI가 헤매는가

대규모 프로젝트에서 AI가 실패하는 3가지 이유 슬라이드. 오른쪽 위 데이터 포인트 — 79%의 대규모 팀이 AI로 효율성 향상을 경험하지만 46%는 AI 생성 코드의 정확도를 불신한다. 세 카드 중 Context Window 한계(엉킨 실타래 그림) — 수만 줄의 스파게티 코드에서 길을 잃고 모든 파일을 참조하려다 환각(Hallucination) 발생. Happy Path 편향(끊어진 다리 그림) — 오직 작동만 하는 튜토리얼 수준의 코드를 생성하고 예외 처리·동시성·엣지 케이스를 무시. Unity 물리적 특성 무시(부서지는 큐브 그림) — Update 내 메모리 할당으로 GC 스파이크를 유발하고 엔진 고유의 null 체크(UnityEngine.Object)를 무시

목적에 맞는 AI 에이전트 선택 전략 표. Cursor(에이전트 모드) — 인터페이스는 IDE 내장(채팅 & 인라인), 맥락 범위는 로컬 파일 및 RAG 인덱싱, 최적 사용처는 실시간 인라인 수정과 빠른 프로토타이핑. Claude Code(CLI 기반) — 터미널(자율적 도구 호출), 저장소 전체(다단계 추론), 복잡한 리팩토링과 대규모 테스트 자동화. Unity AI Gateway(MCP) — 에디터 내장 어시스턴트, 씬 계층 구조 및 에셋 메타데이터, 에셋 조작·씬 자동화·메타데이터 기반 검증

세 번째 실패 이유는 유니티 개발자라면 바로 공감할 부분입니다. 범용 C# 관점에서는 문제없어 보이는 코드도 매 프레임 실행되는 Update 안에서는 성능 문제가 되고, 파괴된 오브젝트를 일반 C# 방식으로 비교하면 의도와 다르게 동작합니다. AI는 이런 엔진 고유의 규칙을 알려 주지 않으면 지키지 않습니다. 79%, 46%는 자료 기준 수치입니다.

기둥 1 — 아키텍처로 맥락을 좁힌다

섹션 표지 슬라이드. 청록색 와이어프레임으로 그린 숫자 1 과 함께 아키텍처 설계 — 규모가 큰 프로젝트에서 AI를 사용하는 적절한 방법

맥락 깔때기(Context Funnel): ASMDEF를 통한 시야 제어 슬라이드. 왼쪽 소음 과부하(Noise Overload)는 선이 어지럽게 얽힌 거대한 단일 Assembly-CSharp.dll, 오른쪽 맥락 격리(Context Isolation)는 Core·UI·Gameplay·Audio 네 상자가 점선 화살표로 의존 방향만 이어진 모듈별로 명확히 분리된 ASMDEF. 아래 세 줄은 AI에게 전체 프로젝트를 제공하지 마라, 어셈블리 정의(ASMDEF)로 컴파일 단위와 의존성 경계를 분리, 특정 모듈 수정 시 불필요한 참조 데이터를 차단해 AI 추론 정확도 극대화

의존성 주입(DI): 스파게티 참조 끊어내기 슬라이드. 왼쪽 강결합(FindObjectOfType 호출)은 Component 와 AudioManager 가 직접 연결된 선에 빨간 X, 오른쪽 느슨한 결합(인터페이스 주입)은 Scene Installer 가 IInputProvider 와 IHealth 인터페이스에 플러그처럼 꽂히는 그림. 아래 상자에 문제 — 전역 참조(Singleton)와 Scene 검색(FindObject)은 AI의 코드 생성 시 결합도 문제를 야기, 해결 — 구체적인 클래스가 아닌 인터페이스(Interface) 단위 설계 지시, 효과 — AI가 독립적인 단위 테스트(Unit Test) 및 모킹(Mocking) 객체를 5배 빠르게 생성 가능

ASMDEF와 인터페이스 설계는 AI가 없던 시절에도 권장되던 방식입니다. 달라진 점은 사람이 읽기 좋은 구조가 AI에게도 읽기 좋다는 것이 확인되면서 도입 이유가 하나 더 생겼다는 것입니다. 모듈 경계가 분명하면 AI에게 "이 폴더만 보라"고 범위를 줄 수 있고, 인터페이스가 있으면 테스트용 가짜 객체를 만들기도 쉬워집니다. 5배라는 효과 수치는 자료 기준입니다.

기둥 2 — 가드레일로 오작동을 막는다

섹션 표지 슬라이드. 초록색 와이어프레임 숫자 2 와 자물쇠가 달린 방패 그림, 오작동 방지 가드레일 — AI가 잘못된 코드를 작성하지 않도록 통제하는 방법

프로젝트 지식 베이스(Digital Brain) 구축 슬라이드. 가운데 .notes/ 폴더를 중심으로 project_overview.md — 고수준 아키텍처, 데이터 흐름도(일관성 유지), task_list.md — 현재 마일스톤 및 작업 할당(중복 방지 및 맥락 유지), directory_structure.md — 에셋 배치 규칙 및 폴더 역할(올바른 위치 지정), .cursorrules(또는 CLAUDE.md) — 네이밍 컨벤션 및 프레임워크 제약(스타일 강제) 네 문서가 연결된 그림

Unity 전용 안티 패턴 차단 규칙(Ruleset) 비교. Don't(금지 패턴) — Update() 내에서의 new 할당 및 LINQ 사용(GC 스파이크), 잦은 GameObject.Find 및 GetComponent 호출, 일반 C# 방식의 객체 비교(ReferenceEquals 사용 금지). Do(권장 패턴) — UnityEngine.Pool.ObjectPool 을 통한 객체 재사용, Awake() 단계에서의 참조 캐싱 및 NonAlloc 물리 API 사용, Unity 고유의 파괴 검증 연산자(obj == null) 철저 준수

자기 보정 사이클(Self-Correction Loop) 도식. AI 코드 생성 → Unity 컴파일(오류 발생) → CLI Bridge(Exit Code 1 반환) → AI 자율 분석 및 수정 → 성공(Exit Code 0) 으로 도는 순환 화살표. 오른쪽 설명은 개발자가 직접 콘솔 에러를 복사·붙여넣기 하는 시대를 끝내라, unity-agent-bridge 와 Yolo 모드를 결합하여 AI가 컴파일러와 직접 대화하게 설정, AI가 유니티 에러 로그를 자체 판독하고 성공할 때까지 스스로 디버깅 수행

규칙 파일은 한 번 써 두면 매 대화마다 같은 설명을 반복하지 않아도 된다는 점에서 효과가 큽니다. 금지 패턴 목록은 팀이 코드 리뷰에서 자주 지적하던 항목을 그대로 옮기는 것부터 시작하면 됩니다. 자기 보정 루프는 편리하지만, AI에게 명령 실행 권한을 넓게 주는 방식이라 작업 범위와 되돌리기 방법을 먼저 정해 두는 것이 전제입니다.

기둥 3 — 검증과 오디팅

섹션 표지 슬라이드. 주황색 와이어프레임 숫자 3 에 스캐너 빛이 비치는 그림, 신속한 검증과 오디팅(Auditing) — AI가 작성한 코드를 직관적으로 이해하고 오류를 탐지하는 방법

시각적 오디팅(Visual Auditing) 슬라이드. 왼쪽 흐릿한 코드 화면에서 "프롬프트: 이 로직을 Mermaid 다이어그램으로 시각화해" 화살표를 따라 오른쪽에 시작 → 조건 확인 → 예(데이터 처리)/아니오(예외 처리) → 종료로 이어지는 순서도가 그려진다. 아래 세 줄은 AI가 작성한 수백 줄의 로직을 줄줄이 읽지 마라, 로직 흐름·상태 전이·데이터 파이프라인의 다이어그램화를 AI에게 요구하라, 시각화된 플로우를 통해 예외 처리 누락이나 논리적 비약을 수 초 내에 파악 가능

MECE 기반 분해와 역질문 검증 슬라이드. 전체 구조 설계에서 모듈 A·B·C 로 나뉘는 트리와 모듈 B 아래 "왜 이 아키텍처/방식을 선택했는가?"(역질문) 말풍선. 오른쪽 설명은 작업 분해 — 복잡한 시스템은 MECE(상호 배제 및 전체 포괄) 원칙에 따라 분해하여 단계별로 검토, 왜(Why) 역질문 — 코드가 완성된 후 AI에게 숨은 논리적 허점을 스스로 드러내게 하라, 효과 — AI 스스로 자신의 논리를 변호하게 만들며 맥락 누락을 개발자가 쉽게 적발 가능

AI 코드 신뢰 등급 관리(The Quarantine Pattern) 슬라이드. 세 단계 화살표 상자. 1단계 격리(Quarantine) 010회 실행 — 의심을 전제로 한 접근, 집중 로깅 및 즉각적인 롤백(Fallback) 대비. 2단계 모니터링(Monitored) 10100회 실행 — 런타임 예외 모니터링 및 성능 지표(프로파일러) 추적. 3단계 신뢰(Trusted) 100회 이상 무결성 입증 — 프로젝트 표준 라이브러리로 편입, 이후 AI가 재사용할 모범 사례(Best Practice)로 지정

Synthesis: 2026 에이전틱 워크플로 도식. 가운데 Architect & Auditor(개발자)를 맥락 통제(ASMDEF), 룰셋 제어(Guardrails), 품질 보증(Visual Auditing) 세 원이 둘러싸고 선으로 연결된 그림. 아래 설명은 타이피스트(Typist) 시대의 종말, 개발자의 역할은 코드를 생산하는 것에서 시스템을 설계하고 품질을 보증하는 아키텍트 겸 감사자로 진화했으며, 이 세 가지 기둥(구조화, 가드레일, 시각적 검증)의 결합만이 대규모 프로젝트를 10배 빠르게 성공시키는 유일한 공식이라는 문장

검증 단계에서 가장 바로 써 볼 만한 것은 다이어그램 요청입니다. 수백 줄을 한 줄씩 읽는 대신 상태 전이도나 순서도로 먼저 보면 빠진 분기가 눈에 띕니다. 신뢰 등급은 실행 횟수 기준이 자료의 예시일 뿐이고, 팀 사정에 맞게 "QA 한 차례 통과", "한 번의 업데이트 배포" 같은 기준으로 바꿔 써도 같은 효과를 낼 수 있습니다. 10배라는 결론 수치는 자료의 주장입니다.

자주 묻는 질문

유니티 프로젝트에 ASMDEF를 나중에 도입해도 되나요? 가능합니다. 다만 순환 참조를 먼저 정리해야 하므로, 의존성이 적은 공용 모듈부터 하나씩 분리하는 편이 안전합니다.

규칙 파일에는 무엇을 먼저 적어야 하나요? 코드 리뷰에서 반복 지적되는 항목부터 적는 것이 좋습니다. 네이밍 규칙, Update 내 할당 금지, null 비교 방식 같은 유니티 고유 규칙이 우선입니다.

AI가 쓴 코드는 어디까지 믿어도 되나요? 처음에는 격리 단계로 보고 로그와 되돌리기 수단을 붙여 두는 것이 좋습니다. 실제 사용에서 문제가 없음을 확인한 뒤 공용 코드로 올립니다.

작은 팀에도 이런 구조가 필요한가요? 코드가 커지기 전에 모듈 경계만 잡아 두어도 충분합니다. 나중에 AI 도구를 본격적으로 쓸 때 맥락을 좁히기 쉬워집니다.

저희가 이 이야기를 하는 이유

에버스톤은 2013년부터 Unity로 모바일 게임과 앱을 개발해 왔고, 지금은 자체 개발에 AI 코딩 도구를 함께 쓰고 있습니다. 프로젝트가 오래되고 커질수록 AI 도구의 효과는 도구 자체보다 프로젝트 구조와 규칙 문서에 더 크게 좌우된다고 느낍니다. 이 자료의 세 기둥은 그 경험을 정리하는 데 참고가 되는 틀입니다.

인용한 수치(79%, 46%, 5배, 10배), 도구 구성과 실행 횟수 기준은 원 자료 기준이며, 저희가 검증한 내용이 아닙니다.