# 조직 Claude 에이전트 자산 Git 동기화 방안 v2

- 문서 번호: GIT동기화방안_v2
- 작성일: 2026-04-15
- 작성자: 개발실장 (클라이언트팀장·서버팀장·pm-general 수렴 통합. 기획팀장 의견은 pm-general 경유 기획실 세션에서 별도 수렴)
- 스코프: **조직 전체(PM·기획·개발) Claude 에이전트 자산**
- 상태: v1 → v2 개정. **총괄PM 이관 후 PD님 총괄PM 세션 최종 승인 대기**
- 근거: PD님 2026-04-15 직접 지시 (PD 지시 로그 #4 → #6 범위 확장)
- 선행 승인 사항: C14(토큰 최소화 우선 설계)·C15(일정·기한 개념 배제) 신규 코어룰 신설 (별도 문서 `공유/공통_업무_규칙_개정_제안_C14_C15_v1.md`)

---

## 1. v1 대비 v2 변경점

v1은 **개발실 스코프에 머물러 조직 전체 설계를 포섭하지 못했다.** v2는 다음을 보정한다.

| 항목 | v1 | v2 |
|------|----|----|
| 스코프 | 개발실 자산 중심 | **조직 전체(PM·기획·개발)** |
| ★★★ 결정 3건 | 호스팅·메모리·외부 접근 | **2건 소거** (호스팅=NAS Gitea 확정, 외부 접근=기존 경로 재활용). 남는 결정 A/B/C 3건으로 재정리 |
| 코어룰 반영 | 없음 | **C14·C15 신규 준수 설계**로 전면 재작성 |
| 메모리 구조 | 하이브리드(org/local) | **단일 공용 `memory/org/`** (PD님 지시). local 디렉토리는 확장 여지로만 설계 |
| 기획팀장 의견 | 미수렴 | **pm-general 경유 수렴 이관 명시** |

---

## 2. 확정 전제 (PD님 결정 반영)

- ✅ **호스팅**: 너드나비스 NAS Gitea (단일 SOT). 기존 `nerdnavis-framework` 코어 레포 운영 중
- ✅ **외부 환경 접근 경로**: 기존 코어 레포 접근 경로 재활용 (추가 VPN·Cloudflare 터널 구축 불필요)
- ✅ **메모리 구조**: 단일 공용 `memory/org/` (PC·작업자 분리 미사용, 확장 여지만 설계)
- ✅ **저장소 구성**: 단일 `nerdnavis-org` (Private) 권고. 시크릿은 **`nerdnavis-org-secrets` 별도 분리**(서버팀장 권고)
- ✅ **C14·C15 준수**: CLAUDE.md 통합 금지, 고정비·변동비 분리, 일정 용어 금지

---

## 3. 조직 전체 자산 인벤토리

### 3.1 루트 (`C:/Users/PC/Documents/너드나비스/`)

| 경로 | 유형 | 포함 | 비고 |
|------|-----|-----|-----|
| `CLAUDE.md` | 조직 루트 CLAUDE | O (고정비) | 상위 SOT |
| `.claude/agents/pm-general.md` | 총괄PM 에이전트 | O | 조직 전체 관할 |
| `data/nerdnavis.sqlite` | DB 바이너리 | **X** | 용량·민감도 검토 후 결정. 기본 제외 |

### 3.2 개발실 (`개발실/`)

| 경로 | 유형 | 포함 | 비고 |
|------|-----|-----|-----|
| `CLAUDE.md` | 개발실 CLAUDE | O | 참조 링크 방식으로 재정비 필요 (C14-4) |
| `⚠️_C13_절대원칙_재공지_2026-04-15.md` | 긴급 공지 | O | |
| `조직공지/` | 조직 공지 문서 (GIT동기화방안 v1·v2 등) | O | |
| `코어_설계/01_아키텍처_개요_v1.md`, `02_수상한잡화점_추출대상_v1.md` | 설계 문서 | O | 변동비 |
| `코어_설계/_skeleton/` | UPM 패키지 스켈레톤 | **분리 검토** | 클라이언트팀장 권고: 신규 `nerdnavis-framework` 패키지 레포로 분리 이관 가능 |
| `프로젝트_숙지/수상한잡화점/01~10_*.md` | 프로젝트 숙지 10종 | O | 변동비 |
| `.claude/agents/개발실장.md`, `클라이언트팀장.md`, `서버팀장.md` | 팀장 에이전트 3종 | O | |
| `.claude/commands/게임플레이·ui-ux·테크아트·최적화·백엔드·db·devops·qa.md` | 실무 commands 8종 | O | |
| `.claude/settings.local.json` | 로컬 설정 | **X** (.gitignore) | 대신 `settings.local.json.template` 커밋 |

### 3.3 기획실 (`기획실/`)

**pm-general 경유 기획팀장 수렴 대상. 예비 인벤토리 (기획팀장 확정 필요)**

| 경로 | 유형 | 포함(예비) | 비고 |
|------|-----|-----------|-----|
| `CLAUDE.md` | 기획실 CLAUDE | O | C14-4 참조 무결성 재정비 |
| `⚠️_PHASE3_HOLD_공지.md` | 긴급 공지 | O | |
| `밸런싱/` | 밸런싱 문서 | **기획팀장 확정 필요** | 엑셀(.xlsm) 대용량 처리 방침(LFS vs 외부 SOT) 결정 항목 |
| `.claude/agents/*.md` 7종 (planning-lead·balance·content·level·narrative·system·ux designer) | 기획실 에이전트 | O | |
| `.claude/skill-modules/*.md` 5종 (onboarding·balance_check·stage_audit·build_analysis·economy_design) | 스킬 모듈 | O | pm-general 추가 질의: 공용화 vs 기획실 전용 |
| `.cache/` (시뮬레이터) | 대용량 산출물 | **X** (.gitignore) | |

### 3.4 공유 (`공유/`)

| 경로 | 유형 | 포함 | 민감도 |
|------|-----|-----|-------|
| `공통_업무_규칙.md` | 조직 공용 SOT | O (고정비 인접) | 조직 공개 필수 |
| `README.md` | 안내 | O | |
| `공통_업무_규칙_개정_제안_C14_C15_v1.md` | C14·C15 제안서 | O | 승인 후 본 규칙에 흡수 |
| `PD_지시_트래킹/` | PD 지시 로그 | **민감** — `nerdnavis-org-secrets` 포함 검토 | 경영상 민감 의사결정 |
| `조직공지/` | 조직 공지 | O | |
| `일일보고/` | 일일보고 | O (append-heavy) | 머지 충돌 관리 필요 |
| `개발실→기획실/`, `기획실→개발실/`, `완료/` | 부서 간 채널 | O | |

### 3.5 사용자 메모리 (외부, `~/.claude/projects/<해시>/memory/`)

| 파일 | 포함 | 비고 |
|------|-----|-----|
| `MEMORY.md` | O (고정비 인덱스) | 조직 공용 인덱스 |
| `user_role.md` | O | 사용자(PD님) 프로필 |
| `feedback_*.md` 7종 | O | 조직 공용 피드백 |
| `project_*.md` 3종 (suspicious_shop·shop_security_pending·new_core_direction) | O | 현재 프로젝트 컨텍스트 |
| `reference_*.md` 2종 (paths·devroom) | O | 경로 참조 |

repo 내 배치: `memory/org/` 단일 공용. 각 PC의 `~/.claude/projects/<해시>/memory/`는 symlink/junction으로 `memory/org/`를 가리킨다.

---

## 4. 저장소 구조 최종안

```
nerdnavis-org/                       ← Gitea Private, Admin=PD·총괄PM
├── CLAUDE.md                        ← 조직 루트 (참조 링크 방식, C14-4)
├── .claude/
│   └── agents/
│       └── pm-general.md
│
├── 공유/
│   ├── 공통_업무_규칙.md             ← 조직 공용 SOT
│   ├── README.md
│   ├── 조직공지/
│   ├── 일일보고/                     ← append-heavy, 일자별 파일 규칙
│   ├── 개발실→기획실/
│   ├── 기획실→개발실/
│   └── 완료/
│
├── 개발실/
│   ├── CLAUDE.md                    ← 참조 링크만
│   ├── .claude/
│   │   ├── agents/ (3종)
│   │   └── commands/ (8종)
│   ├── 조직공지/
│   ├── 코어_설계/ (01·02 문서만)
│   └── 프로젝트_숙지/수상한잡화점/ (01~10)
│
├── 기획실/
│   ├── CLAUDE.md                    ← 참조 링크만
│   ├── .claude/
│   │   ├── agents/ (7종)
│   │   └── skill-modules/ (5종)
│   └── 밸런싱/                      ← xlsm 처리 방침 기획팀장 결정
│
├── memory/
│   └── org/                         ← 조직 공용 메모 (단일)
│       ├── MEMORY.md
│       ├── user_*.md
│       ├── feedback_*.md
│       ├── project_*.md
│       └── reference_*.md
│   (확장 여지 — 현 시점 미사용)
│   └── local/                       ← PC·작업자별 분리 필요 시 추가
│
├── paths.local.json.template        ← 환경별 경로 변수
├── .gitignore
├── .gitattributes
├── setup/
│   ├── setup_windows.ps1            ← PC별 셋업 스크립트
│   └── setup_macos.sh
└── README.md

nerdnavis-org-secrets/               ← Gitea Private, 최소 접근
├── .env.example                     ← 실값 아님, 구조만
├── keys/ (gitignore된 실값 저장소)
└── README.md                        ← 배치 가이드

nerdnavis-framework/                 ← 기존 코어 레포 (유지)
└── (현행 그대로)

_skeleton/                           ← 신규 `nerdnavis-framework` 패키지 레포로 이관 검토
```

**PD 지시 로그·밸런싱 xlsm 최종 배치**는 기획팀장 수렴 결과·보안 검토 반영 후 확정한다.

---

## 5. C14·C15 적용 설계

### 5.1 고정비·변동비 구분 (C14-2)

| 고정비 (매 턴 로드) | 변동비 (on-demand) |
|---|---|
| 루트 `CLAUDE.md` (최소 규칙·구조·호출 가이드) | 개발실/기획실 `CLAUDE.md` (상위 참조만) |
| `MEMORY.md` (인덱스만) | `memory/*.md` 개별 파일 |
| `공유/공통_업무_규칙.md` 참조 링크 | 공통_업무_규칙.md 본문 |
| - | 프로젝트 숙지 문서 10종 |
| - | 에이전트 정의·commands |
| - | 조직공지·일일보고·PD 지시 로그 |

### 5.2 참조 무결성 재정비 (C14-4)

현재 하위 CLAUDE.md에 상위 규칙이 복붙되어 있는지 점검하고, 복붙은 참조 링크로 전환한다.

점검 대상:
- 개발실/CLAUDE.md → 루트 CLAUDE.md 규칙·공통_업무_규칙.md 복붙 여부
- 기획실/CLAUDE.md → 동
- `⚠️_C13_절대원칙_재공지_2026-04-15.md` → 공통_업무_규칙.md C13 본문 참조 링크로 축약

### 5.3 C15 준수 (일정 용어 제거)

v2 본 문서에서도 "이번 주·당일·N시간" 표현을 사용하지 않고, 종속 관계(Phase 0 → 1 → 2)·차단 요인·PD 승인 조건으로만 기술.

---

## 6. 단계별 착수 계획 (일정 단위 배제, C15 준수)

### Phase 0 — dry-run 기술 준비 (호스팅·접근 경로 결정과 독립)

**즉시 착수 가능**. 차단 요인 없음.

- [ ] 현 환경 스캔 — 하드코딩 경로(`C:/Users/PC/Documents/너드나비스/`, `D:/NerdNavis/...`) 전수 grep → `$NERDNAVIS_ROOT`, `$UNITY_PROJECT_ROOT` 치환 후보 목록화
- [ ] `.gitignore` 초안 작성 (Unity·.cache·바이너리·.env·settings.local.json 등)
- [ ] `paths.local.json.template` 초안
- [ ] gitleaks 로컬 dry-run — 현 상태 민감정보 사전 스캔 (서버팀장 권고)
- [ ] `nerdnavis-framework` 기존 레포 history 사전 스캔 (평문 키 유입 여부)

주관: 개발실장 주도 + 서버팀(DevOps·QA 관점).

### Phase 1 — `nerdnavis-org` repo 생성·초기 커밋

**차단 요인**: PD님 최종 승인 + 기획팀장 수렴 완료 + C14·C15 승인.

- [ ] NAS Gitea에 `nerdnavis-org`·`nerdnavis-org-secrets` 레포 생성
- [ ] 현 `C:/Users/PC/Documents/너드나비스/` 구조 초기 커밋 (상기 인벤토리 기준)
- [ ] `.gitignore`·`.gitattributes` 확정 반영
- [ ] `paths.local.json.template` + 회사 PC용 `paths.local.json` 실값 배치(gitignored)
- [ ] pre-commit hook (gitleaks) 설치
- [ ] C14-4 참조 무결성 재정비 (CLAUDE.md 복붙 → 참조 링크 전환)

### Phase 2 — 타 PC(집·노트북) 셋업 검증

**차단 요인**: Phase 1 완료.

- [ ] 집·노트북에서 clone → symlink/junction 설정 → 에이전트 호출 동일성 검증
- [ ] `paths.local.json` 환경별 실값 배치
- [ ] 메모리 경로 연결 (`~/.claude/.../memory` → `memory/org/`)
- [ ] 일일보고·PD 지시 로그 append 충돌 시뮬레이션

### Phase 3 — 상시 운영

**차단 요인**: Phase 2 검증 완료.

- [ ] 세션 시작 시 `git pull`, 종료 시 `git push` 관례 CLAUDE.md 환기 메모에 추가
- [ ] append-heavy 파일 분할 전략 가동 조건 (다중 환경 동시 작업 발생 시점)
- [ ] 서버팀 가동 시 `server/` 디렉토리 신설 + 브랜치·권한 전략 적용 (서버팀장 초안)

---

## 7. 리스크 통합 (팀장급 수렴)

### 클라이언트팀장 제기
1. Unity repo와 조직 repo 간 숙지 문서 drift — SOT 명시 필요
2. `settings.local.json` 로컬값·API 키 실수 커밋
3. 환경별 드라이브 레터 차이로 참조 실패
4. 숙지 문서 CLAUDE.md 통합 압력(C14 위반 유혹)
5. `_skeleton/` 혼입 시 조직 repo 비대화

### 서버팀장 제기
1. 기존 `nerdnavis-framework` history에 평문 키 존재 가능성 — 선스캔 필수
2. Windows/macOS/Linux 줄바꿈·한글 파일명 인코딩 깨짐
3. `.claude/` 공개 repo 착각 실수 커밋 (C8 위반)
4. secrets repo 미구축 상태로 메인 repo 착수 시 .env 유입
5. C15와 상충하는 "동기화 완료 일정" 외부 요청 시 즉시 차단 요인 보고 필요

### 공통 대응
- Phase 0 dry-run에서 선스캔·`.gitignore`·`.gitattributes` 확정
- gitleaks pre-commit hook 3환경 설치
- secrets repo 먼저 구축 후 메인 repo 착수
- CLAUDE.md 환기 메모에 "세션 시작 시 pull / 종료 시 push" + "C14-4 참조 무결성" 상기

---

## 8. 결정 필요 사항 (PD님 승인 안건)

**개발실 권고안은 모두 제시함. PD님이 총괄PM 세션에서 승인만 하시면 Phase 1 진입 가능.**

| # | 안건 | 개발실 권고 | 비고 |
|---|------|-----------|------|
| ① | 저장소 구성 | **A1 단일 `nerdnavis-org` + secrets 분리** | 서버팀장 권고에 따라 secrets는 별도 repo |
| ② | 메모리 구조 | **단일 공용 `memory/org/`, local 확장 여지만** | PD님 지시 반영 |
| ③ | 포함 범위 | **조직 문서·에이전트·CLAUDE.md·공유·메모리 / 제외: Unity·빌드산출물·.cache·.xlsm(기획팀장 확정 시까지)** | |
| ④ | 외부 접근 | **기존 `nerdnavis-framework` 접근 경로 재활용** | 추가 인프라 0 |
| ⑤ | C14·C15 신설 | **별도 제안서 승인** | `공유/공통_업무_규칙_개정_제안_C14_C15_v1.md` |
| ⑥ | `data/nerdnavis.sqlite` 포함 여부 | 기본 제외 권고 (민감·바이너리) | ✅ **확정 (PD님 2026-04-15 일괄 승인): 제외** |
| ⑦ | PD 지시 로그 민감도 | secrets repo 분리 vs 메인 repo Private 유지 | pm-general 분류 검토 중 (별도 처리) |
| ⑧ | 밸런싱 .xlsm | LFS vs 외부 SOT 유지 | ✅ **확정 (PD님 2026-04-15 일괄 승인, 기획팀장 권고 채택): B안 외부 SOT 유지** + 장기 C안(텍스트 변환) 병행 검토 |
| ⑨ | 스킬 모듈 공용화 | 기획실 전용 vs 조직 공용 | ✅ **확정 (PD님 2026-04-15 일괄 승인, 기획팀장 권고 채택): A안 기획실 전용 유지** — 차기 프로젝트 시점 재평가 |
| ⑩ | `_skeleton/` 분리 | 신규 `nerdnavis-framework` 패키지 레포로 이관 | ✅ **확정 (PD님 2026-04-15 일괄 승인): 이관** |

---

## 9. 병렬 착수 준비 완료 선언

본 v2 문서 작성 시점까지, **Phase 0 dry-run 기술 준비는 즉시 착수 가능** 상태로 정비되었다. 차단 요인은 다음 순서로 해제된다:

1. PD님 → C14·C15 승인 → 총괄PM 반영
2. PD님 → v2 ① ~ ⑥·⑩ 결정
3. 기획팀장 → ⑧·⑨ 확정
4. 총괄PM → ⑦ 민감도 분류 확정
5. Phase 1 착수

---

## 10. 변경 이력

| 버전 | 일자 | 작성자 | 내용 |
|------|------|-------|-----|
| v1 | 2026-04-14 | 개발실장 | 초안. 개발실 스코프 한정. ★★★ 결정 3건 도출 |
| v2 | 2026-04-15 | 개발실장 (클라·서버·pm-general 수렴 통합) | 조직 전체 스코프로 재작성. C14·C15 준수. 호스팅·외부 접근 기 결정 반영. 기획팀장 수렴 pm-general 이관 명시 |