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 초안

# ===== 로컬 환경 설정 =====
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 초안

# 줄바꿈 통일 (서버팀장 권고 — 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

{
  "_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)

# 조직 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)

#!/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 환기 메모 편입안)

### [세션 시작 시점]
- `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 기술 준비 일체 포함