BurningTimesAi/공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md

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

> **조직**: BurningTimes (구 NerdNavis 계승)
> **담당**: 클라이언트팀장
> **대상 원본**: 수상한잡화점 (Unity `6000.0.67f1`, 외부 레포 `FilGoodBandits/DeckBuilding`)
> **계승 대상**: EerieVillage (Unity `6000.3.13f1 LTS`, 2D PlatformerMicrogame 템플릿)
> **v2 갱신 (2026-05-08)**: §6 EerieVillage BT5-Dev 영역 신규 노하우 7종 추가 (발판 시스템 BT47~BT75 + 몬스터 시스템 BT76~BT109)

---

## 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`

---

## 6. EerieVillage BT5-Dev 영역 신규 노하우 (v2 추가, 2026-05-08)

> **대상**: BT5-Dev 발판 시스템 (BT47~BT75) + 몬스터 시스템 (BT76~BT109)
> **계기**: 본 PM 가설 누적 부정확 자인 28+23회 누적 → PD 근본 진단 채택 후 영구 마무리 도달
> **연관 헌법급 feedback**: `feedback_pm_root_diagnosis_priority` (2026-05-08 신설)

### 6-1. Tilemap cell 기반 측정 (Raycast 부정확 폐기)

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| 수평·수직 Raycast 측정 (BT80~BT106) | 절벽·벽 검출 | sprite·collider 영역 의존 부정확 누적 23회+ | Raycast 영역 = sprite·collider 정합 필수. 미정합 시 부정확 |
| `Tilemap.WorldToCell` + `HasTile` (BT107) | data 직접 사용 | PD 근본 진단 채택 즉시 영구 마무리 도달 | **Tilemap data 직접 사용 = 정확. 절벽·벽 검출 1순위** |
| footPos cell 영역 (BT109) | Capsule 발 위치 정합 | `footPos.y = bounds.min.y - 0.5f` = 발판 cell 영역 정확 | 발 자체 cell ≠ 발판 cell. -0.5f 오프셋 의무 |

### 6-2. KinematicObject body·transform 동시 set 의무

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| `transform.position` 단독 set (BT89~BT92) | 즉시 위치 변경 | KinematicObject `body.position` 미동기화 → 1 frame 후 원위치 복귀 | transform 단독 set 영역 = KinematicObject 영역 부정합 |
| `body.position` + `transform.position` 동시 set (BT93·BT96) | 양 영역 동기 | TriggerReverse 영역 정합 | **transform + body 동시 set 의무** |
| `velocity.x` 직접 set | 즉시 방향 전환 | FixedUpdate 영역 = `velocity.x = targetVelocity.x` 덮어씀 → 1 frame만 영향 | `control.move.x` 영역과 동시 set 의무 |

### 6-3. body.simulated = false (제자리 사망 영역)

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| `_collider.enabled = false` 단독 (BT104) | 충돌 차단 | gravity 적용 → 떨어짐 | collider만 차단 시 물리 영역 잔존 |
| `body.simulated = false` (BT105) | 물리 영역 전수 차단 | gravity X·충돌 X·제자리 사망 정합 | **죽은 Enemy 제자리 사망 영역 = body.simulated=false** |

### 6-4. AutoForeground vs PD Foreground 영역 분리

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| Foreground TilemapCollider 부착 (BT82) | 발판 충돌 | PD Foreground = 시각만 의도. 통로 막힘 | PD가 직접 그린 시각 영역 = 충돌 X 의도 |
| AutoForeground 신규 GameObject (BT47 R2 채택) | 자동 분류 결과 별도 분리 | Grid 자식·Tilemap·TilemapCollider·Layer 16·transform 동기화 | **시각 의도 ↔ 충돌 영역 분리. AutoForeground = 자동 분류 결과만 충돌** |

### 6-5. 측정 시점 — Awake < AfterSceneLoad < Start

| 시도 | 이유 | 결과 | 교훈 |
|------|------|------|------|
| Awake 시점 측정 (BT94 시도) | 가장 빠른 시점 | AutoForeground Tile data 미활성 → 측정 부정확 | Awake = scene 전수 활성 전 |
| `RuntimeInitializeOnLoadMethod(AfterSceneLoad)` 영역 | scene load 후 | AutoForeground 분류 후 시점 | AfterSceneLoad = Awake 후·Start 전 |
| Start 시점 측정 (BT97) | AutoForeground 분류 완료 후 | Tile data 활성 영역 측정 정합 | **AutoForeground·Tilemap data 의존 측정 = Start 시점 의무** |

### 6-6. Drop-Through Platform 표준 패턴 (발판 시스템 영구 채택)

| 영역 | 동작 | 교훈 |
|------|------|------|
| `JUMP_THROUGH_LAYER = 16` | AutoForeground·Foreground 통과 대상 Layer | Layer 기반 mask 제어 표준 |
| `dropThroughTimer (0.3초)` | Down + Jump 입력 시 Layer 16 mask 강제 OFF | 일시 mask OFF 패턴 |
| `jumpAscentTimer (0.4초)` | 점프 ascending·정점 영역 mask 강제 OFF | jitter 차단 의무 |
| `dropThroughJump` | `velocity.y = -0.5f` (즉시 낙하·IsGrounded=false 확보) | 즉시 효과 의무 |
| `UpdateContactFilterForDropThrough` | ascending·정점·Timer 활성 시 mask OFF / footHit 3점 Raycast | 발판 위 검출 안정화 |
| 밀림 강제 Drop-Through | 점프·낙하 중 + 수평 입력 + 발판 가장자리 일시 검출 → `dropThroughTimer` 강제 활성 | 가장자리 jitter 차단 |
| Down + Jump 발동 조건 | 발판(Layer 16) 위 footHit 검출 시만 (지면 위 = 일반 점프) | 분기 의무 |

### 6-7. PM 가설 누적 부정확 자인 패턴 (메타 영역)

| 사이클 | 본 PM 가설 누적 | PD 근본 진단 명시 시점 | 즉시 정합 도달 |
|--------|---------------|---------------------|--------------|
| 발판 시스템 (BT47~BT75) | 28회+ 가설 (Distance·Bounds·VisualBounds·PlatformEffector·STOMP_MIN_DY 등) | PD: "R2로 진행해줘" (BT66) | AutoForeground 분리 채택 |
| 몬스터 자동 patrol (BT80~BT109) | 23회+ 가설 (수평 Raycast·waitTimer·stuckTimer·EnemyWall·y 영역 고정 등) | PD: "절벽 체크 로직 잘못이 근본 원인" (BT107) | Tilemap cell 기반 측정 재설계 |
| 핵심 PD 명시 진단 4건 | "R2 진행"·"PatrolPath 제거"·"투명벽 삭제"·"절벽 체크 근본 원인" | 매번 본 PM 가설 3회+ 누적 후 명시 | 즉시 영구 마무리 도달 패턴 반복 |

**핵심 교훈**: 본 PM 가설 3회 이상 누적 부정확 자인 시점 = **가설 생산 즉시 중단 + PD 근본 진단 능동 수령 의무**. 헌법급 feedback `feedback_pm_root_diagnosis_priority` 정합.

---

## 7. v2 추가 PM 보고 안건

- **BT5-Dev 좁은 영역 Enemy 잔여**: PD 보고 (BT109 후) "몬스터들 중 일부(이동 가능 영역이 좁은 경우)를 제외하면 내가 원하는대로 움직이고 있어". 좁은 영역 (시작 위치 ↔ 절벽 거리 매우 작음) 패턴 부정합 잔존. PD 재요청 시 본 PM 후속.
- **Unity 측정 자료 카탈로그 보유 의무**: Tilemap·Physics2D·Bounds·KinematicObject·Rigidbody2D·이벤트 시점 영역별 정합 카탈로그 본 PM 능동 보유 의무 (`feedback_pm_root_diagnosis_priority` §3 정합)