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

---
type: 시행착오_아카이브
scope: 개발팀_통합
author: 개발팀장
date: 2026-04-21
version: v1
project_source: 이전 프로젝트 (NerdNavis, 2025-2026)
project_target: EerieVillage (Unity 6000.3.13f1 LTS, 2D PlatformerMicrogame, BurningTimes, 2026~)
---

# 개발팀 통합 시행착오 아카이브 v1 — 서버·클라이언트·QA 총괄 관점

## 1. 개요 — 핵심 교훈 8건 요지

1. **C11(개발 관점 3축) 판정 선행** — 자원 효율성·코드 직관성·범용성 3축 미통과 설계는 은폐 금지, C3에 따라 제기.
2. **시뮬레이터 이원화는 조직 생존급 리스크** — Python·Unity C# 2언어 동시 유지 시 메커닉 SOT 불일치·밸런스 신뢰도 붕괴. Unity MCP EditMode 단일 SOT로 근원 해결.
3. **Unity MCP 편집 6단계 표준 워크플로우** (SHA 확보→원본 Read→백업→commit→편집→검증) 준수 의무. C6-1 재발 방지 SOT: `공유/개발팀_자산/Unity_MCP_편집_표준_워크플로우_v1.md`.
4. **Agent 호출 시 절대 경로 하드코딩 금지(C34-11)** — worktree 경계 이탈 실증. `git rev-parse --show-toplevel` 기반 상대 경로 의무.
5. **worktree-local 저장 자산 생존급 위험(C34-15)** — 3종 중앙 Junction(`.live/`·`memory/org/`·audit). 신규 저장소·hook 설계 시 5문항 통과 의무.
6. **BT.Framework 현 프로젝트 비투입·조직 자산 계승(P29)** — Tier 1 실증 자산 EerieVillage부터 적극 활용. 특수 로직 vs 범용 모듈 경계 초기 분리.
7. **서버 Critical 보안 3종 복원 계획 유지** — IAP 영수증·암호화 키·전투 연산. 상세는 `개발_서버팀장_v1.md`. 서버팀 가동 시점 복원 전략 수립.
8. **QA 게이트(P14) — 빌드 오류·콘솔 에러 잔존 종료 금지** — 회귀 검증은 동일 경로 재현 포함. "임시로 돌아가는 코드"는 C2·C11 동시 위반.

---

## 2. 시도한 방법·이유·결과·교훈 (4필드 표)

### 2-1. 아키텍처·설계

| 시도한 방법 | 이유 | 결과 | 교훈 |
|------------|------|------|------|
| Python 시뮬(다종) + Unity C# 실코드 병행 | 기획팀 숙련도·빠른 반복 | 메커닉 SOT 불일치 · 기획 가정값 vs 실코드 수치 괴리 반복 | Unity MCP EditMode 단일 SOT로 일원화. Python은 참조 구현 + 자동 동기화 검증 테스트 의무 |
| 카드·아이템·유닛 개별 스크립트 구현 | 특수 효과 구현 편의 | 신규 추가 = 코드 수정 필요 · 시너지 조합 폭증 대응 불가 | 데이터 드리븐 아키텍처 강제(enum + 파라미터 JSON). "신규 추가가 JSON 한 줄로 끝나는가?" 핵심 질의 |
| 프로젝트 내부에 범용 네임스페이스 혼재 | 초기 분리 부족 | 프로젝트 특수 vs 범용 모듈 경계 모호 · 차기 프로젝트 재활용 곤란 | P29 코어 프레임워크 독립 레포 분리. 현 프로젝트 비투입, 추출 대상만 식별 |
| Tier 1 전 모듈 단일 라운드 일괄 구현 시도 | 빠른 완결 | 상호작용 재검증 필요 · 아키텍처 부채 우려 | 라운드 완결 아카이브 원칙 정착(`feedback_log_round_completion.md`) |

### 2-2. 서버·보안 (상세는 `개발_서버팀장_v1.md`)

| 시도한 방법 | 이유 | 결과 | 교훈 |
|------------|------|------|------|
| 단일 백엔드 직접 의존 | 초기 속도 | 백엔드 교체 경로 부재 · 병행 SDK는 설정 누락으로 비활성 | INetworkService 추상화 선행. 허브 패턴은 유지하되 인터페이스로 교체 가능 구조 |
| 전투·보상 연산 100% 클라이언트 | 내부 연산 편의 | 변조 방어 불가 · 랭킹·이벤트 보상 악용 경로 | 스테이지 클리어 판정·보상 지급 최소 서버 재연산 P0. 전체 재연산은 점진 확장 |
| 암호화 키 소스 평문 하드코딩 · IL2CPP 의존 | 빌드 난독화 신뢰 | 메모리 덤프로 추출 가능 · 사실상 무의미 | 런타임 유도(디바이스ID 해시 혼합) + 서버 페이로드 HMAC 서명 + 키 회전 |
| IAP 영수증 검증 주석처리 | 서버팀 미가동 대기 | 결제 우회 경로 오픈 · 블로커급 | "보류" 상태라도 메모리 SOT(`project_shop_security_pending.md`) + PD 지시 로그 보류 사유·사후 조치 기록(P19) |

### 2-3. 코어 프레임워크(BT.Framework)

| 시도한 방법 | 이유 | 결과 | 교훈 |
|------------|------|------|------|
| 코어 설계 문서를 프로젝트 R&D 경로에 배치 | 작성 편의 | 비투입 방향 확정 후 "프로젝트 산출물"로 오인 유발 | `프로젝트/코어프레임워크/` 단일 SOT. 구 경로는 "대체됨" 표식 |
| `Convert.ChangeType` 캐시 방식 Enum 변환 | BCL 표준 | 박싱 발생·핫패스 성능 저하 | `Unsafe.As<,>` 제로-박싱 전환. EnumToInt 단일 SOT |
| UnityEngine 의존 허용 (일부 Util) | Unity 편의 | 서버·배치 재사용 불가 · C11 범용성 위반 | Tier 1은 순수 BCL 의존만. Unity 의존 모듈은 별 asmdef 분리 |
| 외부 파서/직렬화 라이브러리 도입 검토 | 완결성 | Tier 1 외부 의존 최소 원칙 위반 · PC 독립 설치 리스크 | 필수 핵심만 자체 구현 + Unity 기본 래퍼. 한계는 명시 후 호출자 우회 안내 |
| 키 구분자 혼용(`_`·`:`) | 관례 | 프로젝트 간 조회 실패 경험 | `:` 단일 표준 강제 |

### 2-4. 개발 인프라·운영·Agent 경계

| 시도한 방법 | 이유 | 결과 | 교훈 |
|------------|------|------|------|
| `.live/` 더미를 레포 내부 저장 | 단순화 | worktree마다 물리 격리 · 세션 간 실시간 공유 실패 | `$HOME/.claude/nerdnavis-live/` 중앙 저장 + worktree junction (C34-3) |
| `memory/org/`를 junction만으로 관리 | 중앙화 편의 | Windows core.symlinks·한국어 경로·clone 후 접근 불가 | 레포는 실체 디렉토리 유지 + sync 4계층 양방향 동기화 (C34-16) |
| Agent 프롬프트에 절대 경로 지정 | 호출 편의 | worktree 경계 이탈 · main 체크아웃 파일 생성 실증 | cwd 상대 경로 의무 + `git -C` 교차 확인 (C34-11) |
| 빌드 오류·콘솔 에러 잔존 PR 머지 | 속도 우선 | 회귀 버그 빈발 · QA 비용 누적 | P14 QA 게이트: 에러 0 원칙. 회귀 검증 동일 경로 재현 포함 |
| 서브에이전트 인용을 PM이 직접 작성(역할 연기) | 편의 | C23 위반 · 조직 신뢰 훼손 | Task 도구 실제 호출 결과만 인용. 미확인은 "미확인" 태그 |
| 완료 후 PD 지시 로그 갱신 누락 | 작업 우선 | 다른 세션 "진행중" 오인 | C27·C29-4 동기화 4종 동시 수행 (PD 로그·대화로그·소통 채널·Live 더미) |
| 설계 문서 참조만 남기고 본문 미작성 | 속도 | "유령 문서" 발생 · P18 위반 | 참조 시점 즉시 작성 착수 또는 "작성 예정(담당·재개 트리거)" 명시 |
| 수치 변경 시 단일 SOT만 업데이트 | 단일 작업 수행 | 다른 SOT 기획 가정값 유지 · 괴리 재발 | 수치 확정 시 "해당 수치 등장 모든 SOT 전수 grep" 체크리스트 편입 |

---

## 3. BT 조직 착수 시 체크리스트 (개발팀장 기준)

### 3-1. 세션 시작 직후 (C10-1·C16-4·C30)
- [ ] 조직 레포 + Unity 프로젝트(`${UNITY_PROJECT_ROOT}`) + BT.Framework 레포 각각 `git fetch && git status`
- [ ] `공유/PD_지시_트래킹/개발팀_PD_지시_로그.md` 활성 테이블 전수 Read
- [ ] `공유/대화로그/EerieVillage/`·`공유/대화로그/코어프레임워크/` 최근 2일 Read

### 3-2. 신규 기능·시스템 설계 착수 전
- [ ] C11 3축 판정 (자원 효율성·코드 직관성·범용성) 자문
- [ ] "신규 {카드·적·아이템·이벤트} 추가가 JSON 한 줄로 끝나는가?" 데이터 드리븐 확인
- [ ] 프로젝트 특수 vs 범용 모듈 경계 명시 (범용은 BT.Framework 추출 대상 식별)
- [ ] P18 설계 문서 선행 작성 (배경·대안·구현 가이드·검증·변경 이력 5요소)
- [ ] 기획 요청이 C11과 충돌 시 C3에 따라 우려 즉시 제기

### 3-3. Unity 편집·서버 연동·Agent 호출 전
- [ ] Unity MCP 편집 시 6단계 표준 워크플로우 준수 + 백업 `공유/개발팀_백업/EerieVillage/{원본}.bak_{YYYYMMDD_HHMM}.{ext}` + `precondition_sha_256` + 편집 후 `get_sha` 재확인 + 콘솔 에러 0 검증
- [ ] 서버 연동: 전투·재화·IAP·랭킹·보상 영역 식별 → 권한 표 갱신 → Critical 3종 재발 체크(`개발_서버팀장_v1.md`) → 백엔드 추상화(INetworkService) 선행
- [ ] Agent 호출: 프롬프트에 "cwd 기준 상대 경로 의무" 명시(C34-11) + `$(git rev-parse --show-toplevel)` 기준 경로 + 응답 수령 직후 `git -C <레포루트> status` + 본 worktree `git status` 병행
- [ ] 신규 공용 저장소·hook·설정 도입 시 C34-15 worktree 경계 5문항 통과

### 3-4. 작업 완료 시 (C29-4 동기화 4종)
- [ ] PD 지시 로그 상태 갱신 (완료 아카이브 즉시 이동 + 즉답 접두)
- [ ] `공유/대화로그/{프로젝트}/YYYY-MM-DD.md` 엔트리 추가 (결정·설계는 "기각안" 필드 필수)
- [ ] 소통 채널 `status: 완료` + `공유/소통/완료/` 이동
- [ ] `.live/` 더미 기록 + 수치 변경 시 "해당 수치 등장 모든 SOT 전수 grep"

---

## 4. PM 보고 안건 (특이사항)

1. **BT.Framework Tier 1→Tier 2 진입 경계** — Tier 1 자산 EerieVillage 착수부터 적극 활용. Tier 2(Network·Persistence·UI) 진입 조건을 요구사항과 연계. P29 원칙.
2. **서버 Critical 3종 복원 계획** — 서버팀 가동 시점에 이전 프로젝트 보류분(IAP·AES·전투 연산) 복원 전략 PD 사전 보고. 상세: `개발_서버팀장_v1.md`.
3. **Unity MCP 워크플로우 v1 적용 범위** — BT.Framework 편집 명시 적용. 씬·프리팹(비스크립트) 미포함. v2 확장 PD 결정.
4. **시뮬레이터 이원화 재발 방지** — EerieVillage 착수부터 Unity MCP EditMode 단일 SOT. Python 시뮬은 참조 구현 한정 + 동기화 검증 테스트 의무화 PD 승인 안건.
5. **PC 독립 셋업 신 PC 합류 프로토콜** — `setup_*` + `verify_setup` 3축 검증 의무. 실패 시 조직공지 이슈화.
6. **dev-auditor 모드 A·B 정착** — 착수 초반 모드 A(중요 기술 결정) 호출 빈도 상향으로 학습 데이터 축적.

---

## 5. 참조 원본 파일 목록 (감사 재현 가능)

### 5-1. 동일 시행착오 아카이브
- `공유/조직자산/시행착오_아카이브/개발_서버팀장_v1.md` (서버 Critical 3종·백엔드 세부 SOT)
- `공유/조직자산/시행착오_아카이브/개발_클라이언트팀장_v1.md`

### 5-2. 코어 프레임워크 (BT.Framework)
- `프로젝트/코어프레임워크/01_아키텍처_개요_v1.md`·`02_추출대상_v1.md`·`03_배포방식_안건_v1.md`·`04_Tier1_상호작용_설계_v1.md`
- `코어코드/BT.Framework/Runtime/Core/` 전체

### 5-3. 이전 프로젝트 개발 산출물 (상세 참조)
- `프로젝트/수상한잡화점/개발/01~13_*.md`

### 5-4. 조직 자산·표준 워크플로우
- `공유/개발팀_자산/Unity_MCP_편집_표준_워크플로우_v1.md`
- `공유/개발팀_백업/` (원본 백업 SOT)

### 5-5. feedback 메모리 (재발 방지 SOT)
- `feedback_agent_path_boundary.md` — Agent 절대 경로 유출
- `feedback_worktree_isolation.md` — worktree 경계 5문항 체크
- `feedback_memory_sync_overwrite.md` — memory sync 덮어쓰기
- `feedback_c6_backup_before_edit_violation.md` — Unity MCP 백업 누락
- `feedback_log_round_completion.md` — 라운드 완결 아카이브
- `feedback_dev_auditor_*.md` — 개발 감사 실증
- `project_shop_security_pending.md` — Critical 3종 보류 SOT

---

*본 아카이브는 BurningTimes 조직이 EerieVillage 및 차기 프로젝트 착수 시 동일 시행착오 반복 방지·검증된 방법 재활용을 위한 개발팀 통합 관점 SOT. PD 지시 2026-04-21 "조직 자산 계승" + "불필요 부분 제외" 이행 산출물.*