148 lines
5.3 KiB
Markdown
148 lines
5.3 KiB
Markdown
# 신 PC 셋팅 체크리스트 v1
|
||
|
||
> **발행**: 2026-04-15 (개발실장 주도, 총괄PM·PD님 공유)
|
||
> **목적**: 회사/집/노트북 등 새로운 PC에서 조직 레포(`NerdNavisAi`)를 가동할 때 동일한 재현 결과를 보장하기 위한 표준 체크리스트.
|
||
> **근거**: PD 지시 #7·#7-α (Git 동기화 완료) → #8 (개발실 셋팅 마무리 잔여 과제 3종).
|
||
> **원칙**: C5 (정보의 정직성) · C14 (토큰 최소화 — 본 문서가 유일한 셋팅 SOT) · `공유/공통_업무_규칙.md` P-설정 관련 조항 준수.
|
||
|
||
---
|
||
|
||
## 0. 전제
|
||
|
||
- Windows 10/11 + PowerShell 5.1 이상 (또는 macOS/Linux — macOS는 `setup/setup_macos.sh` 사용)
|
||
- Git 설치 완료
|
||
- Claude Code 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` 자동 생성 (레포 루트 드라이브 기준으로 `UNITY_PROJECT_ROOT`·`FRAMEWORK_PKG_ROOT` 추정)
|
||
2. `memory/org/` 디렉토리 준비
|
||
3. `~/.claude/projects/<해시>/memory/` junction → `memory/org/` 연결
|
||
|
||
### macOS / Linux
|
||
|
||
```bash
|
||
cd <레포 루트>
|
||
bash setup/setup_macos.sh
|
||
```
|
||
|
||
**체크**
|
||
- [ ] 스크립트 정상 종료 (`셋업 완료. 'git pull'로 최신 상태 유지 권장.` 메시지)
|
||
- [ ] `paths.local.json` 파일 실존
|
||
- [ ] Claude 프로젝트 해시 폴더에서 `memory` junction 생성 로그 확인
|
||
|
||
---
|
||
|
||
## 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에 존재하거나 의도적으로 빈 값
|
||
- [ ] 파일이 `.gitignore` 로 추적 제외 상태 (`git status` 에 나타나지 않음)
|
||
|
||
---
|
||
|
||
## 4. 검증 스크립트 실행 (필수)
|
||
|
||
```powershell
|
||
# Windows
|
||
.\scripts\verify_setup.ps1
|
||
```
|
||
|
||
3축 검증을 수행:
|
||
1. **파일 존재**: `paths.local.json` 파싱·필수 키·`memory/org` 실체
|
||
2. **OS 동작**: junction 의 reparse point 속성·타깃 경로
|
||
3. **실행 결과**: `MEMORY.md` junction 경유 읽기 가능 여부, 경로 추상화 잔존 구 경로 스캔, `.gitignore` 규칙, 조직 공용 승인 `.claude/settings.json`
|
||
|
||
**체크**
|
||
- [ ] `exit 0` 로 종료 (= "셋팅 검증 통과. 작업 착수 가능.")
|
||
- [ ] `[FAIL]` 라인 0건
|
||
- [ ] `[WARN]` 은 본인 환경상 허용 가능한 것인지 육안 확인 (예: Unity 미설치 PC의 `UNITY_PROJECT_ROOT` 경고)
|
||
|
||
---
|
||
|
||
## 5. Claude Code 동작 확인
|
||
|
||
```bash
|
||
# 레포 루트에서
|
||
claude
|
||
```
|
||
|
||
- [ ] `MEMORY.md` 가 세션 초입에 자동 로드됨 (user memory 인덱스 표시)
|
||
- [ ] `CLAUDE.md` (조직 최상위) 의 지시가 인지됨 — "PD님"·"총괄PM" 호칭 사용
|
||
- [ ] 조직 공용 승인(`.claude/settings.json`) 의 Bash/Edit/Write 포괄 허용이 반영됨 (개별 승인 반복 없음)
|
||
|
||
---
|
||
|
||
## 6. 자주 발생하는 문제
|
||
|
||
| 증상 | 원인 | 조치 |
|
||
|------|------|------|
|
||
| `verify_setup.ps1` 파싱 에러 | 파일 인코딩이 UTF-8 BOM 아님 | 레포 재 clone 또는 스크립트 재 pull |
|
||
| junction 이 실체 폴더로 존재 | Claude Code 가 기존에 실제 `memory` 폴더를 만들어둠 | `setup_windows.ps1` 재실행 (자동 백업 후 junction 교체) |
|
||
| `MEMORY.md` 안 읽힘 | junction 타깃이 `memory` 루트가 아니라 `memory/org` 여야 함 | `setup` 스크립트는 정상이지만 수동 생성 시 `memory -> memory/org` 구조 확인 |
|
||
| `paths.local.json` 이 커밋되려 함 | `.gitignore` 누락 | 레포 재 pull 또는 `.gitignore` 에 `paths.local.json` 라인 존재 확인 |
|
||
| PC 간 승인 설정 불일치 | `.claude/settings.local.json` 은 `.gitignore` 대상이라 이동 불가 | 공용 승인은 **`.claude/settings.json`** (커밋됨) 로 유지. 개별 실험은 local 로 분리 |
|
||
|
||
---
|
||
|
||
## 7. 변경 이력
|
||
|
||
| 버전 | 일자 | 변경 | 담당 |
|
||
|------|------|------|------|
|
||
| v1 | 2026-04-15 | 최초 발행 (PD 지시 #8 처리) | 개발실장 |
|
||
|
||
---
|
||
|
||
## 8. 참조
|
||
|
||
- `setup/setup_windows.ps1`, `setup/setup_macos.sh`
|
||
- `scripts/verify_setup.ps1`
|
||
- `paths.local.json.template`
|
||
- `README.md` (레포 루트)
|
||
- `공유/공통_업무_규칙.md` (부록 A: 작업 착수 체크)
|
||
- `memory/org/MEMORY.md` 인덱스 — [PC 간 승인 설정 일관성](../../memory/org/feedback_permissions_portability.md)
|