# 클라이언트팀장 시행착오 아카이브 v1

> **조직**: BurningTimes (구 NerdNavis 계승)
> **담당**: 클라이언트팀장
> **대상 원본**: 수상한잡화점 (Unity `6000.0.67f1`, 외부 레포 `FilGoodBandits/DeckBuilding`)
> **계승 대상**: EerieVillage (Unity `6000.3.13f1 LTS`, 2D PlatformerMicrogame 템플릿)

---

## 1. 개요 — 핵심 교훈 7건

1. **Unity MCP 편집 = 6단계 표준 불가침**: `apply_text_edits`/`script_apply_edits`는 Read-then-Edit 관성 미발생. SHA→Read→백업→commit→편집→검증
2. **Unity 프로젝트는 외부 git 레포**: 조직 레포와 분리. 작업 전 `git fetch && git status` 선행(C30)
3. **시뮬레이션 = MCP EditMode가 정답**: Headless 도메인 추출은 재빌드·이원화 부담. `execute_code` + EditMode로 Actor.cs 실클래스 직접 호출이 단일 SOT
4. **핫리로드 = hook 기반 `.live/` 증분 주입**: `@import`·`/compact`·`.claude/rules/`는 세션 중 갱신 불가. UserPromptSubmit hook + SHA1 diff만 유효
5. **CLI 병렬은 `--worktree` 격리**: 동시 수정 가능성 있으면 워크트리 강제. 같은 디렉토리 다중 세션은 덮어쓰기·git 이력 혼란
6. **기획팀 협업 = 정기 실측 교차 검증**: 문서-실체 괴리(부재 스크립트·Spine 추가·Res_Addr 확장·xlsm SOT 이중화)는 정기 실측만 감지
7. **BT.Framework Tier 1 16/16은 차기부터 적용**: 수상한잡화점 미도입 확정(P29 원칙 A). 범용 패턴 추출만 수행

---

## 2. 시도한 방법·이유·결과·교훈

### 2-1. Unity MCP 편집 표준 워크플로우 (2026-04-20)

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| `script_apply_edits` 직접 치환 | PM 프롬프트 "C6-1 백업"은 있었으나 MCP 구체 수단(`manage_script read`→저장) 미명시 | 편집·검증 정상이나 `.bak_*` 분리 누락 → C6-1 위반. 3중 복구(보고서·역방향·undo) 실질 손실 0 | MCP 원자 편집은 Read-then-Edit 관성 미발생. 절차 명문화 불가침 |
| 백업 경로 표준화 | PC 독립·git 추적·포맷 통일 | `공유/개발팀_백업/{프로젝트}/{원본명}.bak_{YYYYMMDD_HHMM}.{확장자}` 단일 SOT. 긴급 시 `git stash push -u` | 조직 레포 내 고정. 절대 경로·Unix timestamp 금지 |

### 2-2. 시뮬레이션 — MCP EditMode 단일 SOT 확정

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| 도메인 Headless 추출(netstandard) | Python-Unity 결과 불일치 해소 + 엔진 완전 분리 | 대형 스크립트 리팩터링·재빌드 동기화 부담 급증 | 추출 자체가 근본 아님. 두 구현 유지비 0이 정답 |
| `execute_code`(EditMode) 주력 + Batch Mode 보조 | Editor 내 C# Eval → 실클래스 직접 호출. `IRandomSource`·`IClock`·`ITickDriver`·`IBattlePresenter`·`ITableLoader` 등 stub DI | 기존 시뮬 SOT 100% 재활용. "단일 SOT = Unity 프로젝트 자체" | Unity 전제면 EditMode가 결정론·유지비·접근성 3축 우위 |

### 2-3. 핫리로드 대안 → `.live/` 증분 주입 (C34 헌법급 승격)

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| CLAUDE_LIVE.md 공용 파일 | 세션 중 갱신·참조 | `@import`·`.claude/rules/`는 세션 시작 1회. SessionStart hook은 재시작 시만. UserPromptSubmit hook + SHA1 diff만 유효 | 동적 갱신은 hook 외 불가 |
| SessionStart 전량 + UserPromptSubmit 변경 감지 | 토큰 최소 + 매 턴 반영 양립 | 변경 없는 턴 0, 변경 시 ~1,200 토큰. 한도 이내 | C14 실증. 해시 비교가 핵심 |
| `.live/` 증분 주입 → C34 중앙 Junction | worktree 격리로 주입 실패 실증 | 조직 핵심 자산. 설정·규칙·에이전트 9종 대상. PC 내 모든 세션 공유 비용 0 | worktree 경계 끊김은 생존 이슈. 중앙 저장소 + junction 필수 |

### 2-4. 콘솔 병렬 · PM 보고 구조

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| CLI `--worktree` 격리 | 독립 파일시스템 + 독립 브랜치 | 충돌 없음. 완료 후 main merge | 동시 수정 가능성 있으면 워크트리 강제 |
| PM에 모든 작업 push 보고 | C13 완전 준수 | 토큰 폭증·C14 위반·PM 세션 오염 | 이벤트 드리븐. 상태 전환·타 부서 영향·헌법급만 push |

### 2-5. Editor 의존 분리 · 모바일 UI 패턴 · 기획팀 협업 · BT.Framework

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| Editor 의존 분리 원칙 | 런타임 코드에 `UnityEditor` 네임스페이스 혼입 시 빌드 실패 | `#if UNITY_EDITOR` 가드 + Editor 폴더 분리 | 모든 재사용 모듈은 Editor 무관 전제. Framework 이식 시 필수 |
| UITouchHandler·SafeArea·BackKey 패턴 | 모바일 UI 공통 요구 | 터치 이벤트 래핑·노치 대응·안드로이드 백키 통합 처리 3종 범용 패턴 추출 | 차기 프로젝트 Tier 2·3 후보. Framework 편입 검토 |
| 기획팀 유니티 교차 검증 | 문서 vs 실체 유효성 | 정기 실측으로 부재 스크립트·Spine 추가·Res_Addr 확장·xlsm SOT 이중화 감지 | 정기 실측 필수 |
| BT.Framework Tier 1 16/16 완결 | 차기 조직 자산 | Log·ServiceLocator·CoroutineRunner·MonoSingleton·EventBus·Observable{List,Dict,Queue}·ObjectPool·Factory·DataTable·Attribute3·Util6 + NUnit 28+ | Tier 1은 게임 없이 완결. 2·3은 게임 진행과 축적 |
| 수상한잡화점 Framework 도입 | 자체 코어 사용 중 | P29 원칙 A — 미도입. 범용 패턴 추출만 | 신 프레임워크는 차기 출발 시점이 최적 |
| 싱글톤 4종 → `MonoSingleton<T>` + 옵션 | 재작성 기회 중복 해소 | 오탈자 수정(`WaitCahe→WaitCache`) · 네임스페이스 통일(`BurningTimes.*`) | 재작성은 오탈자·중복 통합 기회 |

---

## 3. BT 착수 시 체크리스트 (EerieVillage · Unity 6000.3.13f1 LTS · 2D PlatformerMicrogame)

**Unity 작업 전 필수**: `${UNITY_PROJECT_ROOT}` `git fetch && git status` (C30) · `paths.local.json` 경로 등록 · MCP Stdio(6400) 연결 · 표준 워크플로우 6단계 준수

**Unity MCP 편집 6단계(불가침)**:
1. `get_sha` — 편집 전 SHA 확보
2. `manage_script(read)` — 원본 내용 Read
3. `공유/개발팀_백업/EerieVillage/{원본명}.bak_{YYYYMMDD_HHMM}.{확장자}` 저장
4. 백업 commit (긴급 시 `git stash push -u`)
5. `apply_text_edits`/`script_apply_edits` (`precondition_sha_256` 지정)
6. SHA 재확인 + `refresh_unity` + `read_console` error 0

**BT.Framework 도입 배선**:
- `manifest.json`에 `"com.nerdnavis.framework": "<Gitea URL>#<tag>"` (C안)
- Framework 동시 개발자는 로컬 `file:../BT.Framework` (H1)
- 2D PlatformerMicrogame 템플릿 샘플은 `EerieVillage/Samples/` 격리
- EventBus·ObservableList·DataTable·ServiceLocator 4종 출발점 배선

**Editor 의존 분리**: 런타임 어셈블리에 `UnityEditor` 직접 참조 금지 · `#if UNITY_EDITOR` 가드 또는 Editor 폴더 분리 · Framework 전 모듈 Editor 무관 전제

**모바일 UI 기반 패턴**: UITouchHandler(터치 래핑) · SafeArea(노치 대응) · BackKey(안드로이드 백키 통합) 3종 Tier 2·3 편입 검토

**시뮬레이션**: `execute_code`(EditMode) 주력 · Headless 추출안 재도입 금지 · `IRandomSource`·`IClock`·`ITickDriver` DI · 동일 시드 비트 단위 동일 결과 검증

**기획팀 협업 주기 실측**: 산출물 참조 경로·파일 실존·최근 수정일 · xlsm SOT 단일화(이중화 시 즉시 문의) · 스크립트·씬·Res_Addr 변동 감지

---

## 4. PM 보고 안건

- **BT.Framework 차기 도입 경로**: C안(UPM Git URL) + H1(로컬 file:) 배선 확정. Gitea 태그 정책·PD NAS Git 접근 방식 최종 확정. 2D PlatformerMicrogame 템플릿과 공존 방식 설계(Samples 격리)
- **Editor 상시 기동 의존**: EditMode `execute_code`는 Unity Editor 기동 + MCP Stdio 전제. 대량 배치(1만+)는 BatchMode 병렬 경로 별도. 재연결 자동화 스크립트 검토
- **Unity 전제 정합성**: MCP 방향은 Unity 전제 위 재활용 한정. 비-Unity 엔진 이관 시 재추출 필요. EerieVillage·차차기 Unity 전제 PD 재확인 권고
- **모바일 UI 패턴 Framework 편입**: UITouchHandler·SafeArea·BackKey 3종 Tier 2·3 배치 검토

---

## 5. 참조 원본 파일 목록

**Unity MCP 편집 워크플로우**
- `공유/개발팀_자산/Unity_MCP_편집_표준_워크플로우_v1.md`
- `공유/소통/개발팀→PM/2026-04-20_C6-1_재발방지_Unity_MCP_워크플로우.md`
- `memory/org/feedback_c6_backup_before_edit_violation.md`

**기술 검토 (2026-04-16~17)**
- `공유/소통/완료/2026-04-16_콘솔병렬실행_기술검토_개발팀.md`
- `공유/소통/완료/2026-04-16_핫리로드대안_기술검토_개발팀.md`
- `공유/소통/완료/2026-04-16_하이브리드구조_개발실의견.md`
- `공유/소통/완료/2026-04-16_유니티프로젝트_점검_기획팀.md`
- `공유/소통/완료/2026-04-17_Unity_MCP_시뮬레이션_기술검토_개발팀.md`

**BT.Framework 설계**
- `프로젝트/코어프레임워크/01_아키텍처_개요_v1.md`·`03_배포방식_안건_v1.md`·`04_Tier1_3종_상호작용_설계_v1.md`

**대화로그**: `공유/대화로그/코어프레임워크/2026-04-16.md`·`2026-04-17.md`·`2026-04-18.md`