7.1 KiB
LLM Wiki — 작업 가이드
원본 자료(raw/)를 검증된 실무 기술 문서로 바꾸는 문서 파이프라인입니다. 거기서 면접·블로그·포트폴리오 같은 외부 산출물을 만들어 냅니다. Obsidian vault 이자 Claude Code 자동화 저장소입니다.
처음 오셨다면 이 README만 읽으면 작업을 시작할 수 있습니다. 운영 규칙의 전체 정의(SSOT)는 CLAUDE.md 에 있습니다.
핵심 원칙 (이것만 기억하면 됩니다)
raw 자료 = 증거 (출처 보존)
wiki/concepts = 검증된 일반 개념
wiki/projects = 내 프로젝트에 적용된 검증 사실
wiki/interview·blog·portfolio = 위 canonical 에서 파생된 외부 산출물
이 순서는 거꾸로 갈 수 없습니다. 외부 산출물(블로그·면접 문서 등)은 raw나 메모에서 바로 만들지 않고 반드시 wiki/concepts 또는 wiki/projects 를 거쳐서 나옵니다.
또 하나의 원칙은 근거 없는 단정을 쓰지 않는다입니다. 모든 결정은 출처(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
- 캡처 — 하루는
/daily로, 새 작업은/branch <slug>로 시작합니다. 슬러그는 무엇을 구현하는지 를 영문 kebab-case 4~8단어로 적습니다(feature-,fix-,chore-,experiment-중 하나로 시작). 번호 계층(-1,-2)은 쓰지 않습니다. - 근거 조사 — 공식 문서·대기업 블로그 URL 을 저장하면 원문에서 핵심 인용을 그대로(verbatim) 발췌합니다. 실제 존재하는지
grep으로 검증한 뒤raw/에 보관합니다. 각 자료에는Claims Extracted표(Claim ID 가 붙은 사실 목록)가 있습니다. - 노트 채움 —
/branch-spec이 source 의 Claim 에서 결정과 대안을 채우고 근거가 없으면 먼저 자동으로 공식 문서·대기업 블로그를 조사합니다. 그래도 없으면 추측 대신UNSUPPORTED_DECISION으로 표시합니다. 마지막에/depth가 자동으로 돌아 Ready / Not ready 를 판정합니다. Ready 일 때 코딩을 시작하면 구현 중 되묻을 일이 없습니다. - wiki 승급 — 구현이 끝나면
status_label을review나merged로 올립니다. 그 뒤/ingest를 실행하면 검증된(actually-implemented이상) 결과만wiki/projects/로 추출됩니다. - 외부 산출물 — 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/ 에 기록되어 있습니다.