Unity AI Assistant Project Overview 자동 생성 — AI가 내 프로젝트를 이해하게 만드는 방법 -

Unity AI 완전 정복 시리즈
1편 — Unity AI Assistant 완전 입문: Ask·Plan·Agent 모드 차이점과 언제 무엇을 쓸까
2편 — Unity MCP 완전 가이드: Claude Code·Codex·Gemini·Cursor를 Unity Editor와 연결하기
3편 — Unity MCP 커스텀 도구 만들기: McpTool Deep Dive와 4가지 등록 방식
4편 — Unity Skills 시스템으로 AI 워크플로우 자동화하기: SKILL.md 완전 가이드
Appendix — Unity MCP 빌트인 도구 완전 레퍼런스 — 51개 도구 파라미터·활성화 가이드
5편 — Unity AI Assistant Project Overview 자동 생성 — AI가 내 프로젝트를 이해하게 만드는 방법 (현재 글)
6편 — Unity AI Assistant × Profiler — 성능 병목을 자연어로 진단하는 완전 가이드

Unity AI Assistant에 프롬프트를 입력할 때, AI가 내 프로젝트 구조를 전혀 모르는 상태에서 답한다면 어떨까요? 매번 “우리 프로젝트는 씬이 세 개이고, 매니저 패턴을 쓰고 있으며…”를 반복해서 설명해야 한다면 생산성이라는 말이 무색해집니다. Refresh Project Overview 기능은 이 문제를 해결합니다. Assistant가 프로젝트를 직접 스캔해서 11개 섹션으로 구성된 기술 문서(Project_Overview.md)를 자동 생성하고, 이후 모든 응답의 컨텍스트로 이 문서를 참조합니다. Unity 6.3 기준으로 이 기능의 작동 방식과 실무 활용 포인트를 정리합니다.

TL;DR
– Assistant 텍스트 필드의 Gear 아이콘(⚙) → Refresh Project Overview 선택으로 실행
– Assets/Project_Overview.md가 자동 생성되며 11개 섹션의 구조화된 기술 문서를 포함
– 생성 후 Assistant는 이 파일을 모든 응답의 컨텍스트로 참조
– 수동 편집 가능하지만, 재생성 시 편집 내용은 덮어씌워짐
– 프로젝트 구조가 안정화된 시점에 생성하고, 주요 변경 후마다 재생성 권장

Refresh Project Overview 진입 경로
Project_Overview.md 자동 생성 위치
11개 섹션 전체 구조
AI 컨텍스트 참조 메커니즘
수동 편집과 덮어쓰기 동작
언제 재생성해야 하는가
프로젝트 구조 안정화 후 생성 권장
자주 묻는 질문

Refresh Project Overview 진입 경로

진입 경로는 두 단계입니다. Assistant 창의 텍스트 필드 안에 있는 Gear 아이콘(⚙)을 선택하면 프롬프트 설정 메뉴가 열립니다. 여기서 Refresh Project Overview를 선택하면 스캔이 시작됩니다.

이 기능을 사용하려면 Assistant 창이 열려 있고 대화가 시작된 상태여야 합니다. 대화를 먼저 시작하지 않으면 프롬프트 설정 메뉴에 접근할 수 없습니다.

스캔이 진행되는 동안에도 Assistant를 계속 사용할 수 있습니다. 생성 작업이 백그라운드에서 실행되므로 별도로 기다릴 필요 없이 다른 질문을 이어가도 됩니다.

Project_Overview.md 자동 생성 위치

Refresh Project Overview를 실행하면 Assistant가 프로젝트 계층 구조를 스캔하고 시스템을 분석해 포괄적인 기술 문서를 생성합니다. 생성된 파일은 프로젝트의 Assets 폴더 바로 아래에 Project_Overview.md라는 이름으로 저장됩니다.

YourProject/
└── Assets/
    └── Project_Overview.md   ← 자동 생성 위치

Unity 에디터의 Project 창에서도 이 파일을 바로 확인할 수 있습니다. 텍스트 에디터에서 직접 열어 내용을 검토하는 것도 가능합니다.

11개 섹션 전체 구조

생성된 Project_Overview.md는 다음 11개 섹션으로 구성됩니다. 각 섹션이 담당하는 정보가 무엇인지 파악해두면 문서를 수동으로 보완할 때 어느 섹션에 내용을 추가해야 할지 판단하기 쉽습니다.

섹션 이름	담당 내용
Project Overview	프로젝트의 목적, 대상 사용자, 경험을 정의하는 핵심 기능
Gameplay Flow / User Loop	실행에서 종료까지 사용자가 경험하는 흐름, 주요 상태와 전환
Architecture (Runtime + Editor)	주요 시스템 간 상호작용, 주요 씬·매니저·패턴·데이터 흐름
Scene Overview	주요 씬 목록, 각 씬의 역할, 씬 간 로드 방식, 씬 플로우 제어 규칙
UI System	사용 중인 UI 프레임워크, 화면 구조, 데이터 바인딩, 내비게이션 흐름, UI 화면 업데이트 방법
Asset & Data Model	콘텐츠 저장·조직 방식 (프리팹, ScriptableObjects, Addressables, 저장 데이터 포함)
Project Structure (Repo & Folder Taxonomy)	리포지토리와 폴더 조직 방식, 구조 일관성을 위한 컨벤션
Technical Dependencies	Unity 버전, 렌더 파이프라인, 패키지, 플러그인, SDK, 필수 외부 서비스
Build & Deployment	로컬 및 자동화 파이프라인에서 프로젝트를 빌드·테스트·배포하는 방법
Style, Quality & Testing	코드 표준, 성능 목표, 프로파일링 관행, 테스트 기대값
Notes, Caveats & Gotchas	엣지 케이스, 제한사항, 경고, 흔한 함정

11개 섹션을 보면 설계 의도가 읽힙니다. 단순한 파일 목록이 아니라, 새 개발자가 프로젝트에 투입됐을 때 알아야 할 맥락을 구조화한 형태입니다. “이 씬은 왜 이렇게 로드되는가”, “UI 화면을 어떻게 추가하는가” 같은 실무 질문에 AI가 직접 답할 수 있는 기반을 만드는 것이 목적입니다.

AI 컨텍스트 참조 메커니즘

Project_Overview.md가 생성된 이후부터 Assistant는 이 파일을 모든 응답의 컨텍스트로 참조합니다. 즉, 이후 대화에서 프로젝트 구조나 시스템에 대한 질문을 할 때 Assistant는 이 문서를 바탕으로 더 관련성 높은 답변을 제공할 수 있게 됩니다.

실무적으로 어떤 차이가 생기는지 예를 들어 보겠습니다. Project_Overview.md가 없는 상태에서 “씬 전환 로직을 어디에 두는 게 좋을까요?”라고 물으면 Assistant는 일반적인 Unity 패턴을 기반으로 답합니다. 반면 문서가 있고 Architecture 섹션에 “씬 매니저 패턴 사용, SceneController가 모든 전환 담당”이라는 내용이 들어 있다면 Assistant는 그 구조에 맞는 구체적인 답변을 제시합니다.

특히 Agent 모드에서 이 차이가 두드러집니다. Agent 모드는 프로젝트에 직접 변경을 가하는 작업을 수행하는데, 프로젝트 개요 문서가 있으면 기존 아키텍처와 컨벤션을 고려한 코드를 생성하거나 파일을 배치할 가능성이 높아집니다.

수동 편집과 덮어쓰기 동작

생성된 Project_Overview.md는 일반 마크다운 파일이므로 텍스트 에디터로 직접 열어 내용을 수정할 수 있습니다. AI가 놓친 세부 사항을 보완하거나, 팀 내에서만 통용되는 컨벤션이나 주의사항을 Notes, Caveats & Gotchas 섹션에 추가하는 방식으로 활용할 수 있습니다.

단, 한 가지 동작을 반드시 인지해야 합니다. Refresh Project Overview를 다시 실행하면 수동으로 편집한 내용이 모두 덮어씌워집니다.

보완 내용을 보존하고 싶다면 별도 파일에 메모해두거나, 재생성 후 다시 병합하는 방식으로 관리해야 합니다. 이 점은 현재 버전(2.7)의 제약으로, 사용 전에 팀 전체가 인지하고 있어야 합니다.

반대로, Assistant가 이 문서를 아예 참조하지 않도록 하고 싶다면 Assets/ 폴더에서 Project_Overview.md 파일을 직접 삭제하면 됩니다. 파일이 없으면 Assistant는 이 문서를 컨텍스트로 사용하지 않습니다.

언제 재생성해야 하는가

Project_Overview.md는 생성 시점의 스냅샷입니다. 프로젝트가 발전하면 문서도 업데이트해야 합니다. 공식 문서에서 명시하는 재생성 트리거는 다음과 같습니다.

게임 플로우(Game Flow) 변경 — 씬 전환 로직, 게임 상태 구조, 사용자 루프가 달라진 경우
의존성(Dependencies) 변경 — Unity 버전 업그레이드, 패키지 추가·제거, 외부 SDK 변경
씬 구성(Scene Organization) 변경 — 씬 추가·삭제·이름 변경, 씬 역할 재편
폴더 레이아웃(Folder Layout) 변경 — 프로젝트 폴더 구조 재편, 네임스페이스 정리
에셋 콘텐츠(Asset Contents) 변경 — 주요 ScriptableObjects, Addressables 구조 변경

반대로 특정 스크립트 로직 수정이나 버그 픽스처럼 구조적 변경이 없는 작업 후에는 재생성이 필요하지 않습니다. 재생성할 때마다 Unity Credits를 소비하므로, 의미 있는 구조 변경이 있을 때만 실행하는 것이 합리적입니다.

프로젝트 구조 안정화 후 생성 권장

공식 문서는 “프로젝트 구조가 상대적으로 안정화된 시점에 Project Overview를 생성하는 것이 최적 결과를 위한 방법”이라고 명시합니다. 실무 관점에서 이 조언을 해석하면 다음과 같습니다.

프로젝트 초기 단계, 특히 씬 구조나 폴더 구성이 하루가 다르게 바뀌는 시점에 생성한 문서는 빠르게 유효성을 잃습니다. 결과적으로 AI가 참조하는 문서와 실제 프로젝트 상태가 괴리되어, 오히려 부정확한 맥락으로 답변이 틀어질 수 있습니다.

반면 스프린트 막바지나 마일스톤 직후처럼 구조가 어느 정도 굳어진 시점에 문서를 생성하면, 이후 한동안의 개발 기간 동안 유효한 컨텍스트를 AI에 제공할 수 있습니다. 저는 기능 브랜치를 main에 머지한 직후를 재생성 타이밍으로 삼는 방식이 현실적이라고 판단합니다.

자주 묻는 질문

Project_Overview.md가 Git에 포함되어야 할까요?

공식 문서에서는 이 부분에 대해 별도 언급이 없습니다. 실무 관점에서 생각하면, 이 파일은 팀원 모두가 동일한 컨텍스트를 AI에 제공할 수 있다는 점에서 버전 관리에 포함하는 것이 유리합니다. 다만 재생성 시 충돌이 발생할 수 있으므로, 재생성 후 커밋 전 리뷰하는 프로세스를 팀 규칙으로 정해두는 것이 바람직합니다.

생성 중에 Assistant를 다른 용도로 사용할 수 있나요?

네, 가능합니다. 공식 문서에 따르면 overview 생성 중에도 Assistant를 계속 사용할 수 있습니다. 스캔과 문서 생성이 백그라운드에서 진행되므로, 별도로 완료를 기다릴 필요가 없습니다.

Project_Overview.md를 삭제하면 어떻게 되나요?

파일을 삭제하면 Assistant는 더 이상 이 문서를 컨텍스트로 참조하지 않습니다. 의도적으로 프로젝트 개요 참조를 차단하고 싶을 때 이 방법을 사용할 수 있습니다. 다시 필요하면 Refresh Project Overview를 실행해 재생성하면 됩니다.

생성된 문서의 정확도는 어느 정도인가요?

Assistant가 프로젝트 계층 구조를 스캔하고 시스템을 분석해서 생성하지만, AI가 추론한 결과이므로 100% 정확하지 않을 수 있습니다. 생성 직후에 내용을 검토하고, 잘못 파악된 부분이나 누락된 정보는 직접 수정하는 것을 권장합니다. 단, 앞서 언급했듯이 재생성 시 편집 내용은 덮어씌워집니다.

마무리

Refresh Project Overview는 Assistant가 내 프로젝트를 알게 만드는 기능입니다. 11개 섹션의 문서를 자동 생성하고, 이후 모든 응답에서 이 맥락을 참조하기 때문에 매번 프로젝트 구조를 설명하는 반복을 줄일 수 있습니다.

실무에서 이 기능을 제대로 쓰려면 세 가지 습관이 필요합니다. 구조가 어느 정도 안정된 시점에 처음 생성할 것, 게임 플로우·의존성·씬 구성·폴더 구조·에셋 콘텐츠에 주요 변경이 있을 때마다 재생성할 것, 수동으로 보강한 내용은 별도로 관리해 재생성 후 다시 병합할 것. 이 세 가지를 지키면 문서와 실제 프로젝트 상태의 괴리 없이 유효한 컨텍스트를 유지할 수 있습니다.

Unity AI Assistant Project Overview 자동 생성 — AI가 내 프로젝트를 이해하게 만드는 방법