← 최신 가이드

Unity AI 도구 가이드

v1.0 · 2026-10-06 갱신 · 항목 10개

버전◀ 처음최신 ▶두 버전 비교

이 페이지는 v1.0 시점의 기록입니다. 최신 가이드 보기

AI에 바로 적용하기

Claude Code나 Codex를 프로젝트 폴더에서 열고 붙여 넣으세요. 현재 설정을 조사해 점검표를 만들고, 파일로 할 수 있는 것은 AI가 하며, 에디터에서 클릭해야 할 것은 "사람이 할 일" 목록으로 정리합니다.

프롬프트 미리보기
이 Unity 프로젝트에 아래 "Unity AI 도구 가이드 v1.0" (2026-10-06) 항목을 적용해 줘. 대상은 Unity 프로젝트의 AI 도구 설정(MCP 연결, 검증 루프, 코드 품질, 반복 속도)이다.

## 작업 절차
1. 현재 상태 조사 (아직 고치지 않는다)
   - Unity 버전: ProjectSettings/ProjectVersion.txt
   - 패키지: Packages/manifest.json (com.coplaydev.unity-mcp, com.unity.ai.assistant, com.unity.test-framework 등)
   - asmdef 현황, Tests 폴더, Player Settings의 Scripting Define Symbols(USE_ROSLYN)
   - MCP 설정: .mcp.json, ~/.claude.json, ~/.codex/config.toml 의 Unity 항목
   - AGENTS.md의 Unity·MCP 관련 규칙
2. 점검표: 아래 항목마다 "적용됨 / 안 됨 / 해당 없음"과 근거(파일:줄)를 표로 만든다.
3. 계획을 보여 주고 내 확인을 받은 뒤 진행한다. (확인 없이 바로 진행하려면 이 줄을 지운다)
4. 적용 규칙
   - 파일로 할 수 있는 것(manifest.json 패키지 줄, AGENTS.md 섹션, asmdef, 리셋 코드)은 직접 한다.
   - 에디터 안에서 사람이 클릭해야 하는 것(메뉴 실행, 설정 창, Unity 재시작)은 "사람이 할 일" 목록으로 순서대로 정리한다.
   - 템플릿의 "채울 것" 안내를 따른다: AI 칸은 저장소에서 읽어 채우고, 직접 칸은 추측하지 말고 질문 목록에 넣는다.
   - Unity 버전 조건이 안 맞는 항목(예: 공식 MCP는 Unity 6 이상)은 건너뛰고 이유를 적는다.
5. 검증: 컴파일 에러가 없는지 확인한다(MCP가 연결돼 있으면 refresh_unity → read_console).
6. 보고: 적용한 것, 사람이 할 일, 남은 질문을 표로 정리한다.

## 항목
### T01 Unity MCP(CoplayDev unity-mcp)를 설치해 AI가 에디터를 직접 다루게 함
- 왜: MCP가 없으면 AI는 C# 파일만 고치고, 씬·프리팹·콘솔 에러는 사람이 보고 옮겨 줘야 합니다
- 효과: 콘솔 에러를 복사해 붙여 넣을 필요가 없어지고, 씬·게임오브젝트·컴포넌트·에셋·테스트·빌드까지 대화로 처리. 무료(MIT), Unity 2021.3~6.x 지원
- 방법:
  1. Python 3.10+와 uv 설치
  2. Unity → Package Manager → Add from git URL → https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.0.0 (버전 고정)
  3. Window → MCP for Unity → Configure All Detected Clients (Claude Code·Codex 등 자동 설정)
  4. AI 도구를 다시 열고 "Unity 콘솔 에러 읽어 줘"로 연결 확인
### T02 Unity 6 + Unity AI 구독 중이면 Unity 공식 MCP(AI Assistant 패키지)도 선택지
- 왜: Unity가 직접 만든 연결이라 에디터 버전과 함께 관리됩니다. 단, 조건이 있습니다
- 효과: 조건: Unity 6(6000.0) 이상, com.unity.ai.assistant 패키지, Unity AI 베타 체험·구독, Unity Cloud 연결 프로젝트 (공식 블로그 기준). 조건이 안 맞으면 CoplayDev가 현실적
- 방법:
  1. Package Manager에서 AI Assistant 패키지 설치
  2. Unity 실행 시 ~/.unity/relay/ 에 relay 실행 파일이 설치됨
  3. Integrations 패널의 자동 설정 또는 아래 설정 파일 예시로 AI 도구에 등록
### T03 unity-mcp 도구 그룹은 필요한 것만 켬 (기본은 core 30개)
- 왜: 보이는 도구마다 매 호출에 토큰이 붙고, 도구가 많을수록 엉뚱한 도구를 고를 확률이 오릅니다
- 효과: 공식 문서: 도구를 숨기면 토큰 비용이 줄고, 48개보다 core 30개 중에서 고를 때 잘못된 도구 선택이 측정 가능하게 줄어듦
- 방법:
  1. 기본 상태(core만)로 시작
  2. 테스트가 필요할 때: manage_tools(action="activate", group="testing")
  3. UI Toolkit·VFX·프로파일링 등도 그 작업 때만 켜고 끝나면 deactivate
### T04 unity-mcp의 Roslyn 스크립트 검증(USE_ROSLYN)을 켬
- 왜: AI가 쓴 C#에 없는 네임스페이스·타입·메서드가 있으면 Unity 컴파일까지 가서야 드러납니다
- 효과: Unity 컴파일 전에 의미 분석으로 오류를 잡아 수정-컴파일 반복이 줄어듦. 공식 문서가 'AI가 C#을 많이 쓸 때' 켜라고 권장
- 방법:
  1. Window → MCP for Unity → Runtime Code Execution → Install Roslyn DLLs
  2. Player Settings → Scripting Define Symbols 에 USE_ROSLYN 추가
  3. Unity 재시작 → 상태 패널에 "Roslyn: enabled" 확인
### T05 에디터를 조작하는 세션은 하나로 정하고, Unity를 여러 개 열면 대상 인스턴스를 지정
- 왜: MCP는 열린 에디터에 연결되므로 여러 세션이 같은 에디터를 동시에 조작하면 상태가 꼬입니다
- 효과: 씬·에셋 동시 수정 충돌 방지. 공식 MCP relay는 기본으로 처음 찾은 에디터에 연결, unity-mcp는 set_active_instance로 지정
- 방법:
  1. AGENTS.md에 "에디터 조작은 <역할> 세션만" 한 줄 추가
  2. Unity를 둘 이상 열 때: unity-mcp는 set_active_instance로 대상 지정 (Multi-Instance Routing 문서)
### T06 스크립트를 고친 뒤 refresh_unity → read_console 순서로 컴파일 결과를 확인하게 함
- 왜: AI는 파일 저장만 하고 끝내기 쉽고, 컴파일 에러는 에디터 콘솔에만 나옵니다
- 효과: AI가 스스로 컴파일 에러를 보고 고치는 반복이 생김 (사람이 콘솔을 볼 필요 감소)
- 방법:
  1. unity-mcp 설치 상태에서 AGENTS.md에 아래 'MCP 사용 규칙' 섹션 추가
  2. 작업 지시 끝에 "콘솔에 에러 0개를 확인하고 끝내"를 붙여도 됨
### T07 테스트 경로를 두 가지로 정함: 에디터가 열려 있으면 MCP run_tests, 닫혀 있으면 배치 모드 명령
- 왜: 같은 프로젝트를 에디터 두 개로 열 수 없어서, 에디터가 열린 상태에서는 배치 모드 테스트가 실패합니다
- 효과: 에디터를 닫지 않고도 AI가 테스트를 돌려 결과를 확인. 에디터 없이 돌릴 때(밤샘 작업 등)는 배치 모드로
- 방법:
  1. Unity Test Framework 패키지와 Tests 폴더 준비 (Create → Testing → Tests Assembly Folder)
  2. 에디터 열림: manage_tools로 testing 그룹 활성화 → run_tests → get_test_job으로 결과 확인
  3. 에디터 닫힘: AGENTS.md의 배치 모드 명령 (-batchmode -runTests -testResults)
### T08 Microsoft의 Unity 분석기(Microsoft.Unity.Analyzers)가 켜져 있는지 확인
- 왜: 일반 C# 분석기는 Unity 관례를 모르고, 반대로 Unity에 맞지 않는 경고를 냅니다
- 효과: Unity 전용 진단이 추가되고 Unity에 안 맞는 일반 경고는 억제되어, AI가 만든 코드의 Unity 함정이 IDE 경고로 보임
- 방법:
  1. Visual Studio: "Game development with Unity" 워크로드 설치 시 기본 포함
  2. VS Code: Unity 공식 확장(VisualStudioToolsForUnity.vstuc) 설치
  3. Unity가 만든 프로젝트 파일에 자동 포함되므로 별도 설정 없이 경고 확인
### T09 Assembly Definition(asmdef)으로 코드를 기능 단위로 나눔
- 왜: AI가 파일 하나를 고칠 때마다 큰 어셈블리 전체가 다시 컴파일되면 수정-확인 반복이 느려집니다
- 효과: Unity 공식: 어셈블리로 나누면 불필요한 재컴파일 시간이 줄어듦. AI 반복 한 번당 대기 시간 감소
- 방법:
  1. 기능 폴더마다 Create → Scripting → Assembly Definition
  2. 의존 방향대로 references 정리 (예: UI → Core, Core는 UI를 모름)
  3. 테스트 코드는 별도 Tests 어셈블리로
### T10 Enter Play Mode 옵션에서 도메인 리로드를 끄고, static 초기화 규칙을 AGENTS.md에 적음
- 왜: 플레이 모드 진입마다 도메인·씬 리로드에 시간이 들고, 스크립트가 많을수록 길어집니다
- 효과: 플레이 진입 시간이 줄어 AI 수정-확인 반복이 빨라짐. Unity 6.6 문서는 개발 반복 속도와 CoreCLR 대비로 도메인 리로드 끄기를 권장
- 방법:
  1. Project Settings → Editor → Enter Play Mode Settings에서 도메인 리로드 끄기
  2. static 필드·이벤트는 플레이 시작 때 초기화되지 않으므로 [RuntimeInitializeOnLoadMethod]로 리셋 (아래 예시)
  3. AGENTS.md에 "static 상태는 리셋 메서드와 함께 만든다" 규칙 추가

## 설정·예시 파일 (형식 참고용)
#### AGENTS.md에 추가 · Unity MCP 사용 규칙
놓는 위치: 루트 AGENTS.md의 '프로젝트 고유 규칙' 아래에 붙여 넣기
- 채울 것 [직접] <에디터 담당 역할>: 에디터를 조작할 세션 이름. 혼자 한 세션이면 이 줄 삭제 (확인: 본인 작업 구조)
- 채울 것 [AI] 테스트 줄: Test Framework·테스트가 없으면 지운다 (확인: Packages/manifest.json 의 com.unity.test-framework)
- 채울 것 [그대로] 나머지 줄: 그대로 쓴다
````
## Unity 에디터 (MCP)
- 에디터 조작은 Unity MCP로 한다. 씬·프리팹 YAML을 텍스트로 직접 고치지 않는다.
- 스크립트를 고친 뒤: refresh_unity → read_console 로 컴파일 에러 0개를 확인하고 끝낸다.
- 테스트: 에디터가 열려 있으면 MCP run_tests(get_test_job으로 결과 확인), 닫혀 있으면 위 검증 명령.
- 필요한 도구 그룹만 켠다. 예: manage_tools(action="activate", group="testing") → 끝나면 deactivate
- 에디터 조작은 <에디터 담당 역할> 세션만 한다. 다른 세션은 코드만 고치고 필요한 에디터 작업을 보고서에 적는다.
````

#### Packages/manifest.json에 추가 · unity-mcp
놓는 위치: Packages/manifest.json 의 dependencies 안에 한 줄 추가 (Package Manager → Add from git URL 과 같은 효과)
- 채울 것 [AI→직접] #v10.0.0: 고정할 버전. 새 릴리스가 나오면 바꾼다 (확인: unity-mcp Releases)
- 채울 것 [그대로] 나머지: 기존 dependencies는 그대로 두고 이 줄만 추가
- 채울 것 [직접] 설치 후: Window → MCP for Unity → Configure All Detected Clients 는 에디터에서 직접 클릭
````
{
  "dependencies": {
    "com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.0.0"
  }
}
````

#### Codex 설정 · 공식 Unity MCP (config.toml)
놓는 위치: ~/.codex/config.toml (Unity 공식 MCP를 쓸 때만. Unity 문서의 Claude Code 설정을 Codex 형식으로 옮긴 것)
- 채울 것 [AI] <HOME>: 사용자 폴더 절대 경로. 예: C:/Users/<이름> (확인: 탐색기 주소창)
- 채울 것 [AI] <relay 실행 파일>: ~/.unity/relay/ 폴더 안의 실행 파일 이름 (운영체제별로 다름) (확인: ~/.unity/relay/ 폴더)
- 채울 것 [선택] startup_timeout_sec: Codex 기본은 10초. 에디터 연결이 늦으면 늘린다 (확인: Codex MCP 문서)
- 채울 것 [선택] unity-mcp(CoplayDev)를 쓰면: 이 파일 대신 Configure All Detected Clients 가 자동으로 설정한다
````
[mcp_servers.unity-mcp]
command = "<HOME>/.unity/relay/<relay 실행 파일>"
args = ["--mcp"]
startup_timeout_sec = 20
````

#### Claude Code 설정 · 공식 Unity MCP (.mcp.json)
놓는 위치: 프로젝트 루트의 .mcp.json (팀과 공유) 또는 claude mcp add 로 개인 설정
- 채울 것 [AI] <HOME>, <relay 실행 파일>: 위 Codex 설정과 같다 (확인: ~/.unity/relay/ 폴더)
- 채울 것 [직접] 팀 공유 여부: 경로가 사람마다 다르면 .mcp.json 대신 claude mcp add (local 범위)로 각자 등록
````
{
  "mcpServers": {
    "unity-mcp": {
      "command": "<HOME>/.unity/relay/<relay 실행 파일>",
      "args": ["--mcp"]
    }
  }
}
````

#### asmdef 예시 · Game.UI.asmdef
놓는 위치: Assets/Scripts/UI/Game.UI.asmdef (Create → Scripting → Assembly Definition 으로 만들면 같은 파일이 생김)
- 채울 것 [AI→직접] Game.UI, Game.Core: 실제 폴더·기능 이름으로 (확인: Assets/Scripts 폴더 구조)
- 채울 것 [AI] references: 이 코드가 쓰는 다른 어셈블리만. 서로 참조(순환)는 만들 수 없다 (확인: using 문, 컴파일 에러)
````
{
  "name": "Game.UI",
  "rootNamespace": "Game.UI",
  "references": ["Game.Core"],
  "autoReferenced": true
}
````

#### C# 예시 · 도메인 리로드 끈 상태의 static 리셋
놓는 위치: static 상태를 가진 클래스마다 (AGENTS.md 규칙으로 AI가 지키게 함)
- 채울 것 [그대로] ScoreCache, s_total: 예시 이름
- 채울 것 [AI] 적용 대상: 기존 코드의 static 필드·이벤트를 찾아 리셋 메서드 추가 (확인: 프로젝트 전체 검색)
````
public static class ScoreCache
{
    static int s_total;

    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
    static void ResetStatics()
    {
        s_total = 0; // 도메인 리로드가 꺼져 있으면 플레이 시작 때 자동으로 0이 되지 않는다
    }
}
````

항목 (10)

에디터 연결 (MCP)

T01 · Unity MCP(CoplayDev unity-mcp)를 설치해 AI가 에디터를 직접 다루게 함

왜MCP가 없으면 AI는 C# 파일만 고치고, 씬·프리팹·콘솔 에러는 사람이 보고 옮겨 줘야 합니다
효과콘솔 에러를 복사해 붙여 넣을 필요가 없어지고, 씬·게임오브젝트·컴포넌트·에셋·테스트·빌드까지 대화로 처리. 무료(MIT), Unity 2021.3~6.x 지원
어떻게1. Python 3.10+와 uv 설치 2. Unity → Package Manager → Add from git URL → https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.0.0 (버전 고정) 3. Window → MCP for Unity → Configure All Detected Clients (Claude Code·Codex 등 자동 설정) 4. AI 도구를 다시 열고 "Unity 콘솔 에러 읽어 줘"로 연결 확인
근거공식 · CoplayDev unity-mcp README
v1.0

T02 · Unity 6 + Unity AI 구독 중이면 Unity 공식 MCP(AI Assistant 패키지)도 선택지

왜Unity가 직접 만든 연결이라 에디터 버전과 함께 관리됩니다. 단, 조건이 있습니다
효과조건: Unity 6(6000.0) 이상, com.unity.ai.assistant 패키지, Unity AI 베타 체험·구독, Unity Cloud 연결 프로젝트 (공식 블로그 기준). 조건이 안 맞으면 CoplayDev가 현실적
어떻게1. Package Manager에서 AI Assistant 패키지 설치 2. Unity 실행 시 ~/.unity/relay/ 에 relay 실행 파일이 설치됨 3. Integrations 패널의 자동 설정 또는 아래 설정 파일 예시로 AI 도구에 등록
근거공식 · Unity 문서: Get started with Unity MCP · Unity 블로그: Unity MCP 시작하기 (2026-05-11)
v1.0

T03 · unity-mcp 도구 그룹은 필요한 것만 켬 (기본은 core 30개)

왜보이는 도구마다 매 호출에 토큰이 붙고, 도구가 많을수록 엉뚱한 도구를 고를 확률이 오릅니다
효과공식 문서: 도구를 숨기면 토큰 비용이 줄고, 48개보다 core 30개 중에서 고를 때 잘못된 도구 선택이 측정 가능하게 줄어듦
어떻게1. 기본 상태(core만)로 시작 2. 테스트가 필요할 때: manage_tools(action="activate", group="testing") 3. UI Toolkit·VFX·프로파일링 등도 그 작업 때만 켜고 끝나면 deactivate
근거공식 · unity-mcp Tool Groups
v1.0

T04 · unity-mcp의 Roslyn 스크립트 검증(USE_ROSLYN)을 켬

왜AI가 쓴 C#에 없는 네임스페이스·타입·메서드가 있으면 Unity 컴파일까지 가서야 드러납니다
효과Unity 컴파일 전에 의미 분석으로 오류를 잡아 수정-컴파일 반복이 줄어듦. 공식 문서가 'AI가 C#을 많이 쓸 때' 켜라고 권장
어떻게1. Window → MCP for Unity → Runtime Code Execution → Install Roslyn DLLs 2. Player Settings → Scripting Define Symbols 에 USE_ROSLYN 추가 3. Unity 재시작 → 상태 패널에 "Roslyn: enabled" 확인
근거공식 · unity-mcp Roslyn Validation
v1.0

T05 · 에디터를 조작하는 세션은 하나로 정하고, Unity를 여러 개 열면 대상 인스턴스를 지정

왜MCP는 열린 에디터에 연결되므로 여러 세션이 같은 에디터를 동시에 조작하면 상태가 꼬입니다
효과씬·에셋 동시 수정 충돌 방지. 공식 MCP relay는 기본으로 처음 찾은 에디터에 연결, unity-mcp는 set_active_instance로 지정
어떻게1. AGENTS.md에 "에디터 조작은 <역할> 세션만" 한 줄 추가 2. Unity를 둘 이상 열 때: unity-mcp는 set_active_instance로 대상 지정 (Multi-Instance Routing 문서)
근거공식+해석 · unity-mcp Multi-Instance Routing · Unity 문서: Get started with Unity MCP
v1.0

검증 루프

T06 · 스크립트를 고친 뒤 refresh_unity → read_console 순서로 컴파일 결과를 확인하게 함

왜AI는 파일 저장만 하고 끝내기 쉽고, 컴파일 에러는 에디터 콘솔에만 나옵니다
효과AI가 스스로 컴파일 에러를 보고 고치는 반복이 생김 (사람이 콘솔을 볼 필요 감소)
어떻게1. unity-mcp 설치 상태에서 AGENTS.md에 아래 'MCP 사용 규칙' 섹션 추가 2. 작업 지시 끝에 "콘솔에 에러 0개를 확인하고 끝내"를 붙여도 됨
근거공식+해석 · unity-mcp 도구 목록
v1.0

T07 · 테스트 경로를 두 가지로 정함: 에디터가 열려 있으면 MCP run_tests, 닫혀 있으면 배치 모드 명령

왜같은 프로젝트를 에디터 두 개로 열 수 없어서, 에디터가 열린 상태에서는 배치 모드 테스트가 실패합니다
효과에디터를 닫지 않고도 AI가 테스트를 돌려 결과를 확인. 에디터 없이 돌릴 때(밤샘 작업 등)는 배치 모드로
어떻게1. Unity Test Framework 패키지와 Tests 폴더 준비 (Create → Testing → Tests Assembly Folder) 2. 에디터 열림: manage_tools로 testing 그룹 활성화 → run_tests → get_test_job으로 결과 확인 3. 에디터 닫힘: AGENTS.md의 배치 모드 명령 (-batchmode -runTests -testResults)
근거공식+해석 · unity-mcp 도구 목록 · Unity Test Framework: 명령줄 실행
v1.0

코드 품질

T08 · Microsoft의 Unity 분석기(Microsoft.Unity.Analyzers)가 켜져 있는지 확인

왜일반 C# 분석기는 Unity 관례를 모르고, 반대로 Unity에 맞지 않는 경고를 냅니다
효과Unity 전용 진단이 추가되고 Unity에 안 맞는 일반 경고는 억제되어, AI가 만든 코드의 Unity 함정이 IDE 경고로 보임
어떻게1. Visual Studio: "Game development with Unity" 워크로드 설치 시 기본 포함 2. VS Code: Unity 공식 확장(VisualStudioToolsForUnity.vstuc) 설치 3. Unity가 만든 프로젝트 파일에 자동 포함되므로 별도 설정 없이 경고 확인
근거공식 · Microsoft Analyzers for Unity
v1.0

반복 속도

T09 · Assembly Definition(asmdef)으로 코드를 기능 단위로 나눔

왜AI가 파일 하나를 고칠 때마다 큰 어셈블리 전체가 다시 컴파일되면 수정-확인 반복이 느려집니다
효과Unity 공식: 어셈블리로 나누면 불필요한 재컴파일 시간이 줄어듦. AI 반복 한 번당 대기 시간 감소
어떻게1. 기능 폴더마다 Create → Scripting → Assembly Definition 2. 의존 방향대로 references 정리 (예: UI → Core, Core는 UI를 모름) 3. 테스트 코드는 별도 Tests 어셈블리로
근거공식 · Unity 매뉴얼: Assembly definitions
v1.0

T10 · Enter Play Mode 옵션에서 도메인 리로드를 끄고, static 초기화 규칙을 AGENTS.md에 적음

왜플레이 모드 진입마다 도메인·씬 리로드에 시간이 들고, 스크립트가 많을수록 길어집니다
효과플레이 진입 시간이 줄어 AI 수정-확인 반복이 빨라짐. Unity 6.6 문서는 개발 반복 속도와 CoreCLR 대비로 도메인 리로드 끄기를 권장
어떻게1. Project Settings → Editor → Enter Play Mode Settings에서 도메인 리로드 끄기 2. static 필드·이벤트는 플레이 시작 때 초기화되지 않으므로 [RuntimeInitializeOnLoadMethod]로 리셋 (아래 예시) 3. AGENTS.md에 "static 상태는 리셋 메서드와 함께 만든다" 규칙 추가
근거공식+해석 · Unity 매뉴얼: Configurable Enter Play Mode
v1.0

설정 · 예시 파일

위 항목을 적용할 때 쓰는 설정 조각과 예시입니다. 파일마다 "채울 것" 표를 보고 < > 칸을 정리하세요. 누가: AI 적용 프롬프트를 쓰면 AI가 저장소에서 읽어 채움 · AI→직접 AI가 후보를 넣고 본인이 확인 · 직접 본인이 정해야 함 · 그대로 수정 불필요 · 선택 필요 없으면 삭제

AGENTS.md에 추가 · Unity MCP 사용 규칙

놓는 위치 · 루트 AGENTS.md의 '프로젝트 고유 규칙' 아래에 붙여 넣기

채울 것무엇을 넣나어디서 확인누가
<에디터 담당 역할>에디터를 조작할 세션 이름. 혼자 한 세션이면 이 줄 삭제본인 작업 구조직접
테스트 줄Test Framework·테스트가 없으면 지운다Packages/manifest.json 의 com.unity.test-frameworkAI
나머지 줄그대로 쓴다—그대로
## Unity 에디터 (MCP)
- 에디터 조작은 Unity MCP로 한다. 씬·프리팹 YAML을 텍스트로 직접 고치지 않는다.
- 스크립트를 고친 뒤: refresh_unity → read_console 로 컴파일 에러 0개를 확인하고 끝낸다.
- 테스트: 에디터가 열려 있으면 MCP run_tests(get_test_job으로 결과 확인), 닫혀 있으면 위 검증 명령.
- 필요한 도구 그룹만 켠다. 예: manage_tools(action="activate", group="testing") → 끝나면 deactivate
- 에디터 조작은 <에디터 담당 역할> 세션만 한다. 다른 세션은 코드만 고치고 필요한 에디터 작업을 보고서에 적는다.
Packages/manifest.json에 추가 · unity-mcp

놓는 위치 · Packages/manifest.json 의 dependencies 안에 한 줄 추가 (Package Manager → Add from git URL 과 같은 효과)

채울 것무엇을 넣나어디서 확인누가
#v10.0.0고정할 버전. 새 릴리스가 나오면 바꾼다unity-mcp ReleasesAI→직접
나머지기존 dependencies는 그대로 두고 이 줄만 추가—그대로
설치 후Window → MCP for Unity → Configure All Detected Clients 는 에디터에서 직접 클릭—직접
{
  "dependencies": {
    "com.coplaydev.unity-mcp": "https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.0.0"
  }
}
Codex 설정 · 공식 Unity MCP (config.toml)

놓는 위치 · ~/.codex/config.toml (Unity 공식 MCP를 쓸 때만. Unity 문서의 Claude Code 설정을 Codex 형식으로 옮긴 것)

채울 것무엇을 넣나어디서 확인누가
<HOME>사용자 폴더 절대 경로. 예: C:/Users/<이름>탐색기 주소창AI
<relay 실행 파일>~/.unity/relay/ 폴더 안의 실행 파일 이름 (운영체제별로 다름)~/.unity/relay/ 폴더AI
startup_timeout_secCodex 기본은 10초. 에디터 연결이 늦으면 늘린다Codex MCP 문서선택
unity-mcp(CoplayDev)를 쓰면이 파일 대신 Configure All Detected Clients 가 자동으로 설정한다—선택
[mcp_servers.unity-mcp]
command = "<HOME>/.unity/relay/<relay 실행 파일>"
args = ["--mcp"]
startup_timeout_sec = 20
Claude Code 설정 · 공식 Unity MCP (.mcp.json)

놓는 위치 · 프로젝트 루트의 .mcp.json (팀과 공유) 또는 claude mcp add 로 개인 설정

채울 것무엇을 넣나어디서 확인누가
<HOME>, <relay 실행 파일>위 Codex 설정과 같다~/.unity/relay/ 폴더AI
팀 공유 여부경로가 사람마다 다르면 .mcp.json 대신 claude mcp add (local 범위)로 각자 등록—직접
{
  "mcpServers": {
    "unity-mcp": {
      "command": "<HOME>/.unity/relay/<relay 실행 파일>",
      "args": ["--mcp"]
    }
  }
}
asmdef 예시 · Game.UI.asmdef

놓는 위치 · Assets/Scripts/UI/Game.UI.asmdef (Create → Scripting → Assembly Definition 으로 만들면 같은 파일이 생김)

채울 것무엇을 넣나어디서 확인누가
Game.UI, Game.Core실제 폴더·기능 이름으로Assets/Scripts 폴더 구조AI→직접
references이 코드가 쓰는 다른 어셈블리만. 서로 참조(순환)는 만들 수 없다using 문, 컴파일 에러AI
{
  "name": "Game.UI",
  "rootNamespace": "Game.UI",
  "references": ["Game.Core"],
  "autoReferenced": true
}
C# 예시 · 도메인 리로드 끈 상태의 static 리셋

놓는 위치 · static 상태를 가진 클래스마다 (AGENTS.md 규칙으로 AI가 지키게 함)

채울 것무엇을 넣나어디서 확인누가
ScoreCache, s_total예시 이름—그대로
적용 대상기존 코드의 static 필드·이벤트를 찾아 리셋 메서드 추가프로젝트 전체 검색AI
public static class ScoreCache
{
    static int s_total;

    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
    static void ResetStatics()
    {
        s_total = 0; // 도메인 리로드가 꺼져 있으면 플레이 시작 때 자동으로 0이 되지 않는다
    }
}

최근 변경 · v1.0 (2026-10-06)

초기 작성: 항목 10개, 설정·예시 파일 6개

기록

버전날짜구분항목이유근거
v1.02026-10-06—초기 작성: 항목 10개, 설정·예시 파일 6개

삭제된 항목이 없습니다.