BurningTimesAi/개발실/조직공지/GIT동기화방안_v1.md

# 너드나비스 조직 Claude 에이전트 다중 환경 Git 동기화 방안 v1

> **작성**: 개발실장 (2026-04-14)
> **지시 출처**: PD님 직접 지시 (2026-04-14, 개발실 세션, 개발실장 주도 지시)
> **PD 지시 로그**: `공유/PD_지시_트래킹/개발실_PD_지시_로그.md` #4
> **논의 참여**: 개발실장 주도, 클라이언트팀장·서버팀장·DevOps·QA 관점 수렴
> **상태**: v1 초안, PD님 결정 대기 항목 다수 포함
> **참조 규칙**: C6(데이터 보호), C8(프로덕션 보호), C9(AI 에이전트 원칙), C10(중복 작업 방지), C11(개발 관점), C13(공유 의무), P13(코드 변경 관리), P15(의존성·환경 변경 공유), P18(설계 문서화 의무)

---

## 0. 요약 (Executive Summary)

PD님의 요구는 **"회사·집·노트북 어디서든 같은 조직 에이전트에게 일관된 지원을 받고, 노하우가 지속 축적되는 환경"** 구축이다.

현재는 `C:\Users\PC\Documents\너드나비스\` 디렉토리가 **git 저장소조차 아니며**, 조직 자산(CLAUDE.md·agents·commands·공유 문서·PD 지시 로그·일일보고)이 하나의 PC에만 존재한다. 사용자 수준 메모리(`~/.claude/projects/<hash>/memory/`)까지 PC 종속이라 타 환경에서 동일한 에이전트 기억·원칙을 재현할 수 없다.

개발실의 권고 결론:

1. **조직 자산 단일 레포(`nerdnavis-org`)를 Gitea self-host에 신설**하고 `C:\Users\PC\Documents\너드나비스\`를 그대로 git init + remote 연결한다.
2. **사용자 메모리는 repo 안 `memory/org/`로 이전**하고 `~/.claude/.../memory`는 **junction/symlink**로 repo를 가리키게 한다 (PC별 개인 메모만 `memory/local/`로 분리).
3. **민감 파일은 `.gitignore` + 별도 private 서브레포(`nerdnavis-org-secrets`)**로 이중 격리. 키·토큰은 절대 메인 repo에 넣지 않는다.
4. **절대경로는 `$NERDNAVIS_ROOT` 환경 변수 + `paths.local.json`** 체계로 추상화한다. CLAUDE.md는 상대경로·환경변수 표기로 교체.
5. **세션 시작 시 pull / 종료 시 push** 관례를 훅·CLAUDE.md 자동 환기 메모에 박아두고, **append-heavy 로그(일일보고·PD 지시 로그·메모리)는 일자·환경별 파일 분할**로 머지 충돌을 구조적으로 회피한다.
6. **단계적 도입**: Phase 0(읽기 전용 dry-run) → Phase 1(org repo + 문서·규칙·에이전트) → Phase 2(공유 로그·일일보고) → Phase 3(메모리·스킬 모듈) → Phase 4(완전 다중 환경 상시 사용).

Unity 프로젝트(`D:/NerdNavis/FilGoodBandits/DeckBuilding`)와 `NerdNavis.Framework`는 **본 레포와 분리**하여 별도 Git LFS·Plastic 전략으로 다루되, 본 조직 레포는 "에이전트·프로세스·문서·기획 자산" 중심으로 제한한다.

---

## 1. 동기화 범위 정의 (SCOPE)

### 1.1 포함 대상 (IN-SCOPE)

| 계층 | 경로 | 동기화 | 사유 |
|------|------|--------|------|
| 조직 공통 | `너드나비스/CLAUDE.md` | ✅ | 조직 진입 지침 — 모든 환경 동일해야 함 |
| 조직 공통 | `너드나비스/.claude/agents/pm-general.md` | ✅ | 총괄PM 정의 |
| 조직 공통 | `너드나비스/.claude/settings.local.json` | ⚠️ 부분 | 권한 일관성 필요하나 OS별 차이 가능 → `settings.shared.json` 분리 |
| 개발실 | `개발실/CLAUDE.md`, `개발실/.claude/agents/*.md`, `개발실/.claude/commands/*.md` | ✅ | 에이전트 정의 SOT |
| 개발실 | `개발실/코어_설계/`, `개발실/프로젝트_숙지/` | ✅ | 설계 문서(P18) |
| 개발실 | `개발실/⚠️_*.md`, `🛑_*.md`, `🚨_*.md` | ✅ | HOLD·경고 공지(C10-1) |
| 기획실 | `기획실/CLAUDE.md`, `기획실/.claude/agents/*.md`, `기획실/.claude/skill-modules/*.md` | ✅ | 에이전트 정의·스킬 모듈 SOT |
| 기획실 | `기획실/밸런싱/` | ✅ | 기획 설계 자산 |
| 기획실 | `기획실/⚠️_*.md` 계열 | ✅ | HOLD 공지 |
| 공유 | `공유/공통_업무_규칙.md` | ✅ | 규칙 SOT — 최우선 동기화 |
| 공유 | `공유/README.md`, `공유/조직공지/` | ✅ | 조직 공지 |
| 공유 | `공유/PD_지시_트래킹/` | ✅ | C13 의무 기록 (append-heavy — 분할 전략 필요) |
| 공유 | `공유/일일보고/` | ✅ | P20 의무 기록 (append-heavy) |
| 공유 | `공유/기획실→개발실/`, `공유/개발실→기획실/`, `공유/완료/` | ✅ | REQ 히스토리 |
| 사용자 메모리 | `~/.claude/projects/<hash>/memory/MEMORY.md` + feedback/project/reference 파편 | ✅ (재배치) | 조직 공용 기억은 **repo로 이전**, PC 개인 기억은 `memory/local/`로 분리 |

### 1.2 제외 대상 (OUT-OF-SCOPE)

| 경로 | 제외 사유 | 별도 관리 |
|------|----------|----------|
| `D:/NerdNavis/FilGoodBandits/DeckBuilding/` (Unity 프로젝트) | 크기 수 GB, 바이너리 다수, Unity Collaborate/Plastic/PlasticSCM 등 별도 VCS 필요 | Plastic SCM 또는 Git-LFS 전용 레포 |
| `D:/NerdNavis/NerdNavis.Framework/` | 이미 Gitea에 별도 레포로 push 중 | 기존 레포 유지, 본 조직 레포에선 경로 참조만 |
| `너드나비스/data/nerdnavis.sqlite` | 로컬 DB, PC별 실행 상태 다름 | `.gitignore` |
| `기획실/.cache/` | 시뮬레이터 캐시 — 재생성 가능 | `.gitignore` |
| API 키·토큰·Firebase/PlayFab 설정 | 민감정보 | 별도 private 레포 또는 1Password/vault |
| `settings.local.json` (PC 고유 부분) | PC별 권한·경로가 다를 수 있음 | `settings.shared.json`로 공통 분리, `.local`은 ignore |
| `.cache/`, `Library/`, `Temp/`, `obj/`, `bin/` | 빌드·캐시 산출물 | `.gitignore` |
| `*.bak_*` | C6에 따른 백업 파일 | `.gitignore` (선택적 — 팀장 판단) |
| `~/.claude/` 전체 중 **memory 이외** | Claude Code가 관리하는 사용자 설정 | 제외 — 필요 시 별도 dotfiles |

### 1.3 메모리 처리 설계 (핵심 난제)

현재 사용자 메모리는 **경로가 해시로 인코딩된** 사용자 폴더에 존재:

```
C:\Users\PC\.claude\projects\C--Users-PC-Documents----------\memory\*.md
```

이 경로는 **OS와 사용자명에 종속**되어 타 환경에서 자동 재현 불가. 해결 전략 3가지를 비교:

| 옵션 | 내용 | 장점 | 단점 |
|------|------|------|------|
| **A. 전부 CLAUDE.md로 이동** | MEMORY.md 내용을 조직 CLAUDE.md 섹션에 통합 | 표준 위치·추가 설정 불필요 | CLAUDE.md 비대, 개인화 기억 섞임 |
| **B. repo `memory/` + junction/symlink** | `너드나비스/memory/org/` 생성 후 `~/.claude/projects/<hash>/memory`를 junction으로 연결 | 경로 유지, Claude Code 동작 불변 | OS별 symlink/junction 명령 상이, 해시 경로 복원 스크립트 필요 |
| **C. 하이브리드** | 조직 공용 기억은 CLAUDE.md·스킬 모듈·규칙 문서로 흡수, 개인·임시 기억만 원래 위치 유지 | 깔끔, 역할 분리 | 기존 MEMORY.md 리팩토링 공수 |

**권고: C (하이브리드) + B 보조**. 조직 공용 기억은 이미 CLAUDE.md·규칙·스킬 모듈에 상당 부분 흡수되어 있음. 남은 feedback_*·project_*·reference_* 중 **조직 전체에 유효한 항목은 `공유/지식베이스/`로 승격**, 개인 선호·임시 노트만 사용자 메모리에 유지. 사용자 메모리 원본이 반드시 모든 환경에 있어야 한다면, 환경 셋업 스크립트가 `~/.claude/projects/<hash>/memory`를 `memory/personal-PC-$HOSTNAME/`으로 junction 연결.

---

## 2. 저장소 전략

### 2.1 권고: "1 메인 레포 + 1 시크릿 레포 + 프로젝트별 별도 레포"

```
Gitea (self-host, 이미 SSH 22 세팅 완료)
├── nerdnavis-org          (메인: 조직 자산·에이전트·문서·공유·기획 문서)  [Private]
├── nerdnavis-org-secrets  (시크릿: API키, .env 템플릿, 서버 인증 정보)    [Private, 제한 접근]
├── nerdnavis-framework    (이미 존재 — 범용 코어 NerdNavis.*)              [기존 유지]
└── <게임별 Unity 레포>    (예: suspicious-shop-client)                     [LFS/Plastic 병행]
```

### 2.2 대안 비교

| 전략 | 장점 | 단점 | 평가 |
|------|------|------|------|
| **단일 모노레포 (Unity 포함)** | 한 번의 clone으로 전부 | 10GB+ clone, shallow 필수, git 속도 저하, 비개발 PC는 불필요한 바이너리 받음 | ✗ 비권장 |
| **메인+시크릿+프로젝트별** (권고) | 관심사 분리, 민감 격리, 경량 | 레포 수 관리 필요 | ✓ 권고 |
| **레포 파편화 (5개+ 세분화)** | 매우 세밀한 접근 제어 | 상호 참조 복잡, 클론 누락 리스크 | ✗ 비권장 |

### 2.3 Gitea vs GitHub

| 항목 | Gitea (self-host) | GitHub Private |
|------|-------------------|----------------|
| 비용 | 0 (자체 서버) | Team 요금 |
| 데이터 주권 | ✅ 완전 보유 | 타사 보관 |
| 속도 | 내부망 빠름, 외부 SSH 22 세팅 완료 | CDN 우수 |
| CI/CD | Gitea Actions | GitHub Actions (성숙) |
| 모바일 접근 | 자체 VPN/공개 필요 | 기본 지원 |

**권고: Gitea 메인 + GitHub에 푸시 미러(선택)**. 자체 호스팅이 이미 준비되어 있고 기획·설계 문서 민감도를 고려. 다만 **집·노트북 등 외부 환경에서 접근 가능하도록 Gitea 외부 노출(HTTPS 또는 SSH 공개 키 접근) 확인**은 필수 전제(DevOps 확인 필요).

### 2.4 브랜치·접근 권한

- **main**: 보호 브랜치. 직접 push 금지. 병합은 팀장 승인 후 병합 또는 trunk-based for small ops.
- **`agent/<환경명>`** (선택): 환경별 작업 브랜치. 병합 시 main으로 rebase.
- 접근 권한: PD님·총괄PM·개발실장·기획팀장 = Admin. 산하 에이전트 셋업 계정 = Write. 외부 협력자 = Read-only.

실제 운용에서는 개발실 AI 에이전트가 단일 PD님 PC에서 작업하는 구조이므로, 초기에는 **main 직접 push 허용** + **push 전 린트·문서 체크 pre-commit 훅**으로 단순화해도 무방. 다중 환경 접속이 실사용 단계에 들어가면 PR 기반으로 전환.

---

## 3. 환경 간 이식성 (경로·OS 추상화)

### 3.1 현재 하드코딩 절대경로 실태

조직 문서 내 하드코딩된 절대경로 샘플:

- `C:/Users/PC/Documents/너드나비스/...` (CLAUDE.md 곳곳)
- `D:/NerdNavis/FilGoodBandits/DeckBuilding/...` (개발실·기획실 CLAUDE.md)
- `C:/Users/PC/.claude/projects/C--Users-PC-Documents----------/memory/...` (MEMORY.md)

이 경로들은 집 PC·노트북(사용자명 다름, D 드라이브 없음)·macOS에서 **즉시 깨진다**.

### 3.2 해결 설계: 3층 경로 추상화

```
Layer 1: 조직 내부 상대경로 (SOT)
  → "공유/공통_업무_규칙.md" (저장소 루트 기준)

Layer 2: 논리 환경 변수
  → $NERDNAVIS_ROOT       = 조직 레포 clone 위치
  → $NERDNAVIS_UNITY_ROOT = Unity 프로젝트 위치 (PC마다 다름)
  → $NERDNAVIS_FRAMEWORK  = NerdNavis.Framework 위치

Layer 3: PC별 실제 경로 (paths.local.json, .gitignore)
  → {
      "unity_root": "D:/NerdNavis/FilGoodBandits/DeckBuilding",
      "framework":  "D:/NerdNavis/NerdNavis.Framework",
      "hostname":   "NERDNAVIS-MAIN-PC"
    }
```

**CLAUDE.md 재작성 원칙**:
- 조직 내부 자산은 **"공유/", "개발실/", "기획실/"로 시작하는 상대경로**만 사용
- 외부 자산(Unity·Framework)은 `$NERDNAVIS_UNITY_ROOT` 등 환경 변수로 표기
- 환경 변수는 **`paths.local.json` → 셸 export 스크립트(`scripts/env.ps1`·`scripts/env.sh`)** 두 OS에 동일 결과를 내게 함

### 3.3 Windows/macOS/Linux 경로 구분자

- 문서 내 경로 표기는 **슬래시(`/`)** 로 통일 (Windows Git·PowerShell 모두 해석)
- 백슬래시(`\`)는 금지. 기존 문서 내 `\` 역치환 일괄 작업 필요 (Phase 1 cleanup)
- `.gitattributes`에 `* text=auto eol=lf` + 일부 Windows 스크립트 `*.ps1 text eol=crlf` 설정

### 3.4 드라이브 종속 문제 (D:/NerdNavis/...)

해결: **`paths.local.json`에서 대응 경로를 선언**하고, 에이전트는 해당 변수만 참조. 환경별 실제 드라이브가 달라도(C·D·Users/user1/Projects 등) 변수로 흡수.

---

## 4. 민감정보 분리

### 4.1 위험 요소 식별

| 항목 | 현재 위치 | 잠재 위험 |
|------|----------|----------|
| PD 지시 로그 | `공유/PD_지시_트래킹/` | 경영상 민감 의사결정·조직 인사 정보 유출 가능 |
| 기획 초안 | `기획실/밸런싱/`, `기획실/*.md` | 미공개 게임 기획 경쟁 노출 |
| 서버 Critical 보안 현황 | `개발실/프로젝트_숙지/.../05_서버연동_현황_v1.md` | 보안 취약점 직접 노출 |
| 일일 보고 | `공유/일일보고/` | 내부 진행·사고 기록 |
| settings.local.json | `.claude/` | 권한·MCP 토큰 |
| API 키·Firebase·PlayFab·Gitea PAT | (현재 하드코딩 확인 필요) | 인증 크리덴셜 |

### 4.2 분리 전략

**3중 방어**:

1. **공개 위험 없는 자산 → `nerdnavis-org` (Private)**
2. **민감 자산 → `nerdnavis-org-secrets` (별도 Private, 접근자 최소)**
   - API 키, 서버 보안 현황 상세, 외부 공유 전 초안 자료
3. **절대 커밋 금지 → `.gitignore` + pre-commit 훅**
   - `*.env`, `*secret*`, `*credential*`, `*token*`, `*.key`, `*.pem` 차단

### 4.3 `.gitignore` 초안 (메인 repo)

```gitignore
# Claude Code 로컬 상태
.claude/settings.local.json
.claude/.session/
.claude/*.local.*

# 환경별 경로 설정
paths.local.json
scripts/env.local.*

# 민감 자산
*.env
*.env.*
!*.env.template
*secret*
*credential*
*token*
*.key
*.pem
*.pfx
firebase-*.json
playfab-*.json

# 백업
*.bak_*
*.backup

# 캐시·임시
.cache/
**/.cache/
**/Library/
**/Temp/
**/obj/
**/bin/
.DS_Store
Thumbs.db

# Unity (만약 서브모듈 실수 방지)
**/Assets/Library/
**/Assets/Temp/

# 로컬 DB
*.sqlite
*.db
!**/schema/*.sqlite

# Claude 사용자 메모리 로컬 전용 (PC 개인 메모 구역)
memory/local/
memory/personal-*/
```

### 4.4 Git-crypt 옵션 검토

**결론: 초기 도입 보류**. 민감 파일은 별도 `nerdnavis-org-secrets` 레포로 격리하는 편이 더 단순하고 실수 리스크가 낮다. Git-crypt는 키 분실 시 복구 난이도가 높고 AI 에이전트 조직에선 관리 부담이 커진다. 민감도가 더 높은 단일 파일(예: 마스터 키)이 생기면 그때 도입.

---

## 5. 동기화 트리거·워크플로

### 5.1 권고 관례

**"세션 시작 pull / 세션 종료 push"** + **"주요 산출물 생성 직후 커밋"**

| 시점 | 수행 | 책임 |
|------|------|------|
| 세션 착수 | `git fetch && git pull --rebase` | 진입 에이전트 (개발실장·기획팀장·총괄PM 등) |
| C10-1 3단계 확인 직후 | 최신 HOLD 공지·규칙 변경 확인 포함 | 동일 |
| 신규 산출물 생성 | 그 자리에서 `git add + commit` | 해당 에이전트 |
| PD 지시 로그·일일보고 갱신 | 갱신 직후 즉시 commit (지연 금지) | 팀장 |
| 세션 종료 | `git push` + 로그에 push 커밋 해시 기록 | 세션 종료 에이전트 |

### 5.2 자동화 훅 제안

- **pre-commit**:
  - 민감 파일 패턴 차단 (`*.env`, `*secret*` 등)
  - 하드코딩 절대경로 경고 (`C:/Users/PC/`, `D:/NerdNavis/` 패턴 검출 시 경고)
  - CLAUDE.md에 `# currentDate` 등 변동성 블록이 실수로 포함되지 않았는지 확인
- **post-commit** (선택):
  - 커밋 해시를 `공유/일일보고/<date>_<부서>.md` 하단에 자동 append
- **prepare-commit-msg**:
  - 커밋 메시지에 환경 식별자(hostname) 자동 삽입: `[env=NERDNAVIS-MAIN-PC]`

### 5.3 동시 작업 충돌 정책 (append-heavy 파일 핵심)

**문제**: MEMORY 파편·PD 지시 로그·일일보고는 환경 A에서 append, 환경 B에서도 append 시 머지 충돌 발생. 특히 같은 날짜 행을 두 환경에서 동시 기록하면 수동 머지 필요.

**해결 원칙 — "파일 분할로 충돌 구조적 회피"**:

| 현재 구조 | 변경 구조 | 효과 |
|----------|----------|------|
| `공유/일일보고/2026-04-15_개발실.md` (단일 파일) | `공유/일일보고/2026-04-15_개발실/<hostname>-<timestamp>.md` (환경별 파편) + 자동 집계 스크립트 | 환경 간 append 충돌 0 |
| `공유/PD_지시_트래킹/개발실_PD_지시_로그.md` (단일 표) | 단일 표 유지하되 **일자별 분할 가능성 검토** — 당장은 환경을 동시에 쓸 일이 드물므로 유지, 충돌 발생 시 분할 전환 | 단순성 유지 |
| `MEMORY.md` | `memory/org/<카테고리>/<항목>.md` 분할 (이미 일부 분할되어 있음) + index만 MEMORY.md | 카테고리별 독립 편집 가능 |

**충돌 발생 시 해결 순서**:
1. `git pull --rebase` 재시도 — 대부분 자동 머지
2. 구조적 충돌 발생 시 **append-only 원칙에 따라 두 환경 내용을 시간순으로 병렬 기록** (한쪽 drop 금지 — C5 정직성)
3. 로그·보고류는 **"절대 rebase -i로 과거 커밋 수정 금지"** (C6 데이터 보호와 동일 정신)

### 5.4 환경 식별자 기록 관례

각 커밋과 로그 행에 **hostname**(예: `NERDNAVIS-MAIN-PC`, `NERDNAVIS-HOME-PC`, `NERDNAVIS-LAPTOP`)을 자동 첨부. 이후 "어느 환경에서 무슨 작업을 했나"를 추적 가능.

예: 일일보고 파일명 `2026-04-15_개발실_NERDNAVIS-MAIN-PC.md` 또는 행 내부에 `[env=MAIN-PC]` 태그.

---

## 6. 메모리 동기화 심화

### 6.1 현 상태 분석

- `~/.claude/projects/C--Users-PC-Documents----------/memory/` 안에 MEMORY.md + 14개 파일
- 경로 해시: `C--Users-PC-Documents----------` = `C:\Users\PC\Documents\...` 의 Claude Code 규칙 해시
- **타 PC에서 같은 경로 조직 루트(`C:\Users\PC\Documents\너드나비스\`)를 만들지 않는 한 자동으로 다른 해시**가 생성됨 → 자동 재현 불가

### 6.2 권고 처리 (하이브리드)

**Step 1: 메모리 내용 분류**
- **조직 공용 지식** (feedback_design_philosophy·feedback_process_rules·feedback_card_balance_rules 등): `공유/지식베이스/`로 승격, MEMORY.md에선 링크만 유지
- **프로젝트 고유 지식** (project_suspicious_shop·project_new_core_direction 등): 해당 프로젝트 문서 폴더로 이동(`개발실/프로젝트_숙지/수상한잡화점/` 등)
- **PC 개인 선호·임시 메모**: 사용자 메모리 원래 위치 유지, repo에 **올리지 않는다**

**Step 2: MEMORY.md 재구성**
```markdown
# 사용자 메모리 인덱스 (PC: NERDNAVIS-MAIN-PC)

## 조직 공용 (repo 참조)
- 규칙 SOT: $NERDNAVIS_ROOT/공유/공통_업무_규칙.md
- 게임 기획 철학: $NERDNAVIS_ROOT/공유/지식베이스/design_philosophy.md
- ...

## PC 개인 메모 (이 PC 전용)
- 개인 단축키·도구 선호
- 현재 세션의 임시 TODO
```

**Step 3: 신규 PC 셋업 절차**
1. `nerdnavis-org` clone → `$HOME/Documents/너드나비스/` 또는 임의 위치
2. `$NERDNAVIS_ROOT` 환경 변수 설정 (`scripts/env.ps1` 또는 `env.sh` 실행)
3. Claude Code 세션을 해당 루트에서 시작 → CLAUDE.md 자동 로드
4. 사용자 메모리는 **repo의 `memory/template/MEMORY.md`** 템플릿을 `~/.claude/projects/<hash>/memory/MEMORY.md`로 복사 (환경별 hostname·개인 메모 빈칸 상태)
5. (선택) junction으로 `memory/org/`를 사용자 메모리 폴더에 마운트하여 조직 지식 즉시 반영

### 6.3 Claude Code 허용 설정 확인 필요

- CLAUDE.md는 **프로젝트 레벨**(현재 쓰임)과 **사용자 레벨**(`~/.claude/CLAUDE.md`) 둘 다 지원됨 — 확인됨
- `.claude/agents/*.md`·`.claude/commands/*.md`는 **폴더 기반**으로 자동 인식 — 확인됨
- Skill 모듈(`기획실/.claude/skill-modules/`)이 자동 로드되는지 여부는 **Claude Code 버전별 확인 필요** → DevOps가 실증 테스트

---

## 7. 노하우 축적 메커니즘

### 7.1 강제력 설계

**"작업 → 로그 → 커밋 → push"가 단일 흐름이 되도록 규칙·훅·CLAUDE.md 환기로 삼중 강제**.

1. **규칙 레벨 (C13·P20)**: 이미 시행 중. 위반 시 헌법급 위반.
2. **프로세스 레벨**: CLAUDE.md의 "작업 시점별 자동 환기 메모"에 **"세션 종료 시 git push 확인"** 항목 추가.
3. **기술 레벨**: pre-push 훅이 **"일일 보고 파일이 오늘 날짜로 갱신되어 있는지"** 검사. 없으면 확인 경고.

### 7.2 환경 간 노하우 교차 참조

- 일일보고 파일명·메시지에 **hostname** 포함
- 검색 편의를 위해 `공유/지식베이스/INDEX.md`에 발견된 노하우 항목(날짜·환경·태그·요약) 집계
- 주간(선택) 또는 주요 마일스톤마다 총괄PM이 `공유/지식베이스/retrospective_YYYY-WW.md` 작성

### 7.3 스킬 모듈 확장

기획실 `.claude/skill-modules/`처럼 개발실도 스킬 모듈 도입:
- `개발실/.claude/skill-modules/module_git_sync.md` (본 방안 실무 체크리스트)
- `개발실/.claude/skill-modules/module_session_start.md` (세션 진입 C10-1 자동 체크리스트)
- `개발실/.claude/skill-modules/module_session_end.md` (일일보고·push 체크리스트)

---

## 8. 단계적 도입 플랜 (Phase)

### Phase 0 — 준비 (읽기 전용 dry-run, 1~2 세션)
- [ ] Gitea에 `nerdnavis-org`·`nerdnavis-org-secrets` 레포 생성 (DevOps)
- [ ] 현재 `너드나비스/` 전체를 **임시 위치로 복사**해 git init 테스트 (원본 C6 보호)
- [ ] `.gitignore`·`.gitattributes` 초안 적용 후 `git status`로 포함/제외 검증
- [ ] 민감 파일 스캔 스크립트 실행 (`grep` 패턴·사이즈·확장자)
- **진입 조건**: PD님 승인
- **검증**: 불필요 파일이 tracked 상태로 올라오지 않음, 민감 패턴 매칭 0

### Phase 1 — 메인 레포 가동 (읽기 중심, 1~3 세션)
- [ ] 실제 `너드나비스/`에서 `git init` → 원격 연결 → 초기 커밋
- [ ] CLAUDE.md 절대경로 → 상대경로·환경변수 일괄 치환 (개발실장 주도)
- [ ] `paths.local.json.template` + `scripts/env.ps1`·`scripts/env.sh` 작성
- [ ] 첫 번째 환경(메인 PC)에서 push/pull 정상 동작 검증
- **진입 조건**: Phase 0 완료
- **검증**: 별도 임시 폴더에 clone → Claude Code로 세션 진입 → CLAUDE.md·에이전트 정상 로드

### Phase 2 — 공유 로그 동기화 (쓰기 포함, 1~2 세션)
- [ ] PD 지시 로그·일일보고를 repo에 포함
- [ ] append-heavy 파일 분할 전략 적용 여부 결정 (당장은 단일 파일 유지, 다중 환경 동시 작업 발생 시 전환)
- [ ] pre-commit·post-commit·pre-push 훅 도입
- **진입 조건**: Phase 1 안정
- **검증**: 일일보고 작성 → 자동 커밋 → push → 다른 환경에서 pull → 내용 확인

### Phase 3 — 메모리·스킬 모듈 이전 (1~2 세션)
- [ ] MEMORY.md 재구성 (조직 공용 승격 + 개인 메모 분리)
- [ ] 스킬 모듈 repo 포함
- [ ] 신규 환경 셋업 가이드 문서(`공유/환경셋업/신규환경_셋업가이드.md`) 작성
- **진입 조건**: Phase 2 안정
- **검증**: 두 번째 PC(집/노트북) 셋업 → 조직 공용 기억 정상 참조 확인

### Phase 4 — 다중 환경 상시 사용 (운영 단계)
- [ ] 집·회사·노트북 3개 환경 순차 적용
- [ ] 충돌 사례 수집·해결 패턴 `지식베이스/` 축적
- [ ] 주간 retrospective 시작
- **진입 조건**: Phase 3 안정 + 최소 1주 무장애
- **검증**: 한 환경에서 생성한 산출물이 다른 환경에서 즉시 사용 가능

---

## 9. 리스크·오픈 이슈

### 9.1 리스크 목록

| # | 리스크 | 영향 | 대응 |
|---|-------|------|------|
| R1 | CLAUDE.md 절대경로 치환 누락 → 타 환경 파손 | 高 | Phase 1에서 grep 기반 전수 스캔, 타 환경 clone 테스트 |
| R2 | 민감정보 실수로 메인 repo 커밋 | 致命 | pre-commit 훅 + Phase 0 dry-run + 별도 secrets 레포 |
| R3 | 사용자 메모리 해시 경로 차이로 환경별 불일치 | 中 | 환경 셋업 스크립트 + 메모리 하이브리드 구조 |
| R4 | 동일 append-heavy 파일 동시 편집 충돌 | 中 | 파일 분할·시간 태깅, 충돌 시 정직 병합 (C5) |
| R5 | Gitea 외부 접근 장애 시 타 환경 작업 중단 | 中 | 외부 접근 경로 이중화(SSH + HTTPS), GitHub 미러 선택 |
| R6 | Git 명령 실수로 과거 커밋 파괴(`push --force` 등) | 高 | main 보호 브랜치, 헌법급 금지 규정 재환기 |
| R7 | Claude Code 세션 메모리 · repo 메모리 이중 진실 | 中 | 단일 SOT 선언 (repo 우선), MEMORY.md 인덱스는 경량화 |
| R8 | 조직 규모 확장 시 레포 권한·비용 증가 | 低 | 현 단계에서는 무시, Phase 4 이후 재평가 |
| R9 | PD 지시 로그가 git 히스토리에 남아 외부 유출 시 복구 불가 | 中 | Private repo 유지, 접근 계정 최소화, BFG Repo-Cleaner 비상 절차 준비 |
| R10 | Unity·Framework 레포와 경로 참조 꼬임 | 中 | 본 방안에 포함 안 함 명시, paths.local.json으로 참조만 |

### 9.2 PD님 결정 필요 사항 (우선순위 순)

| 우선순위 | 항목 | 선택지 | 개발실 권고 |
|---------|------|--------|-----------|
| ★★★ | **레포 호스팅** | A) Gitea only, B) GitHub only, C) Gitea+GitHub 미러 | A (Gitea only). 데이터 주권·비용·기존 SSH 세팅 기반 |
| ★★★ | **사용자 메모리 처리** | A) 하이브리드(권고), B) 전부 CLAUDE.md로 이동, C) 그대로 두고 수동 동기화 | A |
| ★★★ | **외부 환경 Gitea 접근 경로** | A) SSH 22 공개 노출, B) VPN(WireGuard·Tailscale), C) Cloudflare Tunnel | B (Tailscale). 설치 단순, SSH·HTTPS 모두 보호 |
| ★★ | **민감정보 격리 방식** | A) 별도 secrets repo, B) git-crypt, C) 둘 다 | A (초기) |
| ★★ | **append-heavy 파일 분할 시점** | A) 즉시 분할, B) 충돌 발생 후 분할 | B (단순성 유지) |
| ★★ | **Phase 착수 시점** | A) 즉시, B) 수상한 잡화점 마일스톤 이후, C) PD님 일정 맞춰 | PD님 판단 |
| ★ | **조직 공용 지식 `공유/지식베이스/` 신설 범위** | A) 최소(개인 메모에서 승격되는 것만), B) 스킬·레퍼런스·의사결정 로그까지 포함 | B (장기 노하우 축적 목적상) |
| ★ | **환경 식별자 방식** | A) hostname 그대로, B) 별칭(MAIN/HOME/LAPTOP) | B |
| ★ | **커밋 메시지·브랜치 영어/한국어 혼용 정책** | A) 한국어 허용, B) 영어 통일 | A (조직 규약 한국어 기조와 일치) |

---

## 10. 팀 내 논의 기록 요약

> 개발실장이 각 팀장·담당자의 관점을 대리하여 토론을 진행. 각 역할에서 제기된 핵심 의견을 요약.

### 10.1 클라이언트팀장 관점
- **입장**: Unity 프로젝트와 조직 자산은 **반드시 분리**해야 함. Unity는 Library/·Temp/ 등 거대 캐시 때문에 일반 git 관리 부적합. Plastic SCM 또는 Git-LFS 전용 레포가 필요. 조직 레포에는 **클라이언트 설계 문서**(`개발실/코어_설계/`)와 **에이전트 정의**만 포함.
- **우려**: `.claude/` 중 Claude Code가 자동 생성하는 세션 상태·캐시가 repo에 섞이면 안 됨. `.gitignore`로 `settings.local.json`·`.session/` 구분 필수.
- **제안**: 클라이언트 빌드 스크립트·Player Settings 프리셋은 별도 레포(`suspicious-shop-client`)에서 관리. 본 조직 레포는 **"뇌"** 에 해당하는 문서·에이전트 계층에 한정.

### 10.2 서버팀장 관점
- **입장**: 서버 Critical 보안 3건(IAP·전투·AES 평문키)이 현재 보류 중이므로, **관련 현황 문서는 반드시 `nerdnavis-org-secrets` 레포로 격리**. 메인 repo에 들어가면 git 히스토리에서 지워도 이미 유출 리스크 발생.
- **우려**: Gitea를 외부에 열 때 SSH 22만 열려 있다면 brute-force·key leak 리스크 존재. VPN(Tailscale) 경로 강력 권고.
- **제안**: Phase 0 dry-run 단계에서 **보안 스캔 스크립트** 반드시 선행. 서버 설정 파일 템플릿만 메인에 두고 실제 값은 secrets repo·vault로.

### 10.3 DevOps 관점
- **입장**: Gitea self-host는 이미 가동 중, SSH 22 정상화 완료. 외부 환경 접근을 위해 **Tailscale 설치 권고**(무료·P2P mesh·dynamic IP 불문). DNS·포트 공개 없이도 VPN만 켜면 접근.
- **훅 구성**: pre-commit·pre-push에 git hook 스크립트 + `.pre-commit-config.yaml` 두 버전 준비. Windows/macOS 호환 필요.
- **CI 최소 구성**: Gitea Actions로 (1) 민감 패턴 스캔 (2) 한글 깨짐 인코딩 검사 (3) 설계 문서 참조 무결성(P18) 검증.
- **제안**: 환경 셋업 자동화 스크립트 제작(`scripts/bootstrap.ps1`·`bootstrap.sh`) — 신규 PC에서 한 번 실행하면 clone + junction + 환경변수 + Claude Code 구성까지 완료.

### 10.4 QA 관점
- **입장**: 각 Phase 진입·종료 시 **검증 체크리스트**가 있어야 함. 특히 Phase 3 메모리 이전 후 "조직 공용 기억을 에이전트가 실제로 참조하는가"를 블랙박스 테스트로 확인.
- **회귀 시나리오**: 두 번째 PC에서 (a) `/개발실장` 호출 (b) `/qa` 호출 (c) C13 동작(PD 지시 로그 자동 등록) 세 가지를 순차 실행하고 원본 환경과 출력 일관성 비교.
- **제안**: 각 Phase 말미에 `공유/QA/git동기화_Phase{N}_검증보고.md` 생성. Phase 4 이후 주기적 헬스체크.

### 10.5 합의된 권고안
- 메인 레포 + 시크릿 레포 + 기존 Framework 레포 **3구조**
- Gitea 메인 + Tailscale VPN 접근
- 메모리 **하이브리드** 처리, 사용자 메모리 재구성 포함
- append-heavy 파일 **당장은 단일 유지, 충돌 발생 시 분할**
- 4 Phase 단계 도입
- 본 v1 초안 → PD님 의사결정(우선순위 ★★★ 3건) 후 Phase 0 착수

---

## 11. 실행 산출물 예시 (참고)

### 11.1 `paths.local.json.template`
```json
{
  "hostname": "NERDNAVIS-MAIN-PC",
  "nerdnavis_root": "C:/Users/PC/Documents/너드나비스",
  "unity_root": "D:/NerdNavis/FilGoodBandits/DeckBuilding",
  "framework_root": "D:/NerdNavis/NerdNavis.Framework",
  "user_memory_path": "C:/Users/PC/.claude/projects/C--Users-PC-Documents----------/memory"
}
```

### 11.2 `scripts/env.ps1` (Windows)
```powershell
$cfg = Get-Content "$PSScriptRoot/../paths.local.json" | ConvertFrom-Json
$env:NERDNAVIS_ROOT      = $cfg.nerdnavis_root
$env:NERDNAVIS_UNITY     = $cfg.unity_root
$env:NERDNAVIS_FRAMEWORK = $cfg.framework_root
$env:NERDNAVIS_HOSTNAME  = $cfg.hostname
Write-Host "NERDNAVIS env loaded for $($cfg.hostname)"
```

### 11.3 `scripts/env.sh` (macOS/Linux)
```bash
#!/usr/bin/env bash
CFG="$(dirname "$0")/../paths.local.json"
export NERDNAVIS_ROOT=$(jq -r .nerdnavis_root "$CFG")
export NERDNAVIS_UNITY=$(jq -r .unity_root "$CFG")
export NERDNAVIS_FRAMEWORK=$(jq -r .framework_root "$CFG")
export NERDNAVIS_HOSTNAME=$(jq -r .hostname "$CFG")
echo "NERDNAVIS env loaded for $NERDNAVIS_HOSTNAME"
```

### 11.4 `.gitattributes` 초안
```gitattributes
* text=auto eol=lf
*.ps1       text eol=crlf
*.bat       text eol=crlf
*.cmd       text eol=crlf
*.md        text eol=lf
*.json      text eol=lf
*.png       binary
*.jpg       binary
*.pdf       binary
*.xlsm      binary
*.xlsx      binary
```

### 11.5 pre-commit 훅 개요 (의사코드)
```bash
#!/usr/bin/env bash
# 1) 민감 패턴 검사
if git diff --cached --name-only | grep -E '\.env$|secret|credential|token|\.key$|\.pem$' ; then
  echo "SENSITIVE file detected. Aborting."
  exit 1
fi
# 2) 하드코딩 경로 경고
if git diff --cached -U0 | grep -E 'C:/Users/[^/]+/' ; then
  echo "WARNING: hardcoded absolute path detected. Use \$NERDNAVIS_ROOT."
  # 강제 중단 여부는 정책 결정 필요 → 초기엔 경고만
fi
exit 0
```

### 11.6 신규 환경 셋업 절차(의사 순서)
```
1. Tailscale 설치·로그인 (PD님 계정)
2. git clone git@gitea.nerdnavis.local:org/nerdnavis-org.git $HOME/Documents/너드나비스
3. cd 너드나비스 && cp paths.local.json.template paths.local.json
4. paths.local.json 수정 (hostname, 드라이브 경로 등)
5. (선택) git clone ...org-secrets.git (접근 권한 있는 경우)
6. ./scripts/bootstrap.(ps1|sh) 실행
   - 환경변수 export
   - ~/.claude/projects/<hash>/memory 디렉토리 확인·템플릿 복사
   - (선택) junction으로 memory/org/ 마운트
7. Claude Code 실행 → 개발실장 호출로 동작 검증
```

---

## 12. 변경 이력

| 버전 | 일시 | 변경 | 작성 |
|------|------|------|------|
| v1 | 2026-04-14 | 초안 작성. 팀장급 논의 반영, PD 결정 필요 항목 9건 도출 | 개발실장 |

---

## 13. 후속 조치

- [ ] 본 보고서를 총괄PM이 PD님께 전달 (개발실장은 결과 대기)
- [ ] PD님 ★★★ 3건(호스팅·메모리·외부 접근) 결정 후 Phase 0 착수
- [ ] Phase 0 진입 시 **PD 지시 로그 #4** 산출물 경로 갱신, 상태 `진행중` 유지
- [ ] 각 Phase 완료 시 `공유/QA/` 검증 보고서 병행 작성
- [ ] 본 문서 참조한 운영 규칙(P?? 신규 도입 필요 여부)은 Phase 3~4 안정화 후 팀장급 상의