LLMWiki 완전 가이드 — Karpathy가 제안한 AI가 스스로 관리하는 지식 베이스

RAG는 매번 같은 문서를 처음부터 다시 읽습니다. 지난주에 이미 분석한 논문을 오늘 또 읽고, 내일 또 읽습니다. 아무것도 쌓이지 않습니다. Karpathy가 2026년 4월 GitHub Gist에 올린 패턴은 이걸 뒤집습니다. LLM이 문서를 읽는 게 아니라 위키를 직접 만들고 유지합니다.

[핵심 요약]
→ LLMWiki: Karpathy가 2026년 4월 GitHub Gist로 공개한 AI-native 지식 관리 패턴
→ 핵심 차이: RAG(매번 원문 재검색) → LLMWiki(한 번 컴파일 → 구조화된 위키 영구 저장)
→ 컴파일 비유: 소스코드(원문) → 컴파일러(LLM) → 바이너리(위키) → 실행(쿼리)
→ 핵심 3단계: Ingest(소화) → Query(질문) → Lint(위키 건강 검사)
→ Karpathy 본인 위키: 100개 아티클, 40만 단어에 도달
→ 스택: Obsidian(뷰어) + Claude Code(에이전트) + 마크다운(저장소)
→ RAG와의 결정적 차이: 지식이 쌓임 — 매 쿼리마다 새로 발견하지 않음
→ 팀/프로젝트 단위로도 적용 가능 — 코드베이스 위키, 의사결정 위키

---

RAG의 침묵하는 결함

[전통 RAG의 문제]

매번 반복하는 것들:
→ 같은 PDF 청킹
→ 같은 벡터 생성
→ 같은 상위 K개 청크 검색
→ 같은 답변 합성

문제:
→ 3개월 전 질문한 것과 오늘 질문한 것 — 시스템 입장에서 동일
→ 5개 문서를 종합해야 하는 질문 → 매번 5개 문서 다시 읽기
→ 3월 논문과 10월 논문 사이 연결 — 사람이 수동으로 찾아야
→ 지식이 누적되지 않음 — 영원히 제자리

[LLMWiki의 해결]

소스코드 vs 컴파일된 바이너리:
→ 소스(PDF, 논문, 노트): 원본 → 매번 실행하지 않음
→ 컴파일(LLM이 위키 생성): 한 번만
→ 바이너리(위키): 영구 저장, 빠른 쿼리
→ 새 문서 추가 = 증분 컴파일

Karpathy의 표현:
"Obsidian은 IDE, LLM은 프로그래머, 위키는 코드베이스"

---

실전 1 — 디렉토리 구조와 스키마 설계

[LLMWiki 디렉토리 구조]

my-wiki/
├── SCHEMA.md          # 위키 규칙 + Claude에게 주는 지시문
├── sources/           # 원본 문서 (읽기 전용)
│   ├── papers/
│   ├── articles/
│   └── notes/
├── wiki/              # 컴파일된 위키 (LLM이 작성)
│   ├── concepts/      # 개념 페이지
│   ├── people/        # 인물 페이지
│   ├── projects/      # 프로젝트 페이지
│   └── index.md       # 위키 인덱스
└── CLAUDE.md          # Claude Code 전용 설정

SCHEMA.md — 위키의 헌법

# Wiki Schema

## 이 위키의 목적
AI 개발 지식 베이스 — LLM, 에이전트, 인프라, 개발 도구

## 페이지 타입

### Concept 페이지 (concepts/)
파일명: 소문자-하이픈.md
필수 요소:
- 첫 줄: 한 줄 정의
- ## 핵심 원리 (불릿 3~7개)
- ## 실전 적용
- ## 관련 개념 (위키링크)
- ## 출처

### Person 페이지 (people/)
파일명: 이름.md
필수 요소:
- 소속, 주요 기여
- 핵심 논문/프로젝트 링크
- 관련 개념 위키링크

## 위키링크 규칙
→ 반드시 [[개념명]] 형식 사용
→ 처음 등장하는 개념은 무조건 링크
→ 같은 페이지에서 반복 링크 금지

## 금지사항
→ 의견이나 추측 없이 사실만
→ 출처 없는 클레임 금지
→ 500단어 초과 페이지 분할

CLAUDE.md — 에이전트 전용 설정

# LLMWiki 에이전트 설정

## 역할
이 디렉토리의 LLMWiki를 구축하고 유지하는 에이전트.
SCHEMA.md 규칙을 항상 따른다.

## 명령어
/ingest [파일] → sources/에서 읽고 wiki/ 업데이트
/query [질문] → wiki/에서 답변 생성
/lint → 위키 건강 검사 실행

## ingest 규칙
1. sources/에서 문서 읽기
2. 기존 wiki/ 페이지 확인
3. 관련 개념 페이지 업데이트 또는 생성
4. 모순 발견 시 해당 페이지에 ⚠️ 플래그
5. 새 개념은 concepts/ 에 새 페이지 생성
6. index.md 업데이트

## 절대 하지 말 것
→ sources/ 파일 수정
→ SCHEMA.md 무시
→ 출처 없이 내용 추가

---

실전 2 — 3가지 핵심 명령어

Ingest — 소스 소화

[Claude Code에서 실행]

> /ingest sources/papers/attention-is-all-you-need.pdf

Claude가 하는 것:
1. PDF 전체 읽기
2. 기존 wiki/concepts/ 스캔
3. 관련 페이지 업데이트:
   - transformer.md: Attention 섹션 보강
   - self-attention.md: 원본 논문 출처 추가
   - vaswani.md (인물): 논문 링크 추가
4. 없는 개념은 새 페이지 생성:
   - positional-encoding.md 신규 생성
   - multi-head-attention.md 신규 생성
5. 모순 발견 시 플래그:
   - ⚠️ "기존 transformer.md의 레이어 수 설명과 다름"
6. index.md 업데이트

실제 컴파일 결과물 예시:

<!-- wiki/concepts/kv-cache.md -->
---
title: KV Cache
created: 2026-05-19
sources: [attention-is-all-you-need, turboquant-paper, vllm-docs]
tags: [inference, memory, transformer]
---

트랜스포머 추론 시 키/값 벡터를 저장해 재계산을 방지하는 메모리 최적화 기법.

## 핵심 원리
→ 자동회귀 생성에서 이전 토큰의 K·V를 매 스텝 재계산하지 않고 캐시
→ 메모리 사용량이 시퀀스 길이와 배치 크기에 비례해 선형 증가
→ 128K 컨텍스트에서 70B 모델 단일 요청 기준 ~42GB 소모

## 실전 적용
→ [[vllm]]의 [[paged-attention]]으로 단편화 해결
→ [[turboquant]]로 4~6배 압축 (재학습 없이)
→ [[gqa]]·[[mqa]]로 헤드 수 감소

## 관련 개념
→ [[attention-mechanism]] · [[turboquant]] · [[paged-attention]]
→ [[gqa]] · [[speculative-decoding]]

## 출처
→ Vaswani et al. (2017) "Attention Is All You Need"
→ Google Research (2026) "TurboQuant"
→ vLLM 공식 문서

Query — 위키 기반 질문

[RAG vs LLMWiki 쿼리 차이]

질문: "KV 캐시 최적화 방법들을 비교해줘"

RAG 방식:
→ 임베딩 검색 → 상위 5개 청크 반환
→ 각 청크는 문맥 없는 조각
→ LLM이 그 자리에서 합성
→ 다음에 같은 질문하면 처음부터 반복

LLMWiki 방식:
→ wiki/concepts/kv-cache.md 읽기
→ 위키링크 따라 연관 페이지 읽기
   (turboquant.md, paged-attention.md, gqa.md)
→ 이미 정리된 구조 기반으로 답변
→ 새 ingest 후에는 자동으로 최신 정보 포함

Claude Code에서:
> /query KV 캐시 최적화 방법들 비교해줘

→ wiki/를 탐색해서 구조화된 비교 즉시 반환
→ 모든 정보가 이미 연결되어 있음
→ 각 방법의 장단점, 출처 함께 제공

Lint — 위키 건강 검사

> /lint

Claude가 검사하는 것:

구조적 문제:
→ 고아 페이지 (아무도 링크 안 함): 3개 발견
→ 깨진 위키링크: 2개 발견
→ 출처 없는 클레임: 7개 발견
→ 500단어 초과 페이지: 1개 → 분할 권장

내용 문제:
→ 모순 발견: "transformer.md vs bert.md 인코더 레이어 수 불일치"
→ 오래된 정보: "gpt-4.md — 최신 모델 정보 갱신 필요"
→ 개념 중복: "attention.md vs self-attention.md 내용 80% 중복"

제안:
→ 고아 페이지 index.md에 추가
→ bert.md 확인 후 모순 해결
→ attention.md와 self-attention.md 병합 여부 결정

---

실전 3 — Claude Code로 30분 안에 세팅

# 1. 디렉토리 세팅
mkdir my-llmwiki && cd my-llmwiki
mkdir -p sources wiki/concepts wiki/people wiki/projects

# 2. Claude Code 실행
claude  # 또는 claude --model claude-sonnet-4-6

# 3. 초기 설정 요청
> Karpathy의 LLM Wiki 패턴으로 이 디렉토리를 세팅해줘.
  이 위키의 주제는 AI 개발 도구와 LLM 인프라야.
  SCHEMA.md랑 CLAUDE.md 먼저 작성해줘.

# Claude가 SCHEMA.md, CLAUDE.md 생성

# 4. 첫 번째 소스 ingest
cp ~/papers/turboquant.pdf sources/papers/
> /ingest sources/papers/turboquant.pdf

# 5. 쿼리 테스트
> /query KV 캐시 압축이 왜 필요해?

# 6. 추가 소스 계속 ingest
> /ingest sources/articles/attention-is-all-you-need.pdf
> /ingest sources/notes/my-reading-notes.md

---

실전 4 — 팀/프로젝트 단위 적용

개인 위키를 넘어 팀 전체에 적용하는 패턴입니다.

# 팀 의사결정 위키 예시

wiki/
├── decisions/          # ADR (Architecture Decision Records) 컴파일
│   ├── auth-system.md  # JWT 선택 이유, 배경, 트레이드오프
│   └── db-choice.md    # PostgreSQL 선택 근거
├── postmortems/        # 인시던트 레슨런드 누적
│   ├── 2026-03-outage.md
│   └── patterns.md     # 반복 패턴 자동 추출
├── codebase/           # 코드베이스 설명 위키
│   ├── auth-module.md  # 코드 읽고 자동 생성
│   └── payment-flow.md
└── onboarding/         # 신규 입사자용 자동 생성
    └── quick-start.md

[팀 위키 ingest 파이프라인]

자동화 예시 (GitHub Actions):
→ PR 병합 시 코드베이스 변경 → /ingest 자동 실행
→ 인시던트 해결 후 postmortem.md 추가 → 위키 자동 업데이트
→ 주간 /lint 자동 실행 → Slack 리포트

결과:
→ 신규 입사자: "이 모듈 왜 이렇게 설계됐어?" → 위키에서 즉시 확인
→ 시니어: 과거 의사결정 맥락 잊어버릴 때 → /query로 즉시 복기
→ 팀 전체: 같은 실수 반복 방지 → postmortems/ 패턴 자동 축적

---

RAG vs LLMWiki — 언제 뭘 쓰나

[선택 기준]

RAG가 맞는 경우:
→ 실시간 최신 정보 필요 (뉴스, 주가, API 응답)
→ 문서가 자주 바뀌어서 컴파일 비용이 비쌈
→ 원문 정확한 인용이 필요한 법률, 컴플라이언스
→ 수백만 페이지 규모 (컴파일 불가능)

LLMWiki가 맞는 경우:
→ 연구 노트, 기술 문서, 의사결정 기록 — 쌓이는 지식
→ 같은 질문을 반복적으로 하는 경우
→ 여러 문서 간 연결이 중요한 경우
→ 팀 온보딩, 코드베이스 이해
→ 개인 두 번째 뇌 (Second Brain)

같이 쓰는 경우:
→ 위키 = 컴파일된 기반 지식
→ RAG = 최신 정보 보완
→ 질문 시 위키 먼저 검색 → 없으면 원문 RAG로 폴백

---

마무리

✅ LLMWiki 시작해야 하는 경우
→ 같은 문서를 반복해서 AI에게 설명하고 있을 때
→ 팀 지식이 개인 노트에 흩어져 있을 때
→ 프로젝트 의사결정 맥락을 자꾸 잊어버릴 때
→ 신규 입사자 온보딩에 시간이 너무 많이 걸릴 때
→ RAG 파이프라인이 매번 같은 답을 반복할 때

❌ 아직 LLMWiki가 안 맞는 경우
→ 실시간 최신 정보가 핵심인 서비스
→ 문서가 매일 대량으로 바뀌는 환경
→ 원문 그대로 인용이 법적으로 필요한 경우
→ 아직 정리할 문서 자체가 없는 초기 단계

---

관련 글

• RAG 청킹 전략 완전 정리
• CLAUDE.md 잘 쓰는 법 — 세션마다 시니어 개발자를 고용하는 효과
• Harness Engineering 완전 가이드

---