LLM이 스스로 유지보수하는 지식 저장소 — Claude Code로 LLM Wiki 만들기

문서는 Notion에, 메모는 여기저기, 코드 지식은 머릿속에 흩어져 있다. 그리고 LLM에게 뭔가 물어볼 때마다 관련 맥락을 매번 다시 설명한다. 이 반복이 아까워서, Andrej Karpathy가 제안한 LLM Wiki 패턴을 Claude Code 위에서 실제로 구축해봤다. 이 글은 그 과정과 운영하며 배운 것을 짧게 정리한 기록이다.

왜 LLM Wiki인가

우리가 LLM으로 문서를 다루는 방식은 대부분 RAG다. 질문할 때마다 원본에서 관련 조각을 검색해 답을 조합한다. 잘 동작하지만 아무것도 축적되지 않는다. 다섯 개 문서를 종합해야 하는 질문이면, 매번 그 조각들을 처음부터 다시 찾아 짜맞춘다.

LLM Wiki는 이걸 뒤집는다. 소스가 들어오면 LLM이 한 번 위키로 컴파일(요약·교차참조·모순 표시)해두고, 이후에는 그 위키를 최신 상태로 유지한다. 위키는 시간이 지날수록 똑똑해지는 영구 자산(compounding artifact) 이 된다.

LLM Wiki 패턴

핵심은 3계층과 3연산이다.

사람은 소싱과 질문에, LLM은 요약·교차참조·정리 같은 유지보수 노동에 집중한다. 사람이 위키를 방치하는 이유는 읽기가 아니라 bookkeeping의 부담인데, LLM은 지치지 않는다.

Claude Code로 구축하기

Obsidian 없이 Claude Code에서 바로 운영하기로 했다. llm-wiki 플러그인을 쓰면 /wiki:* 명령으로 수집·질의·점검이 된다.

/plugin marketplace add praneybehl/llm-wiki-plugin
/plugin install llm-wiki@llm-wiki
/wiki:init

/wiki:init이 만드는 구조는 이렇다.

my-brain/
├── wiki/
│   ├── SCHEMA.md      # 규칙(헌법) — 가장 먼저 읽힘
│   ├── index.md       # 페이지 카탈로그(한 줄 요약)
│   ├── log.md         # 수집/질의/점검 이력
│   ├── sources/ entities/ concepts/ synthesis/
└── raw/               # 사람이 넣는 불변 원본

첫 세팅에서 가장 중요한 건 SCHEMA.md다. “모든 페이지는 한국어로”, “모든 주장은 출처를 남긴다” 같은 규칙을 여기 적어두면 이후 모든 수집·질의가 그 규칙을 따른다. 위키는 결국 마크다운 git 저장소이므로 버전 이력·협업은 공짜로 따라온다.

어떻게 쓰나

① 문서 지식 — 넣으면 정리되고, 물으면 축적된다

수집(ingest)은 단순한 파일 업로드가 아니다. 문서를 raw/에 넣고 /wiki:ingest 하면 LLM이 다음을 한 번에 처리한다.

1. 원본을 읽고 핵심을 요약해 sources/에 요약 페이지를 만든다.
2. 그 소스가 언급하는 인물·제품·개념을 찾아, 이미 있는 페이지는 관련 부분만 수정하고 없으면 새로 만든다. 한 소스가 여러 페이지를 동시에 건드린다.
3. 새 데이터가 기존 주장과 충돌하면 조용히 덮어쓰지 않고 모순으로 표시한다.
4. 인덱스와 로그를 갱신한다.

모든 페이지의 주장에는 출처가 붙어, 나중에 “이건 어디서 나온 얘기지?”를 역추적할 수 있다.

질의(query)는 더 흥미롭다. 질문하면 LLM이 인덱스에서 후보 페이지를 골라 읽고 인용과 함께 답한다. 그리고 가치 있는 답변은 다시 새 페이지로 위키에 저장한다. 비교표 하나, 분석 하나가 채팅 기록에 묻히지 않고 위키에 남아 다음 탐색이 그 위에 쌓인다. 소스를 넣을수록, 질문을 던질수록 위키가 풍부해지는 구조다.

② 코드 지식 — 2계층 모델

프로젝트 코드를 지식으로 활용하려니 문서와 다른 문제가 있었다. 코드는 계속 바뀐다. 통째로 위키에 복사하면 방대하고 금방 낡는다. 그래서 두 계층으로 나눴다.

Tier 1 — 상시 축적(개요·구조). 서비스 하나당 세 가지를 위키에 상주시킨다.

• 레포 경로 + 커밋 SHA를 담은 불변 포인터 (코드 자체는 복사하지 않는다)
• 모듈 구조·바운디드 컨텍스트·주요 API·이벤트·외부 연동·데이터 저장소·장애 대응을 정리한 구조 분석 스냅샷
• 책임·의존 관계·기술 스택을 요약한 서비스 카탈로그

이건 “어디를 보면 되는지”를 알려주는 지도다. 언제든 읽을 수 있고, 릴리즈나 큰 변경 때 커밋을 갱신하며 재수집한다.

Tier 2 — 온디맨드 정밀 분석. 특정 기능이나 장애에 대한 질문이 오면, 그때 로컬 클론에서 코드를 직접 추적한다. 예를 들어 어떤 API의 처리 흐름을 물으면 이렇게 흘러간다.

질문: "이 기능의 처리 흐름을 알려줘"
   │
   ▼
Tier 1 위키에서 "어느 모듈·컨트롤러인지" 후보 파악
   │
   ▼
로컬 클론에서 코드 정밀 추적
  (컨트롤러 → 유즈케이스 → 저장소 → 실제 쿼리/캐시, 파일 단위 근거)
   │
   ▼
결과를 synthesis 페이지로 저장  → 다음 질문부터 위키가 바로 답

위키(Tier 1)가 “어디를 보면 되는지”를 알려주고, 정밀한 흐름은 코드가 확정한다. 핵심은 두 가지다. 첫째, 한 번 추적한 흐름은 지식으로 남아 매번 코드를 처음부터 뒤지지 않는다. 둘째, 분석은 항상 특정 커밋 기준으로 못 박혀 “언제 기준의 흐름인가”가 분명하다. 장애가 났을 때 “이 기능이 어떤 순서로, 어떤 데이터를 건드리는가”를 이 방식으로 빠르게 재구성할 수 있다.

③ 리서치 지식 — 질문하면 찾아와서 저장한다

앞의 둘은 소스를 사람이 정한다. 문서는 내가 넣고, 코드는 내가 레포를 지정한다. 세 번째는 다르다. “Kafka의 exactly-once는 어떻게 동작하나” 같은 순수한 기술 질문을 던지면, 에이전트가 리서치해서 소스까지 찾아와 저장한다. 소싱의 주체가 사람에서 에이전트로 넘어가는 것이다.

추출은 세 갈래를 조합한다. LLM 내장 지식으로 개괄을 잡고, 웹 리서치로 공식 문서 같은 1차 출처를 확보해 검증하고, 이미 위키에 있는 개념이면 갈아엎지 않고 연결한다. 여러 소스를 병렬로 모아 주장을 교차검증하는 리서치 도구를 쓰면 신뢰도가 올라간다.

한 번의 리서치는 위키에 여러 페이지를 남긴다.

개념은 개념대로, 비교/결정은 종합대로, 근거 문서는 출처대로 나눠 저장하고 서로 연결한다. 규칙은 앞과 같다 — 사실 주장엔 출처(URL)를 달고, 검증 안 된 건 단정하지 않으며, 기술은 버전에 따라 바뀌니 언제 기준인지를 남긴다. 이렇게 하면 한 번 리서치한 주제는 다시 검색하지 않아도 되고, 위키의 빈 곳이 질문을 던질 때마다 채워진다.

운영하며 배운 것

• AI가 만든 소스는 헤지(hedge)한다. LLM 분석이나 코드 요약은 1차 출처가 아니다. 환각이 섞이면 그럴듯한 위키 페이지가 되어 이후 해석을 오염시킨다. 그래서 검증 안 된 주장은 단정하지 않고 “이 소스가 주장하기를 …(미검증)”로 적고, 코드 분석은 파일 경로를 근거로 인용한다.
• 코드 스냅샷은 커밋에 고정한다. 분석은 특정 SHA 기준으로 못 박고, 릴리즈나 큰 변경 때 재수집한다. “언제 기준의 지식인가”가 항상 명확해진다.
• 무거운 인덱스는 게을리(lazy) 만든다. 관계 그래프 같은 파생 인덱스는 매번 갱신하지 않고, 실제로 관계 질의를 할 때만 다시 만든다.
• 위키가 자기 추정을 스스로 교정했다. Tier 1 구조 분석에서 “아마 이 데이터를 읽을 것”이라고 추정했던 부분이 있었는데, Tier 2에서 실제 코드를 추적해보니 경로가 달랐다. 그 추정을 코드 근거로 정정하고 위키를 갱신했다. 헤지해둔 덕분에 틀린 추정이 사실로 굳지 않았다.

마무리

시작은 세 줄이면 된다. 플러그인을 깔고, /wiki:init으로 뼈대를 만들고, 첫 소스를 /wiki:ingest 한다. 나머지는 쓸수록 쌓인다.

이렇게 만든 지식 저장소는 단순한 메모 앱이 아니다. 문서와 코드 지식이 한곳에 축적되면, AI 에이전트가 그 지식을 근거로 장애를 분석하고 설계를 함께 논의하는 협업 파트너가 된다. 사람은 무엇을 넣고 무엇을 물을지 고민하고, 나머지 정리는 기계가 맡는다.