LLM 위키: 만드는 법과 정확하게 유지하는 법

LLM 위키(LLM wiki)는 AI 에이전트가 대신 써 주는 개인 지식 베이스예요. 원자료(글, 논문, 녹취록, 노트)를 폴더에 모아 두면, 에이전트가 그걸 읽고 그 위에 서로 링크된 마크다운 페이지들을 관리해요. 개념, 사람, 자료마다 페이지 하나씩, 그리고 인덱스가 있어요. 자료를 추가하면 에이전트가 영향을 받는 페이지를 모두 고쳐요. 질문을 하면 위키를 바탕으로 답하고, 그 답을 새 페이지로 남겨 둘 수도 있어요.

이 아이디어는 Andrej Karpathy에게서 나왔어요. 그는 2026년 4월 2일에 X에 “LLM Knowledge Bases”에 관한 글을 올렸고, 이틀 뒤에는 더 긴 버전을 GitHub에 “아이디어 파일”로 공개했어요. Claude Code나 Codex 같은 에이전트에 그대로 붙여 넣도록 쓴 글이에요. 그가 대비하는 건 RAG예요. RAG에서는 모델이 질문할 때마다 파일 조각을 찾아오고, 쌓이는 건 아무것도 없어요. LLM 위키에서는 지식이 “한 번 컴파일된 뒤 계속 최신으로 유지”되기 때문에, 상호 참조와 모순은 질문하기 전에 이미 정리되어 있어요.

Obsidian은 IDE, LLM은 프로그래머, 위키는 코드베이스예요.

gist에 나오는 이 한 줄이 대부분의 사람이 따라 하는 구성을 요약해요. 한쪽에는 터미널에서 돌아가는 에이전트, 다른 쪽에는 마크다운 편집기, 그 사이에는 파일 폴더가 있어요. 그래도 이 패턴에 특정 편집기가 필요한 건 아니에요. 파일을 읽고 쓸 수 있는 폴더와 에이전트라면 무엇이든 괜찮아요.

편집기가 알려 주지 않는 건, 에이전트가 어떤 페이지를 바꿨고 누가 그걸 확인했는지예요. Knowtarium은 바로 이런 구성을 위해 만든 종단간 암호화 지식 베이스예요. 위키는 워크스페이스 안에 일반 마크다운 페이지로 있고, 에이전트는 MCP로 읽고 쓰며, 에이전트가 바꾸는 모든 페이지에는 서명이 남고, 누가 바꿨는지 보이고, 되돌릴 수 있어요. 무료로 시작할 수 있어요. 이 가이드의 나머지는 일반 파일로 구성하는 방법을 다루고, 중간중간 Knowtarium에서는 어떻게 하는지 적어 두었어요.

Karpathy는 LLM 위키 패턴을 세 개의 층으로 설명해요.

• 원자료. 내가 골라 모은 문서예요. 바뀌지 않아요. 에이전트는 읽기만 하고 절대 고치지 않아요. 이게 정답의 출처예요.
• 위키. 에이전트가 쓰는 마크다운 페이지 디렉터리예요. 요약, 엔티티 페이지, 개념 페이지, 비교, 개요가 들어가요. “읽는 건 나, 쓰는 건 LLM.”
• 스키마. Claude Code라면 CLAUDE.md, Codex라면 AGENTS.md 같은 파일로, 위키가 어떻게 짜여 있고 어떤 작업 흐름을 따를지 에이전트에게 알려 줘요. 나와 에이전트가 시간을 두고 다듬어요.

그리고 에이전트에게 시키는 일 세 가지가 있어요.

파일 두 개가 위키를 길 잃지 않게 해 줘요. index.md는 모든 페이지를 링크와 한 줄 요약으로 나열하고, 에이전트는 질문할 때마다 이걸 먼저 읽어요. Karpathy는 이 방식이 적당한 규모(자료 100개 정도, 페이지 수백 개)에서는 임베딩 검색 없이도 “놀랄 만큼 잘” 된다고 해요. 그보다 커지면 마크다운 파일을 대상으로 하는 로컬 검색 도구를 에이전트에게 주라고 gist는 제안해요. log.md는 ingest, query, lint의 기록을 시간순으로 남겨요.

gist는 일부러 추상적으로 쓰여 있고, 세부 사항은 나와 에이전트에게 맡겨요. 여기서는 Claude Code, Codex, Cursor에서 돌아가는 구체적인 버전을 소개해요. 30분쯤 걸리고, 대부분은 스키마를 쓰는 데 들어요.

1. 폴더 만들기

자료와 위키를 따로 두세요. 그래야 어떤 글이 바깥에서 왔고 어떤 글을 에이전트가 썼는지 늘 분명해요.

customer-wiki/
  CLAUDE.md            # 스키마 (Codex라면 AGENTS.md)
  raw/                 # 내 자료: 에이전트는 읽기만 하고 고치지 않아요
    2026-09-12-interview-northwind.md
    2026-09-14-support-tickets.md
    assets/            # 클리핑한 글 옆에 내려받은 이미지
  wiki/                # 에이전트가 쓰는 페이지
    index.md           # 페이지마다 한 줄, 질문할 때마다 먼저 읽어요
    log.md             # 언제 무슨 일이 있었는지
    overview.md
    concepts/
    entities/
    sources/           # 원자료마다 요약 페이지 하나
    answers/           # 좋은 답변을 다시 정리해 둔 곳

Knowtarium에서는

customer-wiki/를 Knowtarium 워크스페이스로 가져오면 폴더 구조가 따라와요. 그래프는 무엇이 낡았는지 보여 주고(검토를 켜면 페이지를 신뢰 등급별로 색칠할 수 있어요), 에이전트가 아직 쓰지 않은 페이지로 가는 링크는 유령 노드로 나타나요. 다음 ingest 때 할 일 목록인 셈이에요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

2. git으로 관리하기

첫 ingest 전에 git init을 실행하세요. Karpathy가 짚듯이 위키는 “그저 마크다운 파일로 된 git 저장소”이고, git은 에이전트가 무엇을 바꿨는지 보는 가장 싼 방법이기도 해요. 자세한 건 아래에서 다뤄요.

3. 스키마 파일 쓰기

이 구성에서 가장 중요한 파일이에요. 짧게 시작하고, 에이전트가 원하지 않는 일을 할 때마다 규칙을 하나씩 더하세요. Anthropic의 CLAUDE.md 가이드가 여기에도 들어맞아요. 200줄 안쪽으로 유지하고, 지시마다 지켰는지 확인할 수 있을 만큼 구체적으로 쓰라는 거예요. 에이전트를 여러 개 쓴다면 AGENTS.md로 한 번만 쓰고, @AGENTS.md가 들어 있는 CLAUDE.md를 추가해서 Claude Code도 같은 규칙을 불러오게 하세요.

# 위키 스키마
 
위키는 wiki/ 안에서 관리해요. raw/ 안의 자료는 읽기 전용이에요.
 
## 페이지
- 파일 하나에 개념, 엔티티, 자료 중 하나만. 파일 이름은 kebab-case로 써요.
- 모든 페이지는 frontmatter로 시작해요: type, title, description, sources.
- 관련 페이지는 표준 마크다운 링크로 이어요.
- 모든 주장에는 자료 id를 키로 한 각주로 출처를 달아요.
- 출처를 댈 수 없으면 쓰지 않아요. 열린 질문은 열린 질문이라고 표시해요.
 
## Ingest (내가 raw/에 파일을 추가하면)
1. 자료를 읽어요. 쓰기 전에 핵심 내용 3~5가지를 먼저 알려 주세요.
2. 요약과 자료 id를 담아 wiki/sources/<name>.md를 써요.
3. 그 자료가 닿는 개념, 엔티티 페이지를 고쳐요. 기존 페이지와 모순되면
   몰래 덮어쓰지 말고 표시해요.
4. wiki/index.md를 고치고 wiki/log.md에 항목을 추가해요.
5. 바꾼 파일을 모두 나열해요.
 
## Query
- wiki/index.md를 먼저 읽고, 필요한 페이지만 열어요.
- 인용과 함께 답해요. 좋은 답은 wiki/answers/에 정리해 둘지 물어봐요.
 
## Lint (내가 요청하면)
- 모순, 낡은 주장, 고아 페이지, 빠진 페이지, 출처 없는 주장을
  보고해요. 고칠 방법을 제안하되, 아직 적용하지는 않아요.

여기 있는 규칙 중 두 가지는 보기보다 중요해요. “모든 주장에는 출처를 달아요”와 “바꾼 파일을 모두 나열해요”예요. 지금은 드는 비용이 없고, 나중에 검토 단계를 가능하게 해 줘요.

4. 자료 하나를 넣고 ingest하기

글 하나를 마크다운으로 raw/에 저장하고 에이전트에게 ingest하라고 하세요. Karpathy는 자료를 한 번에 하나씩 ingest하면서 계속 관여하는 쪽을 좋아해요. 요약을 읽고, 업데이트를 확인하고, 무엇을 강조할지 에이전트에게 알려 주는 거예요. 적어도 처음 자료 열 개까지는 그렇게 하세요. 그래야 스키마에 무엇이 빠졌는지 알 수 있어요.

Knowtarium에서는

ingest가 쓰거나 바꾼 페이지는 열어 볼 때까지 사이드바에 표시돼요. 제목 아래에는 어느 에이전트가 언제 고쳤는지 적힌 줄과 변경 내용 링크, Undo가 있어요. 거기서 요약과 업데이트를 읽고, 원하지 않는 건 되돌리세요. 먼저 승인하고 싶다면 wiki/ 폴더에 검토(“Ask me first”)를 켜세요. 그러면 변경마다 diff로 나를 기다려요.

(새 탭에서 원래 크기로 열림) (새 탭에서 원래 크기로 열림)

5. 질문하고 좋은 답은 남겨 두기

자료 하나가 아니라 여러 자료를 가로질러 물어보세요. 남겨 둘 만한 답이 나오면 에이전트에게 wiki/answers/에 정리하고, 그 답이 기댄 페이지에서 링크하게 하세요.

# 자료 하나 ingest하기
> raw/2026-09-14-support-tickets.md를 ingest해 주세요. 핵심 내용부터 보여 주세요.
 
# 묻고, 답을 남겨 두기
> 위키만 보고 답해 주세요. 신규 고객은 어디서 막히나요? 페이지를 인용해 주세요.
> 그 답을 wiki/answers/onboarding-blockers.md로 정리하고 링크해 주세요.
 
# 상태 점검
> 위키를 lint해 주세요. 아직 아무것도 바꾸지 말고 목록만 주세요.

6. 정해 둔 주기로 lint하기

일주일에 한 번, 아니면 ingest 열 번마다 lint를 요청하세요. 먼저 보고서를 받고 수정은 따로 승인하세요. 그래야 상태 점검이 위키 절반을 몰래 다시 쓰는 일이 없어요. 로그에 일관된 머리말을 쓰면 최근에 무슨 일이 있었는지 쉽게 볼 수 있어요.

## [2026-09-14] ingest | 고객 지원 티켓, 8월
## [2026-09-15] query | 신규 고객은 어디서 막히나?
## [2026-09-20] lint | 모순 2건, 고아 페이지 4개

$ grep "^## \[" wiki/log.md | tail -5

LLM 위키 패턴은 관리를 거의 공짜로 만들어 줘요. 그게 핵심이고, 동시에 위험이기도 해요. 에이전트는 한 번에 페이지 15개를 건드릴 수 있는데, 대부분의 구성에서는 그 15개의 변경을 아무도 읽지 않아요. Karpathy 자신은 ingest할 때 계속 관여하고, 팀 위키에 대해서는 “어쩌면 사람이 중간에서 업데이트를 검토하는” 방식을 언급해요. 대부분의 튜토리얼은 이 부분을 건너뛰어요. 건너뛰면 이런 것들이 쌓여요.

• 원자료에서 멀어지기. 요약의 요약은 단서를 잃어요. “일부 벤치마크에서”가 “일관되게”가 되고, 세 페이지 뒤에는 사실이 돼요.
• 출처 없는 종합. 에이전트가 두 생각을 매끄럽게 읽히는 문장으로 잇고 아무것도 인용하지 않아요. 출처가 있는 주장과 구별할 수 없어요.
• 모순을 조용히 해결하기. 새 자료가 예전 페이지와 어긋나는데, 에이전트가 표시하지 않고 한쪽 손을 들어 줘요.
• 새것처럼 보이는 낡은 페이지. 5월에 쓴 페이지는 12월에도 똑같이 읽혀요. 확인할 때가 됐다고 알려 주는 게 없어요.
• 내 편집이 어긋나기. 한 페이지에서 숫자를 고쳐요. 같은 숫자를 되풀이하는 다른 페이지 다섯 개에는 여전히 예전 숫자가 있어요.
• 린터가 자기 숙제를 채점하기. lint는 같은 종류의 모델이 같은 페이지를 읽는 거예요. 페이지 사이의 모순은 잡지만, 모든 페이지가 똑같이 틀린 오류는 못 잡아요.

그렇다고 이 패턴이 나쁜 생각인 건 아니에요. 한 사람이 쓴 코드베이스에 필요한 것이 LLM 위키에도 필요하다는 뜻이에요. 또 한 쌍의 눈, 그리고 누가 무엇을 썼는지에 대한 기록이요.

습관 네 가지면 빈틈 대부분을 메울 수 있어요. 새 도구 없이 일반 파일만으로, 하나씩 들일 수 있어요.

1. frontmatter에 출처 기록하기

모든 페이지에는 누가, 언제, 어떤 자료로 썼는지 적혀 있어야 하고, 모든 주장은 그 자료 중 하나를 가리켜야 해요. 자료 id를 키로 한 각주([^northwind-call])는 에이전트가 목록 순서를 바꿔도 살아남아요. 번호를 매긴 각주는 그렇지 않아요. 아래는 Open Knowledge Format의 필드 이름을 쓴 페이지예요. 그래서 다른 도구도 읽을 수 있어요.

---
type: Concept
title: 가져오기 단계 이탈
description: 신규 고객이 데이터를 가져오다 멈추는 이유.
generated: { by: claude-code/2.1, at: 2026-09-20T09:12:00Z }
verified:
  - { by: human:sam, at: 2026-09-20T18:40:00Z }
stale_after: 2027-03-20T00:00:00Z
sources:
  - id: northwind-call
    resource: /raw/2026-09-12-interview-northwind.md
    title: 고객 인터뷰, Northwind Traders
---
 
Northwind는 CSV 가져오기에서 일주일을 멈춰 있었어요.[^northwind-call]

generated는 지금 글을 쓴 쪽이에요. verified는 확인한 쪽이고, human: 접두사가 사람을 나타내요. 스키마에 한 줄을 더하세요. “바꾸는 페이지마다 generated에 서명하고, verified에는 절대 자신을 추가하지 않아요.” 에이전트가 출처를 밝히게 하는 방법 가이드에서 더 자세히 다뤄요.

2. 기대기 전에 에이전트의 모든 변경 검토하기

ingest를 풀 리퀘스트처럼 다루세요. 시작하기 전에 커밋하고, 에이전트가 일하게 한 다음, diff를 읽고 받아들이거나 거절하세요. git은 이걸 잘해요.

$ git status --short          # 어떤 페이지가 바뀌었는지$ git diff --stat             # 얼마나 바뀌었는지$ git diff wiki/concepts/     # 실제 편집 내용 읽기$ git add -p                  # 덩어리별로 받아들이기$ git commit -m "ingest: support tickets"$ git restore wiki/entities/  # 받아들이지 않은 건 버리기

모든 페이지를 읽을 필요는 없어요. 바뀐 줄을 읽고, 새 주장마다 그 주장이 인용한 각주와 대조하세요. 페이지를 승인하면 날짜와 함께 verified에 나를 추가하세요. 전체 과정은 에이전트 편집 검토하는 방법에 있어요.

3. 내 편집을 에이전트에게 확인받기

검토는 양방향이어야 해요. 페이지를 손으로 고쳤다면, 그 페이지로 링크하거나, 같은 자료를 인용하거나, 예전 값을 되풀이하는 페이지를 모두 찾아서 고칠 방법을 제안하라고 에이전트에게 부탁하세요. 그 수정은 다른 에이전트 변경처럼 검토하면 돼요. 이렇게 해야 내 수정이 다른 다섯 페이지에도 닿아요.

4. 페이지에 만료 날짜 붙이기

절대 날짜로 stale_after를 추가하세요. 가격, 버전, 사람들의 역할은 짧게, 정의는 길게요. 그러면 lint가 짐작하지 않고 날짜가 지난 페이지를 나열할 수 있어요. 낡았는지는 판단의 문제가 아니라 날짜 비교가 돼요.

Open Knowledge Format은 에이전트가 쓰는 지식을 위해 Google Cloud가 공개한 열린 명세예요. 0.2 버전은 바로 위와 같은 경우, 즉 에이전트가 계속 쓰고 다른 에이전트가 읽는 자료를 위해 신뢰 신호를 추가했어요. OKF 번들은 LLM 위키와 모양이 같고(YAML frontmatter가 있는 마크다운 파일 폴더), 같은 파일 이름 두 개, index.md와 log.md를 예약해 둬요.

읽는 쪽은 verified에서 신뢰 등급을 끌어내요. 항목이 없으면 unverified, 에이전트나 프로세스만 있으면 machine-confirmed, 사람이 한 명이라도 있으면 human-reviewed예요. 페이지가 스스로 믿을 만하다고 선언할 수는 없어요. gist와 작은 차이가 두 가지 있어요. gist는 링크 문법을 정해 두지 않지만 OKF는 표준 마크다운 링크를 써요. 그리고 OKF의 log.md는 YYYY-MM-DD 날짜 제목 아래 최신 항목부터 나열해요. 모든 필드는 선택 사항이라서, OKF로 LLM 위키를 시작하고 신뢰 필드는 하면서 더해도 돼요.

기본은 git이에요. 세션마다 시작 전에 커밋하고 끝난 뒤 diff를 읽으면 무엇이 바뀌었는지 보여 줘요. 위키가 커지면 저희가 권하는 구성은 Knowtarium이에요. 기록, Undo, 신뢰 상태를 터미널이 아니라 페이지 바로 옆에 두니까요. 둘을 비교하면 이래요.

일주일에 자료 몇 개를 ingest하고 diff를 전부 읽는다면 git만으로도 충분할 수 있어요. Knowtarium은 웹 앱이에요. 페이지는 저희에게 닿기 전에 내 기기에서 암호화되니까 저희는 읽을 수 없고, 앱이 직접 AI를 호출하지도 않아요. 연결한 에이전트는 자기가 읽는 내용을 봐요. 위키가 이미 Obsidian 볼트에 있다면 워크스페이스로 가져오세요. 쓴 내용은 건드리지 않고 OKF로 바꿔 줘요. 옮기기 가이드에서 차근차근 설명하고, 비교 페이지에서 두 앱이 어떻게 다른지 다뤄요.