NerdNavis_AiDev
/
BurningTimesAi
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
BurningTimesAi/공유/조직공지/신PC_셋팅_체크리스트_v2.md

8.1 KiB
Raw Blame History

신 PC 셋팅 체크리스트 v2

발행: 2026-04-15 (총괄PM 주도, PD님 직접 지시 #C16 산하 산출물) 목적: 회사/집/노트북 등 어느 PC에서든 조직 레포(NerdNavisAi)를 가동할 때 동일한 재현 결과를 보장. 근거: PD 지시 #7·#7-α·#8 (Git 동기화·셋업 마무리) → C16 신설 (PC 독립 셋업·세션 시작 표준). 원칙: C5(정보의 정직성) · C14(토큰 최소화 — 본 문서가 유일한 셋팅 SOT) · C16(PC 독립 셋업·세션 시작 표준).

v2 변경 요지: 폴더 칩 UI 사용 절차·승인 반복 트러블슈팅·바로가기 비권장 명시·v1 부분 보존.

0. 전제

  • Windows 10/11 + PowerShell 5.1 이상 (또는 macOS/Linux — macOS는 setup/setup_macos.sh 사용)
  • Git 설치 완료
  • Claude Code 설치 완료 (Windows: Microsoft Store(MSIX) 권장 또는 CLI)
  • Gitea 접근 자격 (PAT 또는 SSH key) 준비

1. Clone

레포 루트는 사용자가 원하는 위치(예: C:/Users/PC/Documents/너드나비스 또는 E:/NerdNavisAi)로 자유 선택 가능.

# HTTPS
git clone https://burning.i234.me/NerdNavis/NerdNavisAi.git "<원하는 경로>"

# 또는 SSH
git clone ssh://git@burning.i234.me:30030/NerdNavis/NerdNavisAi.git "<원하는 경로>"

체크

  • clone 성공
  • cd <레포 루트> 후 git log -1로 최신 커밋 확인

2. 셋업 스크립트 실행

Windows

cd <레포 루트>
.\setup\setup_windows.ps1

스크립트 수행 작업:

  1. paths.local.json 자동 생성 (레포 루트 드라이브 기준 추정)
  2. memory/org/ 디렉토리 준비
  3. ~/.claude/projects/<해시>/memory/ junction → memory/org/ 연결
  4. .claude/settings.json 루트 SOT → 부서 2개(개발실/.claude/·기획실/.claude/) 자동 동기 복제 (C16-1)

-CreateShortcuts 옵션: non-MSIX(독립 실행) Claude 환경에서만 권장. Windows Store(MSIX) 앱 환경에서는 바로가기가 작동하지 않으므로 비권장. C16-2 참조.

macOS / Linux

cd <레포 루트>
bash setup/setup_macos.sh

체크

  • 스크립트 정상 종료
  • paths.local.json 실존
  • Claude 프로젝트 해시 폴더에서 memory junction 생성 로그 확인
  • .claude/settings.json이 루트·개발실/.claude/·기획실/.claude/ 3곳 모두 존재 (3중 배치 무결성)

3. paths.local.json 실값 확인·보정

자동 추정값이 실제와 다른 경우 수동 보정.

{
  "NERDNAVIS_ROOT": "<레포 루트 실경로>",
  "UNITY_PROJECT_ROOT": "<Unity 프로젝트 실경로 — 미설치 시 빈 값 가능>",
  "FRAMEWORK_PKG_ROOT": "<NerdNavis.Framework 실경로 — 미설치 시 빈 값 가능>",
  "TABLE_EXPORT_ROOT": "${UNITY_PROJECT_ROOT}/Assets/ResWork/Table/Export",
  "GITEA_URL": "https://burning.i234.me",
  "GITEA_SSH": "ssh://git@burning.i234.me:30030",
  "HOSTNAME": "<본 PC 식별자>"
}

체크

  • NERDNAVIS_ROOT가 레포 실경로와 일치
  • UNITY_PROJECT_ROOT·FRAMEWORK_PKG_ROOT가 본 PC에 존재하거나 의도적으로 빈 값
  • paths.local.json이 git status에 나타나지 않음 (gitignore 제외 상태)

4. 검증 스크립트 실행 (필수)

.\scripts\verify_setup.ps1

3축 검증:

  1. 파일 존재: paths.local.json·memory/org 실체·.claude/settings.json 3중 배치
  2. OS 동작: junction의 reparse point 속성·타깃 경로
  3. 실행 결과: MEMORY.md junction 경유 읽기·경로 추상화 잔존 구 경로 스캔·.gitignore 규칙

체크

  • exit 0로 종료 ("셋팅 검증 통과. 작업 착수 가능.")
  • [FAIL] 0건
  • [WARN] 육안 확인

5. 세션 시작 (C16-2 표준 절차)

Claude Code Windows Store (MSIX) 앱

  1. Claude 앱을 실행한다.
  2. 화면 하단 입력창 위에 있는 "폴더 칩" UI를 클릭한다 (현재 작업 폴더가 표시되는 작은 칩 모양 버튼).
  3. 폴더 선택 다이얼로그에서 본인 역할에 맞는 폴더를 선택:
    • 총괄PM(메인 세션): 레포 루트 (NerdNavisAi/)
    • 개발팀: <레포 루트>/개발실
    • 기획팀: <레포 루트>/기획실
  4. 워크트리 ☑ 체크는 유지 (기본값).
  5. 새 세션 시작.

중요 (C16-2 실증 확정): MSIX 앱 환경에서는 폴더 칩 UI 선택만이 유일한 방법이다. 바탕화면 바로가기·claude:// URI·바로가기 WorkingDirectory 등 기술적 우회는 모두 작동하지 않는다 (2026-04-15 새 PC 셋업 대장정 실증). 따라서 setup_windows.ps1 -CreateShortcuts로 만든 바로가기는 MSIX 환경에서 참고용일 뿐이며, 실제 진입은 폴더 칩으로 한다.

Claude Code CLI

cd <레포 루트>/개발실    # 또는 /기획실, 또는 루트
claude

세션 시작 직후 의무 (C16-4)

  1. git pull 1회 (이미 pull했다면 생략 가능)
  2. CLAUDE.md "🔔 최근 규칙 변경" 재읽기
  3. 공유/공통_업무_규칙.md C 섹션 본문 재읽기
  4. <부서>/ 루트의 🛑_*·⚠️_*·🚨_* 파일 스캔
  5. 공유/조직공지/ 최신 공지 전수 확인

체크

  • 폴더 칩 UI 또는 cd로 올바른 폴더 진입
  • MEMORY.md 자동 로드 확인
  • CLAUDE.md의 "PD님"·"총괄PM" 호칭 인지
  • .claude/settings.json 포괄 승인 반영 (Edit·Write·git에서 개별 승인 받지 않음)

6. 트러블슈팅 (자주 발생하는 문제)

증상 원인 조치
verify_setup.ps1 파싱 에러 파일 인코딩이 UTF-8 BOM 아님 레포 재 clone 또는 스크립트 재 pull
junction이 실체 폴더로 존재 Claude Code가 기존에 실제 memory 폴더 생성 setup_windows.ps1 재실행 (자동 백업 후 junction 교체)
MEMORY.md 안 읽힘 junction 타깃이 memory 루트가 아니라 memory/org여야 함 setup 정상이면 OK, 수동 생성 시 memory -> memory/org 구조 확인
paths.local.json이 커밋되려 함 .gitignore 누락 레포 재 pull 또는 .gitignore에 라인 존재 확인
md 수정·커밋·push마다 개별 승인 요구됨 .claude/settings.json 3중 배치 누락 또는 부서 폴더 동기 미실행 setup_windows.ps1 재실행으로 루트 SOT → 부서 2개 동기. 그래도 발생 시 부서 폴더의 .claude/settings.json 내용이 루트와 동일한지 확인. 불일치면 루트 내용으로 덮어쓰기 후 커밋
잘못된 폴더로 진입함 폴더 칩 UI 선택 누락 즉시 세션 종료 후 폴더 칩으로 올바른 폴더 재선택. C16-2 위반은 C13 PM 공유 대상
MSIX 환경에서 바로가기가 작동하지 않음 MSIX 앱은 외부 WorkingDirectory·URI 매개변수 무시 바로가기 사용 포기, 폴더 칩 UI 사용 (C16-2 정답)
rm 명령이 차단됨 C16-3 deny 정책 (안전 차단) PowerShell Remove-Item 사용 (deny 우회가 아니라 안전 대체)
.claude/settings.local.json만 존재하고 PC 이동 시 사라짐 local 파일은 .gitignore 대상 공용 승인은 반드시 .claude/settings.json(커밋 대상)에 작성

7. 변경 이력

버전 일자 변경 담당
v1 2026-04-15 최초 발행 (PD 지시 #8 처리) 개발실장
v2 2026-04-15 C16 신설 반영. §5 세션 시작(폴더 칩 UI) 신설, §6 트러블슈팅 확장(승인 반복·MSIX 한계·rm 대체), -CreateShortcuts 비권장 명시, .claude/settings.json 3중 배치 검증 추가 총괄PM

8. 참조

  • 공유/공통_업무_규칙.md C16 (PC 독립 셋업·세션 시작 표준)
  • 공유/조직공지/2026-04-15_C16_핵심규칙_신설_PC독립셋업_세션표준.md
  • setup/setup_windows.ps1, setup/setup_macos.sh
  • scripts/verify_setup.ps1
  • paths.local.json.template
  • memory/org/feedback_permissions_portability.md (PC 간 승인 일관성 실증)
  • memory/org/feedback_setup_verification.md (3축 검증 원칙)
  • memory/org/feedback_session_start_protocol.md (세션 시작 표준 절차)