feat: 위키 저장소 초기 커밋
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
159
CLAUDE.md
Normal file
159
CLAUDE.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# 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 원본을 우선하되, 충돌 사실을 페이지에 명시한다.
|
||||
Reference in New Issue
Block a user