LLM Wiki — 작업 가이드

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

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

---

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

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

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

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

---

빠른 시작

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

# 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 를 따릅니다(존댓말, 적당히 긴 길이, 개발 용어만 영어).

---

디렉토리 구조

위치	역할
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 로 완성 선언했을 때만 합니다(작성 중에는 방해하지 않습니다).

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

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 와 rules/ 폴더를 보시면 됩니다. 자동화 설계 배경은 docs/superpowers/specs/ 에 기록되어 있습니다.