185 lines
8.1 KiB
Markdown
185 lines
8.1 KiB
Markdown
# 신 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`)로 자유 선택 가능.
|
||
|
||
```powershell
|
||
# 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
|
||
|
||
```powershell
|
||
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
|
||
|
||
```bash
|
||
cd <레포 루트>
|
||
bash setup/setup_macos.sh
|
||
```
|
||
|
||
**체크**
|
||
- [ ] 스크립트 정상 종료
|
||
- [ ] `paths.local.json` 실존
|
||
- [ ] Claude 프로젝트 해시 폴더에서 `memory` junction 생성 로그 확인
|
||
- [ ] `.claude/settings.json`이 루트·`개발실/.claude/`·`기획실/.claude/` 3곳 모두 존재 (3중 배치 무결성)
|
||
|
||
---
|
||
|
||
## 3. paths.local.json 실값 확인·보정
|
||
|
||
자동 추정값이 실제와 다른 경우 수동 보정.
|
||
|
||
```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. 검증 스크립트 실행 (필수)
|
||
|
||
```powershell
|
||
.\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
|
||
|
||
```bash
|
||
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` (세션 시작 표준 절차)
|