gil-wiki/CLAUDE.md

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에 건강검진 결과 기록

---

위키 페이지 형식

# 페이지 제목

> **카테고리:** 핵심 개념 | 패턴 & 레시피 | 모듈 & 에코시스템 | 트러블슈팅 | 성능 & 배포 | 아키텍처 결정
> **최종 수정:** 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/를 먼저 검색
• 위키 페이지 작성 시 공식 문서 내용을 인용·발췌할 때

검색 방법:

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 원본을 우선하되, 충돌 사실을 페이지에 명시한다.