# LLM Wiki — 작업 가이드

원본 자료(`raw/`)를 검증된 실무 기술 문서로 바꾸는 문서 파이프라인입니다. 거기서 면접·블로그·포트폴리오 같은 외부 산출물을 만들어 냅니다. Obsidian vault 이자 Claude Code 자동화 저장소입니다.

처음 오셨다면 이 README만 읽으면 작업을 시작할 수 있습니다. 운영 규칙의 전체 정의(SSOT)는 [CLAUDE.md](CLAUDE.md) 에 있습니다.

---

## 핵심 원칙 (이것만 기억하면 됩니다)

```
raw 자료          = 증거 (출처 보존)
wiki/concepts     = 검증된 일반 개념
wiki/projects     = 내 프로젝트에 적용된 검증 사실
wiki/interview·blog·portfolio = 위 canonical 에서 파생된 외부 산출물
```

이 순서는 거꾸로 갈 수 없습니다. 외부 산출물(블로그·면접 문서 등)은 raw나 메모에서 바로 만들지 않고 **반드시** `wiki/concepts` 또는 `wiki/projects` 를 거쳐서 나옵니다.

또 하나의 원칙은 **근거 없는 단정을 쓰지 않는다**입니다. 모든 결정은 출처(Claim ID)로 뒷받침하거나 근거가 없으면 `UNSUPPORTED_DECISION` 으로 솔직히 표시합니다.

---

## 빠른 시작

가장 흔한 작업 흐름은 이렇습니다.

```bash
# 1) 새 작업을 시작합니다 (빈 branch-note 스캐폴드 생성)
/branch feature-keycloak-oidc-flow

# 2) 참고할 공식 문서 / 대기업 블로그 URL 을 근거로 저장합니다
#    → Claude 에게 "이 URL 을 근거로 저장해줘" 라고 요청

# 3) branch-note 를 채웁니다 (자동 조사 + 깊이 검증까지 한 번에)
/branch-spec feature-keycloak-oidc-flow
#    → Ready 가 나오면 코딩 시작. Not ready 면 알려주는 부분을 채우고 다시 실행

# 4) 구현이 끝나면 검증된 결과를 wiki 로 올립니다
/ingest raw/branch-notes/feature-keycloak-oidc-flow.md

# 5) 품질을 점검합니다
/lint                # 보고만
/lint --fix-plan     # 수정 계획 + 승인 후 적용

# 6) 외부 산출물을 만듭니다 (canonical 이 reviewed 이상일 때)
/interviewize wiki/projects/...
/blogify wiki/concepts/...
```

---

## 작업 흐름 5단계

```
① 캡처        /daily · /branch          → raw/ 에 빈 노트
② 근거 조사    URL → 근거 자료 저장        → raw/official-docs · company-tech-blogs
③ 노트 채움    /branch-spec → 자동 /depth → 되묻지 않을 수준의 branch-note
④ wiki 승급    /ingest                   → wiki/concepts · projects (canonical)
⑤ 외부 산출물  /interviewize · /blogify   → wiki/interview · blog · portfolio
```

1. **캡처** — 하루는 `/daily` 로, 새 작업은 `/branch <slug>` 로 시작합니다. 슬러그는 *무엇을 구현하는지* 를 영문 kebab-case 4~8단어로 적습니다(`feature-`, `fix-`, `chore-`, `experiment-` 중 하나로 시작). 번호 계층(`-1`, `-2`)은 쓰지 않습니다.
2. **근거 조사** — 공식 문서·대기업 블로그 URL 을 저장하면 원문에서 핵심 인용을 그대로(verbatim) 발췌합니다. 실제 존재하는지 `grep` 으로 검증한 뒤 `raw/` 에 보관합니다. 각 자료에는 `Claims Extracted` 표(Claim ID 가 붙은 사실 목록)가 있습니다.
3. **노트 채움** — `/branch-spec` 이 source 의 Claim 에서 결정과 대안을 채우고 근거가 없으면 먼저 자동으로 공식 문서·대기업 블로그를 조사합니다. 그래도 없으면 추측 대신 `UNSUPPORTED_DECISION` 으로 표시합니다. 마지막에 `/depth` 가 자동으로 돌아 **Ready / Not ready** 를 판정합니다. Ready 일 때 코딩을 시작하면 구현 중 되묻을 일이 없습니다.
4. **wiki 승급** — 구현이 끝나면 `status_label` 을 `review` 나 `merged` 로 올립니다. 그 뒤 `/ingest` 를 실행하면 검증된(`actually-implemented` 이상) 결과만 `wiki/projects/` 로 추출됩니다.
5. **외부 산출물** — canonical 문서가 `reviewed` 이상이면 `/interviewize`·`/blogify` 로 면접 답변·블로그 초안을 만듭니다. 본문 문체는 [rules/prose-style.md](rules/prose-style.md) 를 따릅니다(존댓말, 적당히 긴 길이, 개발 용어만 영어).

---

## 디렉토리 구조

| 위치 | 역할 |
|---|---|
| `CLAUDE.md` | 운영 규칙 SSOT (전체 정의) |
| `raw/` | 가공 전 원본 자료. 출처 보존. 영구 보관 |
| `wiki/` | 정리된 재사용 가능 지식 (canonical + derived) |
| `rules/` | 방법론 규칙 (linking, naming, tag, depth, prose-style 등) |
| `templates/` | 문서 카테고리별 출력 형식 |
| `docs/` | 설계 기록 등 메타 문서 |

`raw/` 하위: `branch-notes` · `daily-notes` · `official-docs` · `company-tech-blogs` · `project-notes` · `errors` · `interviews` · `job-postings` · `blog-topics` · `lectures` · `daily-tasks` · `diagrams`

`wiki/` 하위: `concepts` · `projects` (canonical) / `interview` · `blog` · `portfolio` (derived) / `llm-wiki.md`(vault MOC) · `log.md`

---

## 명령어 한눈에

| 그룹 | 명령 | 용도 |
|---|---|---|
| **캡처** | `/daily` | 오늘 일일 노트 생성 |
| | `/branch <slug>` | 빈 branch-note 스캐폴드 |
| | `/branch-spec <slug>` | branch-note 채움 + 자동 조사 + 자동 `/depth` |
| **변환·품질** | `/ingest <raw 경로>` | raw → `wiki/concepts`·`wiki/projects` |
| | `/depth <slug>` | branch-note 가 코딩 착수해도 될 만큼 깊은지 판정 |
| | `/tag` | wiki 문서 태그 보정 |
| | `/lint [--fix-plan]` | 품질 검사 (과장·출처·stale). `--fix-plan` 은 수정 계획 |
| | `/query` | wiki 기반 질의응답 |
| **출력** | `/projectize` | 개념 → 내 프로젝트 적용 문서 |
| | `/interviewize` | canonical → 면접 답변 |
| | `/blogify` | canonical → 블로그 초안 |

---

## 자동 안전장치 (저장할 때마다 자동 실행)

직접 신경 쓰지 않아도 다음이 자동으로 동작합니다.

- **저장 전 차단** — 근거 구조(Claims Extracted, Decision Evidence Map)를 우회하는 저장을 막습니다.
- **저장 후 검사** — 깨진 link 는 항상 경고합니다. 섹션 누락·빈 선택조건 같은 *완성도* 검사는 문서를 `review`·`merged` 로 완성 선언했을 때만 하므로 작성 중에는 방해하지 않습니다.

전체 검사는 언제든 직접 돌릴 수 있습니다.

```bash
python3 .claude/hooks/wiki_structure_lint.py --all     # 전체 구조·링크 검사
python3 .claude/hooks/wiki_structure_lint.py --file <경로>
```

---

## 꼭 지켜야 하는 규칙 (요약)

- 출처 없는 단정 금지. 결정은 Claim ID 로 뒷받침하거나 `UNSUPPORTED_DECISION` 으로 표시합니다.
- 공식 문서와 기술 블로그를 혼동하지 않습니다(블로그는 사례이지 공식 best practice 가 아닙니다).
- `documented-only`·`planned`·`needs-confirmation` 은 외부 산출물에 절대 쓰지 않습니다.
- 외부 산출물은 canonical 을 거쳐서만 만듭니다.
- 외부 URL 은 링크만 두지 말고 핵심 인용 3~5문장을 `raw/` 본문에 발췌 보존합니다.

전체 규칙과 그 이유는 [CLAUDE.md](CLAUDE.md) 와 `rules/` 폴더를 보시면 됩니다. 자동화 설계 배경은 `docs/superpowers/specs/` 에 기록되어 있습니다.
</content>