---
type: 실행가이드
from: 개발팀장
to: 기획팀장·밸런스기획자
date: 2026-04-20
subject: 기획팀용 Unity MCP 시뮬 실행 가이드 v1 (선행 조건 3)
status: 발행
reference:
  - 프로젝트/수상한잡화점/시뮬레이터/01_시뮬레이터_아키텍처_v1.md
  - 프로젝트/수상한잡화점/시뮬레이터/02_시나리오_JSON_스키마_v1.md
  - 프로젝트/수상한잡화점/시뮬레이터/03_결과_JSON_포맷_v1.md
  - 프로젝트/수상한잡화점/시뮬레이터/04_MCP_호출_스니펫_v1.md
---

# 기획팀용 Unity MCP 시뮬 실행 가이드 v1

## 0. 본 가이드 목적

기획팀(특히 밸런스기획자)이 Phase 3 재개 시 **Unity MCP EditMode 기반 시뮬을 독립적으로 실행**할 수 있도록 환경 준비·시나리오 작성·실행·결과 해석·오류 대응 표준 절차 제공. `시뮬레이터/01~04_*.md` 설계 문서의 **기획팀 실무 관점 축약본**.

> **선행 조건 2(실측 검증 리포트 v1) 확정 후 본 가이드 §3 예시 결과값이 실측 기준으로 갱신됩니다.**

---

## 1. 환경 준비 (세션 시작 시 1회)

### 1-1. Unity Editor 기동
- Unity Editor로 수상한잡화점 프로젝트 오픈
- 콘솔에 컴파일 에러 없는 상태 확인
- `Assets/Sim/NerdNavis.Sim.asmdef` 로드 확인 (Project 창)

### 1-2. MCP 연결 확인
- Claude Code 세션에서 `mcp__unity-mcp__*` 도구 사용 가능 여부 확인
- 간이 확인: `mcp__unity-mcp__manage_editor` 호출하여 Editor 상태 수신

### 1-3. 연결 실패 시
- 가이드 §6 "자주 발생 오류 TOP 5" 참조
- 해결 불가 시 `공유/소통/기획팀→개발팀/{YYYY-MM-DD}_REQ{번호}_MCP연결이슈.md` 발행

---

## 2. 시나리오 JSON 작성

### 2-1. 기본 구조 (`02_시나리오_JSON_스키마_v1.md` 참조)

```json
{
  "scenario_id": "anchor_pc6001",
  "seed": 12345,
  "actors": [
    {
      "id": "pc_6001",
      "type": "pc",
      "maxHP": 100,
      "attackDmg": 1.05,
      "attackCoolTime": 1.0
    },
    {
      "id": "mob_basic",
      "type": "monster",
      "maxHP": 6.0,
      "attackDmg": 0.5
    }
  ],
  "max_ticks": 600
}
```

### 2-2. 필수 필드

- `scenario_id`: 고유 식별자 (재검증 로그에 활용)
- `seed`: 결정론 보장용 시드
- `actors[]`: PC·몬스터 최소 정보 (HP·공격·쿨타임)
- `max_ticks`: 무한 루프 방지 상한

### 2-3. 저장 위치

- 기획팀 작업: `프로젝트/수상한잡화점/기획/시뮬시나리오/{scenario_id}.json`
- Unity MCP는 절대 경로 또는 Assets 하위 상대 경로로 전달

---

## 3. 실행 — `execute_code` 호출

### 3-1. 표준 스니펫 (`04_MCP_호출_스니펫_v1.md` 축약)

```csharp
// mcp__unity-mcp__execute_code 전달용
using NerdNavis.Sim;

var runner = new SimulationRunner();
var result = runner.Run("Assets/Sim/Scenarios/anchor_pc6001.json");
var json = UnityEngine.JsonUtility.ToJson(result, true);
System.IO.File.WriteAllText("Assets/Sim/Results/anchor_pc6001_result.json", json);
return json;
```

### 3-2. 배치 실행 (스윕)

파라미터 N개 배열을 내부 루프로 반복:

```csharp
var results = new List<SimulationResult>();
foreach (var path in scenarioPaths) {
    results.Add(new SimulationRunner().Run(path));
}
```

### 3-3. 반환 형식

- 기본: JSON 문자열 (stdout)
- 파일: `Assets/Sim/Results/{scenario_id}_result.json`

---

## 4. 결과 JSON 해석 (`03_결과_JSON_포맷_v1.md` 축약)

### 4-1. 핵심 필드

```json
{
  "scenario_id": "anchor_pc6001",
  "total_ticks": 342,
  "actors_final": [
    { "id": "pc_6001", "hp_final": 45.2 },
    { "id": "mob_basic", "hp_final": 0, "is_dead": true }
  ],
  "metrics": {
    "dps_pc_6001": 1.048,
    "ttk_mob_basic": 5.68
  }
}
```

### 4-2. 기획 가정 vs 실측 대조 표

| 항목 | 기획 가정 | 실측 (MCP) | 오차 | 판정 |
|------|---------|---------|------|-----|
| PC 6001 DPS | 1.05 | (실측) | (%) | 10% 이내? |
| 몬스터 TTK | 5.7s | (실측) | (%) | 10% 이내? |

**오차 10% 이내** → 기획 가정 채택. **초과** → 개발팀에 `Assets/Sim/Models/` 재조정 REQ 발행 + Day 8~10 이슈 통합 재논의 이관.

### 4-3. 재검증 로그 기록 형식 (`Phase3_재개준비_체크리스트_v1.md §5` 명명 규칙)

재검증 결과는 `재검증보고_Phase0_1_2_v1.md`·`Phase3_성장요소기여도_v2.md` 등 SOT에 다음 형식으로 append:

```markdown
## [항목 #N] 재검증 결과

- 기획 가정: (값)
- Unity MCP 실측: (값)
- 오차: (%)
- 판정: (채택 / 재조정 필요)
- 실행 일시: YYYY-MM-DD HH:MM
- 시나리오 ID: (scenario_id)
- 결과 JSON 경로: (path)
```

---

## 5. 검증 체크리스트 (매 실행마다)

- [ ] Unity Editor 콘솔 에러 없음
- [ ] MCP `execute_code` 호출 성공 (반환값 수신)
- [ ] 결과 JSON 구조 정상 (`scenario_id`·`total_ticks`·`actors_final`·`metrics` 존재)
- [ ] 동일 시드 2회 실행 결과 일치 (결정론 간이 확인)
- [ ] 기획 가정 vs 실측 오차 기록

---

## 6. 자주 발생 오류 TOP 5

| # | 증상 | 원인 | 해결 |
|---|------|-----|-----|
| 1 | `mcp__unity-mcp__execute_code` 호출 실패 | MCP 서버 미연결 | Unity Editor 재기동 + MCP 재연결 (개발팀 에스컬레이션) |
| 2 | `NerdNavis.Sim` 어셈블리 미로드 | Editor-only 속성 충돌 | `Assets/Sim/NerdNavis.Sim.asmdef` 재임포트 |
| 3 | 결과 JSON `actors_final[].hp_final` 음수 | DamageCalc 감소 하한 누락 | 개발팀에 REQ (`Assets/Sim/Models/DamageCalc.cs` 하한 클램프 추가) |
| 4 | 동일 시드 2회 실행 결과 상이 | 난수 상태 오염 | 시나리오 JSON `seed` 명시 여부 재확인 |
| 5 | `total_ticks == max_ticks` 무한 루프 의심 | 전투 종료 조건 미달 | 시나리오 몬스터 HP·공격력 재조정 or 상한 확대 |

---

## 7. 에스컬레이션 경로

| 상황 | 대상 | 채널 |
|------|-----|-----|
| MCP 시뮬 실행 실패 | 개발팀 클라이언트팀장 | `공유/소통/기획팀→개발팀/{YYYY-MM-DD}_REQ{번호}_MCP연결이슈.md` |
| 오차 10% 초과 지속 | 개발팀 클라이언트팀 | `공유/소통/기획팀→개발팀/{YYYY-MM-DD}_REQ{번호}_시뮬모델재조정.md` (REQ 템플릿: `공유/소통/기획팀→개발팀/REQ-템플릿_밸런스수치.md`) |
| 검증 축·범위 재해석 필요 | 개발팀장 | 로드맵 v2 개정 요청 |
| 테이블 변경 필요 (PD 승인 전제) | 총괄PM → PD님 | 기획팀장 상신 |

---

## 8. 다음 단계 (Phase3 재개준비 체크리스트 §2)

본 가이드로 실행 환경 확보 후:
- **Day 1-3 간이 실행 테스트** (앵커 시뮬 1회 실행, 실 빌드 결과와 대조)
- **Day 2~3 Phase 0~2 재검증 6건** (`재검증보고_Phase0_1_2_v1.md` 작성)
- **Day 4~7 성장 요소 기여도 6건** (`Phase3_성장요소기여도_v2.md` 신규 작성)

---

## 참조

- `프로젝트/수상한잡화점/시뮬레이터/01_시뮬레이터_아키텍처_v1.md` (독립 어셈블리 설계)
- `프로젝트/수상한잡화점/시뮬레이터/02_시나리오_JSON_스키마_v1.md` (입력 스키마)
- `프로젝트/수상한잡화점/시뮬레이터/03_결과_JSON_포맷_v1.md` (출력 스키마)
- `프로젝트/수상한잡화점/시뮬레이터/04_MCP_호출_스니펫_v1.md` (상세 스니펫)
- `공유/소통/개발팀→기획팀/2026-04-20_Unity_MCP_실측검증_리포트_v1_스켈레톤.md` (선행 조건 2)
- `공유/소통/기획팀→개발팀/REQ-템플릿_밸런스수치.md` (REQ 템플릿)
