# Nuxt 개발 지식 위키 — 운영 규칙 (Schema)

이 저장소는 Nuxt(Vue 3) 개발 경험을 축적하는 개인 지식 위키다.
**Raw** → 원본 자료 보관, **Wiki** → 정리된 지식 저장, **CLAUDE.md** → 운영 규칙.

---

## 디렉토리 구조

```
nuxt-wiki/
├── CLAUDE.md          # 이 파일. 위키 운영 규칙
├── raw/               # 개인 원본 자료 (플랫, Claude는 수정하지 않음)
├── wiki/              # 정리된 지식 (Claude가 작성·관리, 플랫)
│   ├── index.md       # 전체 목차 (카테고리별 분류)
│   └── log.md         # 작업 이력
└── reference/         # Nuxt 4.x 공식 문서 (트리 구조 유지, 읽기 전용)
```

**플랫 구조 원칙:** `raw/`와 `wiki/` 내부에는 하위 폴더를 만들지 않는다. 분류는 `wiki/index.md`에서만 한다. `reference/`는 예외 — 공식 문서의 원래 트리 구조를 유지한다.

---

## 카테고리 정의

| 카테고리 | 내용 |
|---|---|
| **핵심 개념** | Nuxt 라이프사이클, 렌더링 모드(SSR/SSG/ISR/SPA), 라우팅, 레이어, 모듈 시스템 |
| **패턴 & 레시피** | Composable 패턴, 상태관리(Pinia), 폼 처리, 인증 패턴 등 재사용 가능한 솔루션 |
| **모듈 & 에코시스템** | Nuxt 공식·서드파티 모듈, Nitro, UnJS 계열(H3, ofetch, defu 등) |
| **트러블슈팅** | 에러 사례, 삽질 기록, 버전별 Breaking Change, 해결책 |
| **성능 & 배포** | 번들 최적화, 캐싱 전략, CI/CD, Vercel·Netlify·Node 환경별 설정 |
| **아키텍처 결정** | ADR, 설계 고민, 트레이드오프 기록, 패턴 선택 근거 |

---

## 운영 방법 3가지

### 1. 자료 넣기 (Ingest)

**트리거:** 사용자가 `raw/`에 파일을 추가하거나, 텍스트/URL을 메시지로 붙여넣을 때.

**Claude가 할 일:**
1. 원본 자료 읽기 (raw 파일이면 그대로, 텍스트면 `raw/`에 파일로 저장)
2. 관련 위키 페이지 파악 — 기존 페이지 업데이트 or 새 페이지 생성
3. 각 위키 페이지 작성/갱신 (아래 페이지 형식 참고)
4. `wiki/index.md` 목차 업데이트
5. `wiki/log.md`에 작업 이력 추가

**판단 기준:**
- 기존 페이지와 70% 이상 주제가 겹치면 → 해당 페이지에 병합
- 새로운 주제면 → 새 페이지 생성
- 한 자료에서 여러 주제가 나오면 → 여러 페이지에 분산하고 서로 [[교차참조]]

---

### 2. 질문하기 (Query)

**트리거:** 사용자가 Nuxt 관련 질문을 할 때.

**Claude가 할 일:**
1. `wiki/index.md`와 관련 위키 페이지를 먼저 확인
2. 위키 기반으로 답변 (어느 페이지를 참고했는지 명시)
3. 위키에 없는 내용이면 → 솔직하게 "위키에 없음"을 밝히고 일반 지식으로 보완
4. 답변 과정에서 새로 정리할 가치가 있는 내용이 나오면 → 사용자에게 위키 추가 여부 제안

---

### 3. 건강검진 (Lint)

**트리거:** 사용자가 "건강검진", "lint", "위키 점검"을 요청할 때.

**Claude가 할 일:**
1. 모든 위키 페이지 스캔
2. 아래 항목 체크:
   - 끊긴 [[위키링크]] (참조 대상 페이지가 없는 것)
   - 내용 충돌 (두 페이지에서 상반된 내용)
   - 고아 페이지 (index.md에 없는 페이지)
   - 업데이트 필요 (Nuxt 버전과 맞지 않는 낡은 내용)
   - 빈 섹션 또는 TODO로만 채워진 페이지
3. 문제 목록을 리포트하고, 수정 여부를 사용자에게 확인 후 처리
4. `wiki/log.md`에 건강검진 결과 기록

---

## 위키 페이지 형식

```markdown
# 페이지 제목

> **카테고리:** 핵심 개념 | 패턴 & 레시피 | 모듈 & 에코시스템 | 트러블슈팅 | 성능 & 배포 | 아키텍처 결정
> **최종 수정:** YYYY-MM-DD
> **관련:** [[페이지명]], [[페이지명]]

## 요약
한두 문장으로 이 페이지가 무엇을 다루는지.

## 본문
...

## 참고 / 출처
- raw/파일명 (원본 자료)
- 외부 링크
```

**작성 규칙:**
- 제목은 `wiki/페이지명.md` 형태로 저장. 영문 소문자 + 하이픈 (예: `nuxt-rendering-modes.md`)
- 페이지 간 참조는 반드시 `[[페이지명]]` 형식 사용 (확장자 제외)
- 코드 예시는 언어 지정 코드블록으로 작성
- 의견·추측은 `> ⚠️ 주의:` 또는 `> 💡 경험:` 인용 블록으로 구분
- Nuxt 버전 의존적인 내용은 버전을 명시 (예: `Nuxt 3.x`, `Nuxt 4.x`)

---

## 파일 네이밍 규칙

| 종류 | 형식 | 예시 |
|---|---|---|
| raw 원본 | 자유 (원본 이름 유지 권장) | `nuxt-4-migration-guide.md`, `adr-auth-strategy.txt` |
| wiki 페이지 | `kebab-case.md` | `nuxt-rendering-modes.md`, `usefetch-pattern.md` |
| 트러블슈팅 | `ts-{짧은 설명}.md` | `ts-hydration-mismatch.md` |
| ADR | `adr-{주제}.md` | `adr-state-management.md` |

---

## 참조 라이브러리 (Reference)

`reference/`는 Nuxt 4.x 공식 문서 클론이다. 읽기 전용 — 절대 수정하지 않는다.

**언제 사용하나:**
- 사용자 질문에 위키(`wiki/`)만으로 답이 부족할 때 `reference/`를 먼저 검색
- 위키 페이지 작성 시 공식 문서 내용을 인용·발췌할 때

**검색 방법:**
```bash
grep -r "키워드" reference/
# 또는 폴더 구조로 직접 탐색:
# reference/1.getting-started/  → 시작하기, 설치, 설정
# reference/2.directory-structure/ → 파일 구조
# reference/3.guide/           → 개념 가이드 (라우팅, 상태관리 등)
# reference/4.api/             → 컴포저블, 유틸리티, 컴포넌트 API
# reference/5.community/       → 기여 가이드
# reference/6.bridge/          → Nuxt 2→3 브릿지
# reference/7.migration/       → 마이그레이션 가이드
```

**출처 표기:** `reference/` 내용을 위키에 쓸 때는 `reference/{경로}` 형태로 명시한다.

`raw/`와의 차이: `raw/`는 "내가 정리할 개인 자료", `reference/`는 "필요할 때 찾아볼 공식 자료".

---

## 중요한 제약

- `raw/` 파일은 절대 수정하지 않는다.
- `reference/` 파일도 절대 수정하지 않는다.
- 위키 페이지를 삭제할 때는 사용자에게 먼저 확인한다.
- `wiki/log.md`는 항상 최신 상태로 유지한다.
- 위키 내용이 raw 원본과 충돌하면 raw 원본을 우선하되, 충돌 사실을 페이지에 명시한다.