BurningTimesAi/개발실/조직공지/GIT동기화_준비패키지_v1.md

# 조직 Git 동기화 — 병렬 착수 준비 패키지 v1

- 문서 번호: GIT동기화_준비패키지_v1
- 작성일: 2026-04-15
- 작성자: 개발실장
- 목적: **PD님 승인 즉시 Phase 0·1 병렬 착수**가 가능하도록 기술 산출물(초안) 사전 준비
- 연관 문서: `GIT동기화방안_v2.md`, `공유/공통_업무_규칙_개정_제안_C14_C15_v1.md`
- 상태: 초안, PD님 승인 후 적용

---

## 1. `.gitignore` 초안

```gitignore
# ===== 로컬 환경 설정 =====
paths.local.json
settings.local.json
*.local.json
.env
.env.*
!.env.example
!.env.template

# ===== 시크릿·키 =====
*.key
*.pem
*.p12
*.pfx
secrets/

# ===== Unity 프로젝트 =====
# Unity는 별도 repo. 조직 repo에 혼입 금지
Library/
Temp/
Logs/
UserSettings/
MemoryCaptures/
*.unitypackage
Assets/StreamingAssets/aa/
Build/
Builds/

# ===== 기획실 대용량·산출물 =====
기획실/.cache/
*.xlsm     # 밸런싱 엑셀. LFS 결정 전까지 제외 (기획팀장 결정 대기)
*.xlsx
*.xls
~$*.xlsm   # 엑셀 잠금 파일

# ===== OS·에디터 산출물 =====
.DS_Store
Thumbs.db
desktop.ini
*.swp
*.bak
.vscode/
.idea/
*.suo
*.user
*.userosscache
*.sln.docstates

# ===== DB·로그 =====
*.sqlite
*.sqlite-journal
*.db
*.log

# ===== 임시·백업 =====
*.tmp
*.orig
*.rej
backup/
tmp/

# ===== Python 캐시 =====
__pycache__/
*.pyc
*.pyo

# ===== Node =====
node_modules/

# ===== Git·CI 산출물 =====
.cache/
coverage/
dist/
build/
```

**예외 권고**:
- `.env.example`·`.env.template`·`paths.local.json.template`·`settings.local.json.template`은 **커밋 허용** (구조만 공유)

---

## 2. `.gitattributes` 초안

```gitattributes
# 줄바꿈 통일 (서버팀장 권고 — Windows/macOS/Linux 혼용 대응)
* text=auto eol=lf

# 바이너리 명시
*.png binary
*.jpg binary
*.jpeg binary
*.pdf binary
*.zip binary
*.7z binary
*.sqlite binary

# 한글 경로·BOM 안전 처리
*.md text eol=lf
*.json text eol=lf
*.ps1 text eol=crlf   # PowerShell은 CRLF 유지
*.sh text eol=lf

# 머지 충돌 감소 (append-heavy 파일)
공유/일일보고/*.md merge=union
공유/PD_지시_트래킹/*.md merge=union
```

`merge=union` 은 append 위주 파일에서 **양쪽 변경분을 자동 병합**하여 머지 충돌 빈도를 줄인다.

---

## 3. `paths.local.json.template`

```json
{
  "_description": "환경별 로컬 경로 설정. 이 파일을 paths.local.json으로 복사 후 실값 입력. 실값 파일은 .gitignore로 커밋 금지.",
  "_hostname_example": "NERDNAVIS-MAIN-PC | HOME-PC | LAPTOP-01",

  "NERDNAVIS_ROOT": "C:/Users/PC/Documents/너드나비스",
  "UNITY_PROJECT_ROOT": "D:/NerdNavis/FilGoodBandits/DeckBuilding",
  "FRAMEWORK_PKG_ROOT": "D:/NerdNavis/NerdNavis.Framework",
  "TABLE_EXPORT_ROOT": "${UNITY_PROJECT_ROOT}/Assets/ResWork/Table/Export",
  "GITEA_URL": "http://nas.local:3000",

  "_per_pc_hint": {
    "회사_PC": "D 드라이브 Unity, C 드라이브 org",
    "집_PC": "E 드라이브 Unity 예시",
    "노트북": "C 드라이브 통합 예시"
  }
}
```

에이전트·스크립트는 `$NERDNAVIS_ROOT/paths.local.json` 을 Read → 환경변수 치환 후 경로 사용.

---

## 4. CLAUDE.md 하드코딩 경로 스캔 대상

현 상태에서 CLAUDE.md·문서에 하드코딩된 절대경로를 `$VAR` 치환 후보로 목록화.

```
하드코딩 대상 (grep 예비 결과):
- 루트 CLAUDE.md: 없음 (상대경로 위주)
- 개발실 CLAUDE.md:
  * D:/NerdNavis/FilGoodBandits/DeckBuilding/         → $UNITY_PROJECT_ROOT
  * D:/NerdNavis/FilGoodBandits/DeckBuilding/Assets/ResWork/Table/Export/  → $TABLE_EXPORT_ROOT
  * C:/Users/PC/Documents/너드나비스/기획실/밸런싱/    → $NERDNAVIS_ROOT/기획실/밸런싱/
  * C:/Users/PC/Documents/너드나비스/기획실/.cache/    → $NERDNAVIS_ROOT/기획실/.cache/
- 프로젝트 숙지 문서 (01~10): 상동
- PD 지시 로그: 상대경로 주로 사용. 일부 D: 경로 존재
```

**조치**: Phase 0에서 grep 전수 → 치환 매핑 확정 → Phase 1 초기 커밋 전 일괄 치환 PR.

---

## 5. Phase 0 dry-run 체크리스트

호스팅·외부 접근 결정과 **독립적으로 즉시 착수 가능**한 기술 준비 항목.

### 5.1 현 환경 스캔
- [ ] 조직 루트 디렉토리 전체 용량 측정 (예상 제외/포함 분리 확인)
- [ ] `D:/`·`C:/` 하드코딩 경로 grep 전수 → 치환 매핑 확정
- [ ] 파일명 한글·특수문자 목록화 → Gitea·Git 호환성 확인
- [ ] `data/nerdnavis.sqlite` 용도·용량 확인 (포함 여부 결정 안건 ⑥)

### 5.2 민감정보 사전 스캔
- [ ] gitleaks 설치 (`gitleaks detect --source . --no-git`)
- [ ] `nerdnavis-framework` 기존 레포 history 스캔 (평문 키 유입 이력)
- [ ] `.env` 류·API 키·AES 키 흔적 `grep -rE "(api_key|secret|password|token|aes_key)" .`
- [ ] PlayFab·Gitea·NAS 자격증명 위치 식별

### 5.3 구조 검증
- [ ] `.gitignore`·`.gitattributes` 초안을 현 디렉토리에 임시 적용하여 `git status` 시뮬레이션 (실제 init 없이 `git --git-dir=/tmp/test-dry ...` 방식)
- [ ] 제외 대상 파일이 실제로 제외되는지 확인
- [ ] `merge=union` 동작 검증 (일일보고 파일 두 지점 동시 수정 시나리오)

### 5.4 C14-4 참조 무결성 사전 점검
- [ ] 루트/개발실/기획실 CLAUDE.md 간 내용 중복 목록화
- [ ] 중복 항목을 참조 링크로 전환할 리팩터링 초안 작성

### 5.5 Phase 0 완료 조건
- 상기 모든 체크 `[x]` 처리 + 결과 요약 문서 작성 (`GIT동기화_Phase0_dry-run_결과_v1.md`)
- 서버팀장 보안 항목 전수 통과
- 총괄PM 검토 통과

---

## 6. PC별 셋업 스크립트 초안

### 6.1 Windows (`setup/setup_windows.ps1`)

```powershell
# 조직 Git 동기화 — Windows PC 셋업
# 사용: 관리자 권한 PowerShell에서 실행
# .\setup_windows.ps1 -NerdNavisRoot "C:\Users\PC\Documents\너드나비스" -UnityRoot "D:\NerdNavis\..."

param(
    [string]$NerdNavisRoot = "C:\Users\PC\Documents\너드나비스",
    [string]$UnityRoot     = "D:\NerdNavis\FilGoodBandits\DeckBuilding",
    [string]$FrameworkRoot = "D:\NerdNavis\NerdNavis.Framework",
    [string]$GiteaUrl      = "http://nas.local:3000"
)

$ErrorActionPreference = "Stop"

# 1. Git·Gitea 연결 확인
git --version
if (-not $?) { throw "Git이 설치되지 않았습니다." }

# 2. org repo clone
if (-not (Test-Path $NerdNavisRoot)) {
    Write-Host "Cloning nerdnavis-org..."
    git clone "$GiteaUrl/nerdnavis/nerdnavis-org.git" $NerdNavisRoot
} else {
    Write-Host "Existing directory found. Pulling latest..."
    Push-Location $NerdNavisRoot
    git pull
    Pop-Location
}

# 3. paths.local.json 생성
$pathsFile = Join-Path $NerdNavisRoot "paths.local.json"
$paths = @{
    NERDNAVIS_ROOT     = $NerdNavisRoot
    UNITY_PROJECT_ROOT = $UnityRoot
    FRAMEWORK_PKG_ROOT = $FrameworkRoot
    GITEA_URL          = $GiteaUrl
    HOSTNAME           = $env:COMPUTERNAME
}
$paths | ConvertTo-Json | Out-File -FilePath $pathsFile -Encoding utf8
Write-Host "paths.local.json 작성 완료: $pathsFile"

# 4. Claude 사용자 메모리 연결 (junction)
$claudeMemoryBase = "$env:USERPROFILE\.claude\projects"
$orgMemoryTarget  = Join-Path $NerdNavisRoot "memory\org"

# 해시 폴더 자동 탐지
$hashDir = Get-ChildItem $claudeMemoryBase -Directory | Where-Object {
    $_.Name -like "*너드나비스*"
} | Select-Object -First 1

if ($hashDir) {
    $memLink = Join-Path $hashDir.FullName "memory"
    if (Test-Path $memLink) {
        Write-Host "기존 memory 폴더를 백업 후 junction으로 교체..."
        Rename-Item $memLink "$memLink.bak-$(Get-Date -Format yyyyMMddHHmmss)"
    }
    cmd /c mklink /J "`"$memLink`"" "`"$orgMemoryTarget`""
    Write-Host "Junction 생성 완료: $memLink → $orgMemoryTarget"
} else {
    Write-Warning "Claude 프로젝트 해시 폴더를 찾지 못했습니다. 수동 연결 필요."
}

# 5. pre-commit hook (gitleaks)
Push-Location $NerdNavisRoot
$hookFile = ".git\hooks\pre-commit"
@"
#!/bin/sh
# gitleaks pre-commit (secrets scan)
gitleaks protect --staged --no-banner
if [ `$? -ne 0 ]; then
    echo "[pre-commit] gitleaks detected secrets. Commit aborted."
    exit 1
fi
"@ | Out-File -FilePath $hookFile -Encoding ascii
Pop-Location

Write-Host "셋업 완료. 'git pull' 로 최신 상태 유지 권장."
```

### 6.2 macOS (`setup/setup_macos.sh`)

```bash
#!/bin/bash
# 조직 Git 동기화 — macOS PC 셋업
# 사용: bash setup_macos.sh

set -euo pipefail

NERDNAVIS_ROOT="${NERDNAVIS_ROOT:-$HOME/Documents/너드나비스}"
UNITY_ROOT="${UNITY_ROOT:-$HOME/dev/DeckBuilding}"
FRAMEWORK_ROOT="${FRAMEWORK_ROOT:-$HOME/dev/NerdNavis.Framework}"
GITEA_URL="${GITEA_URL:-http://nas.local:3000}"

# 1. git 확인
command -v git >/dev/null 2>&1 || { echo "git 필요"; exit 1; }

# 2. clone or pull
if [ ! -d "$NERDNAVIS_ROOT" ]; then
    git clone "$GITEA_URL/nerdnavis/nerdnavis-org.git" "$NERDNAVIS_ROOT"
else
    git -C "$NERDNAVIS_ROOT" pull
fi

# 3. paths.local.json
cat > "$NERDNAVIS_ROOT/paths.local.json" <<EOF
{
  "NERDNAVIS_ROOT": "$NERDNAVIS_ROOT",
  "UNITY_PROJECT_ROOT": "$UNITY_ROOT",
  "FRAMEWORK_PKG_ROOT": "$FRAMEWORK_ROOT",
  "GITEA_URL": "$GITEA_URL",
  "HOSTNAME": "$(hostname)"
}
EOF

# 4. 메모리 symlink
CLAUDE_BASE="$HOME/.claude/projects"
HASH_DIR=$(find "$CLAUDE_BASE" -maxdepth 1 -type d -name "*너드나비스*" | head -n1)
if [ -n "$HASH_DIR" ]; then
    MEM="$HASH_DIR/memory"
    [ -e "$MEM" ] && mv "$MEM" "$MEM.bak-$(date +%s)"
    ln -s "$NERDNAVIS_ROOT/memory/org" "$MEM"
fi

# 5. pre-commit hook
cat > "$NERDNAVIS_ROOT/.git/hooks/pre-commit" <<'HOOK'
#!/bin/sh
gitleaks protect --staged --no-banner || { echo "secrets detected"; exit 1; }
HOOK
chmod +x "$NERDNAVIS_ROOT/.git/hooks/pre-commit"

echo "셋업 완료."
```

---

## 7. 세션 pull/push 관례 (향후 CLAUDE.md 환기 메모 편입안)

```markdown
### [세션 시작 시점]
- `git pull` 로 조직 repo 최신화 (C14 변동비이므로 매 턴 로드 아님. 사용자 또는 초기 에이전트가 수동/훅으로 1회)
- 충돌 시: C2 근본 해결 원칙에 따라 양쪽 변경분 의미 파악 후 병합. 임의 덮어쓰기 금지

### [세션 종료 또는 주요 단계 종료 시점]
- `git add` 로 당일 변경분 스테이징
- gitleaks pre-commit 통과 확인
- `git commit` + 의미 있는 메시지 (PD 지시 #번호·C13 등 연관 규칙 표기)
- `git push` 로 NAS Gitea 동기화
```

**타이밍**: Phase 3 진입 시 루트 CLAUDE.md 환기 메모에 추가 (고정비 증가이므로 PD님 승인 선행).

---

## 8. 머지 충돌 관리 (append-heavy 파일)

| 파일 | 전략 | 비상 대응 |
|------|-----|----------|
| `공유/일일보고/YYYY-MM-DD_*.md` | 일자별 파일 분할 (현 규칙 유지) + `merge=union` | 동일 일자 동일 부서 동시 작업 시점이 발생하면 **일자 뒤 환경 접미** (`2026-04-15_개발실_home.md` 등)로 파일 분할 규칙 변경 — 다중 환경 동시 발생 시 결정 |
| `공유/PD_지시_트래킹/개발실_PD_지시_로그.md` | 단일 파일 유지 + `merge=union` | 충돌 시 수동 병합 (지시 번호 단조 증가이므로 해결 용이) |
| `MEMORY.md` | 단일 + `merge=union` | 인덱스 1줄 단위라 union 안전 |
| `CLAUDE.md` | 단일 + 수동 병합 | 고정비 자산. 변경 잦지 않음 |

**`merge=union` 한계**: 같은 줄을 동시에 수정하면 여전히 충돌. 대응은 Phase 2 검증에서 시뮬레이션.

---

## 9. 산출물 목록

Phase 0 dry-run 완료 시점 산출물:

- [ ] `GIT동기화_Phase0_dry-run_결과_v1.md` — 스캔 결과·치환 매핑·민감정보 스캔 결과
- [ ] `.gitignore` 확정본
- [ ] `.gitattributes` 확정본
- [ ] `paths.local.json.template` 확정본
- [ ] `setup/setup_windows.ps1` 확정본
- [ ] `setup/setup_macos.sh` 확정본
- [ ] C14-4 참조 무결성 리팩터링 목록
- [ ] PD님 승인 안건 문서 (v2의 ⑥·⑦·⑧·⑨·⑩ 결정)

Phase 1 초기 커밋 시점 산출물:

- [ ] NAS Gitea `nerdnavis-org`·`nerdnavis-org-secrets` 레포 생성
- [ ] 초기 커밋
- [ ] 회사 PC에서 `setup_windows.ps1` 검증
- [ ] Phase 2 진입 준비 완료

---

## 10. 변경 이력

| 버전 | 일자 | 작성자 | 내용 |
|------|------|-------|-----|
| v1 | 2026-04-15 | 개발실장 | 초안. Phase 0 dry-run 기술 준비 일체 포함 |