LLM Wiki 운영 가이드

11분 분량

LLM Wiki 운영 가이드

이 vault는 단순한 노트 모음이 아니라, LLM이 규율 있는 유지보수자로 동작하는 위키로 운영된다.
이 문서는 그 운영 계층이 (1) 무엇이고, (2) 어떤 구조로 동작하며, (3) 앞으로 어떻게 써야 하는지를 설명한다.

한 줄 요약

기존 1200여 개 노트의 frontmatter는 건드리지 않고, 유일한 신규 필수 필드 type 하나만 붙였다.
정규화·색인·검증은 전부 vault 루트의 비공개 운영 영역 _wiki/에서 일어나고, 블로그(Public/)에는 유출되지 않는다.

1. 왜 이렇게 만들었나

문제: 노트가 1000개를 넘으면 사람도 LLM도 “내가 뭘 알고 있는지”를 한눈에 못 본다. 매번 전체를 읽으면 토큰이 폭발하고, 안 읽으면 중복·모순·끊긴 링크가 쌓인다.

해법: 노트 본문은 그대로 두고, 그 위에 기계가 읽는 얇은 색인 계층을 얹는다. LLM은 매번 전체 vault가 아니라 작은 카탈로그만 읽고도 “어떤 도메인에 무엇이 있는지”를 0토큰에 가깝게 파악한다. 유지보수(끊긴 링크·고아 노트·낡은 노트 탐지)는 기계적 lint가 담당하고, 의미적 판단(모순·빈틈)은 LLM이 사용자 승인 하에 처리한다.

핵심 설계 원칙 3가지:

  • 보존 우선 — 기존 frontmatter는 한 글자도 안 바꾼다. 정규화가 필요하면 별도 카탈로그에서 한다.
  • 유출 차단 — 운영 메모(_wiki/)는 블로그 빌드가 도는 Public/ 밖(vault 루트)에 둔다.
  • 사람이 핸들을 쥔다 — 자동 수정은 명백한 것만. 나머지는 전부 제안→승인.

2. 큰 그림

flowchart TD
    subgraph Pub["Public/ (블로그로 게시됨)"]
        Notes["노트 1200여 개<br/>frontmatter + 본문<br/>유일 필수 필드: type"]
        Tools["_tools/*.py<br/>wikilib · assign_types<br/>build_catalog · lint"]
    end
    subgraph Wiki["_wiki/ (vault 루트, 게시 안 됨)"]
        Cat["catalog/{domain}.md<br/>도메인별 머신 색인 (SSOT)"]
        Log["log.md<br/>append-only 타임라인"]
        Syn["synthesis/ + MOC.md<br/>종합·환류 페이지"]
    end

    Notes -- "build_catalog.py" --> Cat
    Notes -- "lint.py (읽기 전용)" --> Report["lint 리포트<br/>drift·끊긴링크·고아·stale"]
    Cat -- "정합성 검증" --> Report
    Report -- "--log" --> Log
    Query["LLM 질문"] -- "1. 카탈로그만 읽기" --> Cat
    Cat -- "2. 후보 drill-in" --> Notes
    Notes -- "3. 종합" --> Syn
    Syn --> Log

데이터는 한 방향으로 흐른다: 노트(진실) → 카탈로그(색인) → lint(검증) → log(이력). 카탈로그는 언제든 노트로부터 재생성되는 파생물이지, 별도로 손으로 관리하는 원본이 아니다.

3. 구조 — 4개의 축

① Frontmatter와 type

  • 모든 노트의 native frontmatter(Comment, Review-Date, arXiv-ID, tags 등)는 그대로 보존된다.

  • 추가된 유일한 필수 필드는 type — 값은 paper | lecture | concept | hub | project | synthesis | moc 중 하나.

  • 정규화(어떤 필드가 “요약”이고 “날짜”인지)는 노트가 아니라 카탈로그 생성 시점에 역할 매핑으로 처리한다:

    역할paperlecturecontent/hubproject
    summaryComment(제목)description / > [!summary]Topic
    dateReview-Date—Review-DateEnd-date→Start-Date
    groupingTopic,CategorytagstagsTopic
    refarXiv-ID/DOI/URLURL——

② _wiki/ — 비공개 운영 계층 (vault 루트)

블로그로 게시되지 않는다 (Public/ 밖에 있으므로). 구성:

  • catalog/{domain}.md — 도메인별 머신 카탈로그. 노트 한 개당 한 행(type·링크·태그·날짜·요약). 단일 진실 원천(SSOT).
  • log.md — append-only 타임라인. 엔트리 형식: ## [YYYY-MM-DD] {ingest|query|lint} | {제목}.
  • synthesis/ — 여러 노트를 종합한 환류 페이지(평면 구조 + 태그). MOC.md가 그 큐레이션 허브.

③ Public/_tools/ — 도구 (git 추적, 블로그엔 미게시)

도구역할
wikilib.py공유 라이브러리: frontmatter 읽기/쓰기(따옴표·들여쓰기 보존), 노트 순회, type 추론, 역할 매핑
assign_types.py모든 노트에 type 일괄 부여 (--dry-run/--write). 다른 필드 불변
build_catalog.py노트 → 도메인별 카탈로그 생성. 사라진 도메인 파일 자동 정리
lint.pyTier1 기계적 lint. 읽기 전용(노트 수정 안 함), --log 시에만 _wiki/log.md에 append

전부 TDD로 작성됐고 테스트 20개가 통과한다 (cd Public/_tools && python3 -m pytest -q).

④ 카탈로그 = SSOT, lint = 정합성 보증

build_catalog.py로 카탈로그를 다시 만든 직후 lint.py를 돌리면 drift(미등재/유령) = 0이 보장된다. 즉 카탈로그가 현실과 어긋나면 lint가 즉시 잡아낸다.

4. 일상 사용법

🟢 세션 시작 (매번 1회, 거의 0토큰)

python3 Public/_tools/lint.py            # Tier1 상태 점검
grep "^## \[" _wiki/log.md | tail -10    # 최근 활동
ls _wiki/catalog                          # 도메인 목록

LLM에게는 “세션 시작 루틴 돌려줘”라고만 해도 CLAUDE.md 규약대로 위를 수행한다.

🔵 Ingest — 새 논문/소스 추가

새 논문은 기성 스킬에 위임한다: paper-driller(딥 분석) / paper-digest(공유용 요약) / paper-explorer(서베이 누적). 산출물이 나오면 반드시 배선(wiring):

  1. 올바른 도메인 폴더에 배치 (예: AI/Papers/<topic>/)
  2. frontmatter 정규화: type 부여 + 역할 필드 확인. 기존 필드 삭제 금지
  3. python3 Public/_tools/build_catalog.py 재실행 (카탈로그에 새 행 반영)
  4. 이 소스가 보강/반박하는 _wiki/synthesis/ 페이지 갱신
  5. 관련 노트와 양방향 cross-ref 연결
  6. _wiki/log.md에 ingest 엔트리 추가

기본은 한 번에 하나(감독형). “배치로 처리해”라고 하면 여러 편을 일괄 처리 + 배선 자동.

🟣 Query — 검색 → 종합 → 환류

  1. 질문 도메인 추정 → 해당 _wiki/catalog/{domain}.md만 읽기 (전체 vault 안 읽음 = 토큰 절약)
  2. 카탈로그 메타로 후보 추리기 → grep으로 Topic/tags/Comment 교차 확인 → 후보만 본문 drill-in
  3. 종합 시 모든 주장에 출처 링크 [[note]] (+ arXiv-ID/DOI)

환류 게이트: 2개 이상 노트를 종합했고 재사용 가치가 있으면(특히 도메인 횡단) _wiki/synthesis/에 적재한다. 단일 페이지 단순 조회는 적재하지 않는다. 적재 전 dedup 먼저(유사 페이지 있으면 신규 대신 갱신).

🟠 Lint — 유지보수

  • Tier1 (기계적, lint.py): catalog drift, 끊긴 wikilink, 고아 노트, 누락 type/date, stale 노트 탐지. 자동 수정은 카탈로그 갱신과 명백한 오타성 끊긴 링크만 허용. 그 외는 제안→승인.
  • Tier2 (의미적, 사용자 트리거): 모순 탐지, stale 검증, 빠진 개념 stub 제안, 약한 cross-ref 제안, data gap → 웹 검색 제안. 결과는 전부 제안→승인. LLM에게 “이 도메인 Tier2 lint 돌려줘”라고 요청.

5. 안전 규칙 (꼭 기억할 것)

  • frontmatter 보존: 도구는 type만 추가하고 나머지는 바이트 단위로 보존한다(따옴표·들여쓰기 포함). 기존 필드를 지우지 않는다.
  • _wiki/는 게시 금지: 운영 메모는 절대 Public/로 옮기지 않는다. git push 시 블로그 빌드가 도므로, 비공개로 둘 것은 vault 루트에 남긴다.
  • 자동 수정 경계: 위에 적힌 두 가지(카탈로그 갱신 + 명백한 오타 링크) 외의 모든 수정은 사람 승인 후에만.

6. 현재 상태 & 할 일

✅ 완료된 것

  • 도구 4종(wikilib/assign_types/build_catalog/lint) + 테스트 20개 통과
  • 전 노트에 type 부여 (frontmatter 무손상, 순수 추가)
  • 도메인 카탈로그 10개 생성, Tier1 lint 가동, drift=0 검증
  • CLAUDE.md/AGENTS.md에 운영 규약 적재

📋 남은 할 일

  • WIP 노트 정리·커밋 — 위키 작업과 별개로 미커밋 상태인 개인 편집 노트들(type는 이미 붙음). 콘텐츠와 함께 직접 커밋.
  • .DS_Store 추적 해제 — git rm --cached .DS_Store (이미 .gitignore에 있으나 과거 커밋됨).
  • push — 준비되면 git push (→ Quartz 블로그 빌드 트리거).
  • 첫 실사용 사이클 — ingest 1건 + query 1건을 돌려 _wiki/synthesis/ 첫 환류 페이지를 만들어 전체 흐름 검증.

🔧 선택적 개선 (운영하며 조정)

  • Tier1 lint 정밀도: .canvas/.base/이미지 등 비-.md 링크를 “끊긴 링크”에서 분리(현재 broken 카운트의 대부분), 고아/날짜 false positive 정제.
  • Tier2 의미적 lint를 실제로 돌려 첫 모순·stub 후보 발굴.

치트시트

# 상태 점검 (세션 시작)
python3 Public/_tools/lint.py
python3 Public/_tools/lint.py --log        # 리포트 + log.md 기록
 
# 카탈로그 재생성 (노트 추가/수정 후)
python3 Public/_tools/build_catalog.py
 
# 새 노트에 type 부여 (드라이런 먼저!)
python3 Public/_tools/assign_types.py --dry-run
python3 Public/_tools/assign_types.py --write
 
# 도구 테스트
cd Public/_tools && python3 -m pytest -q

전체 LLM 운영 규약의 정본은 CLAUDE.md의 ## LLM Wiki Operations 섹션에 있다.