11 KiB
03. NerdNavis.Framework 배포 방식 안건 (OI-2)
작성자: 개발실장 버전: v1 (2026-04-15 재작성) 문서 성격: PD님 의사결정 안건서. 권장안 + 근거 + 후속 조치 근거 규칙: 🌟 헌법 제1원칙 (조직 비전 목표 1·2·3), C14(토큰 최소화), C15(일정 배제), C18(공유 완료 기준), C19(승인 범위 엄격 해석)
🚨 본 안건의 목적·용도·범위·비목적
| 축 | 내용 |
|---|---|
| 목적 | NerdNavis.Framework(UPM 패키지 com.nerdnavis.framework)의 물리적 배포·참조 방식을 결정 가능한 형태로 안건화한다 |
| 용도 | PD님 의사결정 1회로 OI-2 종결. 결정 후 Framework 레포 태그 정책 + Unity 프로젝트 참조 배선 + 신PC 셋업 절차가 일관되게 정의됨 |
| 범위 | 배포 방식(A/B/C + 하이브리드) 비교 · 권장안 · 선결 조건 · 후속 조치 · 열린 결정 항목 |
| ❌ 비목적 | ① 수상한 잡화점 투입 안건이 아님 — 수상한 잡화점은 본 프레임워크를 참조하지 않기로 기확정(PD님, 2026-04-15). 본 문서는 그 전제를 사용하지 않는다. ② 네임스페이스·릴리스 범위 등 타 OI 재결정이 아님. ③ Gitea 인프라 운영 정책 변경이 아님 |
1. 요약
권장안: C안(UPM Git URL) + H1(로컬 file: 오버라이드). 태그 추적 기반 버전 고정. 근거 한 줄: 헌법 제1원칙 목표 1·2·3 세 축 모두에서 1위 또는 공동 1위이며, 추가 인프라 비용 없이 Tier 1 Core 4종의 현 Gitea push 상태와 최저 추가 작업으로 연결된다.
2. 판단 기준 (헌법 제1원칙 3대 목표 원문)
본 안건은 아래 3대 목표에 대한 정합성을 1차 기준으로 한다. 하위 핵심 규칙(C11·C14·C15 등)은 운영 규칙으로 부속 적용한다.
목표 1 — 코어 프레임워크의 PC 독립 최신화 유지: 어느 PC에서 작업하든 항상 최신화된 너드나비스 조직의 자산으로 코어 코드 프레임워크를 유지·관리한다. 환경 이동·PC 추가·재기동 상황에서 프레임워크의 단일 최신 상태가 깨지지 않도록 구조를 설계·운영한다.
목표 2 — 차기 프로젝트부터 조직 자산으로 적극 활용: 현행 수상한 잡화점 프로젝트는 코어 프레임워크를 활용하지 않는다. 다음 프로젝트부터 조직 자산으로 적극 도입하여, 범용성 높은 너드나비스만의 개발 노하우를 축적한다. 프레임워크는 "만들고 끝"이 아니라 "게임을 만들수록 쌓이는 자산"으로 운영한다.
목표 3 — 단기제작 가능한 유능한 게임 개발 스튜디오로의 발전: 코어 프레임워크를 포함한 효율성 높은 개발 노하우를 지속 축적하여, 궁극적으로 어떤 게임이든 단기간 내 제작 가능한 유능한 스튜디오로 발전한다.
배포 방식이 3대 목표에 기여하는 관점:
- 목표 1 → 단일 최신 상태 유지·PC 독립 재현성. 배포 방식이 PC별 경로·절대경로에 의존하지 않아야 함
- 목표 2 → 차기 프로젝트에서 한 번의 선언으로 도입 가능해야 함. 도입 절차 길이가 곧 진입 장벽
- 목표 3 → 프로젝트를 거치며 버전이 누적되는 구조. 릴리스 이력이 투명하고, 여러 프로젝트가 서로 다른 버전을 병행 사용할 수 있어야 함
3. 후보안 평가표
3.1 후보안 정의
| ID | 안 | 요약 |
|---|---|---|
| A | 외부 경로 참조 | Unity 밖 고정 경로(${FRAMEWORK_PKG_ROOT}) 직접 참조 또는 manifest.json의 file: 절대경로 |
| B | Git 서브모듈 | Unity 레포 내 .gitmodules 로 Framework 레포 등록, Assets 또는 Packages 하위에 체크아웃 |
| C | UPM Git URL | manifest.json 의 com.nerdnavis.framework 항목을 Gitea URL(태그/커밋 고정)로 지정 |
| H1 | C + 로컬 file: 오버라이드 | 기본값은 C(원격 URL), Framework 동시 개발자만 로컬 file:../NerdNavis.Framework 로 덮어씀 |
| H2 | B + UPM 내부 참조 이중 | 서브모듈로 가져오되 manifest는 file: 로컬 참조. Git 이력 B + Unity 참조 C 장점 차용 시도 |
| S1 | 사내 Scoped Registry | Verdaccio 등 npm 호환 레지스트리 구축, UPM scopedRegistries 등록. tarball 배포 |
3.2 목표별 점수 (◎ 우수 · ○ 보통 · △ 열위 · ✕ 부적합)
| 안 | 목표 1 PC 독립 최신화 | 목표 2 차기 프로젝트 자산 활용 | 목표 3 누적 자산·단기제작 | 종합 |
|---|---|---|---|---|
| A 외부경로 | ✕ PC별 절대경로 어긋남 상존. "내 PC에선 된다" 재현 | △ 차기 프로젝트 도입 시마다 경로 합의 필요 | △ 버전 개념이 파일 시스템에 의존 | ✕ |
| B 서브모듈 | ○ clone으로 재현 가능하나 sub-commit 업데이트 누락 리스크 | ○ 프로젝트마다 서브모듈 등록 필요, 학습비 중 | ○ Git 이력은 풍부하나 버전 전환은 수동 | ○ |
| C UPM Git URL | ◎ Unity 표준, clone 직후 Package Manager가 자동 fetch·캐시 | ◎ 차기 프로젝트 manifest.json 한 줄 추가로 도입 |
◎ 태그 기반 semver 누적, 프로젝트별 버전 고정 병행 가능 | ◎ |
| H1 C+로컬오버라이드 | ◎ 기본값은 원격 태그, 로컬 오버라이드는 명시적 수동 조작 | ◎ C와 동일 | ◎ 기본은 C와 동일하되 Framework 동시 개발 Inner Loop 단축 → 목표 3 효율성 가산 | ◎+ |
| H2 서브모듈+file: | △ 이중 관리로 "최신 상태"의 정의 흔들림 | △ 타 프로젝트에 이 이중 구조를 강요하게 됨 | △ 이력은 풍부하나 단기제작 지향과 상충 | △ |
| S1 Scoped Registry | ◎ tarball 캐시로 최상. 단 레지스트리 인프라 선결 | ◎ 장래 복수 프로젝트·복수 패키지 확장 시 최적 | ◎ 정식 패키지 배포 경로. 단 현시점 비용 초과 | ◎ (선결 조건 충족 전엔 보류) |
운영 규칙 관점(C11·C14): C/H1이 참조 경로 단일성과 팀 학습비 최소화 양면에서 우세. A는 paths.local.json·junction 3축 검증 부담을 Framework까지 확대시켜 C16·신PC 체크리스트 v2와 역행.
4. 권장안 상세 (C + H1)
4.1 구조
- 원격 SOT: Gitea
NerdNavis/NerdNavis.Framework레포. 태그는 semver (v0.x.y, v0 개발판 허용) - Unity 참조: 차기 프로젝트
Packages/manifest.json에 다음 한 줄 추가 형태"com.nerdnavis.framework": "https://burning.i234.me/NerdNavis/NerdNavis.Framework.git#v0.x.y"
- 로컬 오버라이드(H1): Framework 동시 개발자는 로컬에서만
file:../../NerdNavis.Framework로 대체. 커밋 대상이 아님 (.gitignore또는manifest.local.json패턴 중 택1)
4.2 초기 셋업 (현 Tier 1 Core 4종 기준)
- Framework 레포에 v0.1.0 태그 부여 (Log·CoroutineRunner·MonoSingleton·ServiceLocator 기반)
- 태그 푸시 후 Gitea에서 릴리스 노트 초안 자동 생성 확인
- 신PC 셋업 체크리스트 v2에 UPM 인증 절차 append (Git credential helper 또는 PAT URL)
4.3 버전 관리 정책
- 태그 정책: semver. breaking change → minor (v0.x) / patch (v0.0.x)
- 프로젝트별 고정: 프로젝트는 태그 또는 커밋 SHA 고정. 브랜치(
#main) 추적은 금지 (목표 1 재현성 보장) - 갱신 절차: Framework 릴리스 → 사용 프로젝트가
manifest.json의 ref 만 갱신 → 커밋
4.4 다음 프로젝트 도입 절차 (목표 2·3 구현)
- 신규 Unity 프로젝트 생성 시
Packages/manifest.json템플릿에 위 한 줄 동봉 - Framework가 제공하는 asmdef·samples는 UPM 표준으로 자동 노출
- 프로젝트가 필요로 하는 확장은 Framework 본체에 PR로 역제안 → 조직 자산 축적
4.5 리스크 · 완화
| 리스크 | 완화 |
|---|---|
| Gitea private 인증 (PAT 주입) | Windows Credential Manager 자동 캐싱(현 NerdNavisAi push 실증). 체크리스트 v2에 명시 |
| 태그 미지정·브랜치 추적 오남용 | manifest.json 리뷰 체크항목 신설, CI에서 ref 패턴 검증 |
| 레포 공개 범위 변경(가령 외부 스튜디오 협업) | URL만 교체. Scoped Registry(S1) 승격 경로 보존 |
| 로컬 file: 오버라이드가 커밋에 섞여 들어감 | manifest.local.json 분리 패턴 채택 검토 (선결 조건) |
5. 대안 요약
- 차선 (선결 조건 충족 시 승격): S1 사내 Scoped Registry. 목표 3 장기 축적에서 C와 동등 이상. 단 Verdaccio 운영·백업·인증 연동이 선결. 현시점 즉시 채택은 비용 초과
- 기각: A 외부경로 — 목표 1 PC 독립성과 정면 충돌. B 단독 — Assets 내부 meta/GUID 경계 리스크. H2 — 이중 관리 비용 대비 이득 불명확
6. 후속 작업 목록 (선결 조건 충족 시 순차 착수)
| # | 항목 | 담당 | 선결 조건 |
|---|---|---|---|
| F1 | Framework 레포 v0.1.0 태그 부여 + 릴리스 노트 초안 | 개발실장 | PD님 권장안 승인 |
| F2 | manifest.local.json 분리 패턴 PoC |
클라이언트팀장 + DevOps | F1 |
| F3 | 신PC 체크리스트 v2에 UPM 인증 절차 append | 총괄PM | F1 |
| F4 | 06 설계안 §2.4·§7 OI-2 상태 🟡 협의 중 → ✅ 결정 갱신 |
개발실장 | PD님 결정 반영 직후 |
| F5 | 차기 프로젝트 Packages/manifest.json 템플릿화 |
클라이언트팀장 | F1, 차기 프로젝트 착수 시점 |
(일정·기한 표현은 C15에 따라 사용하지 않음. 각 항목은 선결 조건 충족 시 착수)
7. 열린 의사결정 항목 (PD님 결정 요청)
| 항목 | 선택지 | 개발실 권장 |
|---|---|---|
| 1. 기본 배포 방식 | A / B / C / H1 / H2 / S1 | C + H1 |
| 2. 버전 고정 방식 | 브랜치 추적(#main) / 태그(#v0.x.y) / 커밋 SHA |
태그 추적 |
3. 로컬 개발자 file: 오버라이드 허용 여부 |
허용(문서화 조건) / 금지 | 허용 |
| 4. Scoped Registry(S1) 승격 경로 | 지금 구축 / 장래 과제 보류 / 불필요 | 장래 과제 보류 |
C19 준수 명시: 본 문서는 안건 제시까지이며, PD님 승인 없이 되돌리기 어려운 액션(태그 부여·
manifest.json병합 등)은 수행하지 않는다. 승인 범위는 위 4개 항목에 한정된다.
8. 변경 이력
- v1 (2026-04-15, 재작성): 헌법 제1원칙 3대 목표 기반 평가표로 재구성. 4축 섹션(목적·용도·범위·비목적) 상단 추가. OI-5 폐기 반영(수상한 잡화점 투입 전제 삭제). C18·C19 준수 명시. 권장안: C + H1 + 태그 추적 + S1 장래 보류.