들어가며
2026년 4월, Andrej Karpathy가 GitHub gist 하나를 올렸습니다. 파일 이름은 llm-wiki.md. 단 며칠 만에 별 5,000개를 받으며 화제가 된 이 글은 "LLM 시대의 위키를 어떻게 만들 것인가"라는 한 가지 질문을 던졌습니다. 그리고 48시간 뒤, Graphify라는 이름의 오픈소스 도구가 그 아이디어를 그대로 구현해서 등장했습니다.
Graphify의 헤드라인 수치는 단 하나, "세션당 토큰 71.5배 절감". Claude Code 같은 AI 코딩 어시스턴트에서 매번 수십 개의 파일을 다시 읽으며 컨텍스트를 채우는 비효율을, 한 번 만든 지식 그래프를 재활용하는 방식으로 끊어내겠다는 발상입니다.
이번 글은 다음 흐름으로 갑니다.
- Karpathy가 던진 화두 - LLM Wiki는 RAG와 무엇이 다른가
- 3계층 구조 (raw / wiki / CLAUDE.md) 의 의미
- Graphify - 아이디어의 실체화 (AST + 미디어 전사 + 의미 추출의 3-pass)
- 71.5배 절감 수치의 실제 조건과 한계
- 실전 셋업: Claude Code + Obsidian + Graphify
- 백엔드 개발자가 자기 코드베이스에 적용하는 법
- 비판적 관점과 현실적 활용 범위
관련 글로 영구 메모리 레이어 실전도 같이 읽으면 "AI가 무엇을 어떻게 기억할 것인가"의 큰 그림이 잡힙니다. 메모리가 "세션 간 사실의 보존"이라면, 위키는 "문서 단위의 누적 지식"입니다. 둘은 보완 관계입니다.
1. Karpathy가 던진 화두 - 왜 RAG로는 부족한가
대부분의 사람들이 LLM에 문서를 활용하는 방식은 RAG (Retrieval-Augmented Generation) 입니다. 문서 더미를 업로드하면, 질문할 때마다 임베딩 검색으로 관련 청크를 끌어와 답변을 만들어냅니다. 잘 동작합니다. 하지만 Karpathy가 지적한 결정적인 한계가 있습니다.
"RAG에서는 LLM이 매 질문마다 0부터 다시 지식을 발견한다. 누적되지 않는다."
예를 들어 "이 회사의 인증 흐름"에 대해 어제도 묻고 오늘도 묻는다고 합시다. RAG는 매번 같은 청크를 다시 가져와서 같은 추론을 다시 합니다. 어제 만든 정리·요약·교차참조는 어디에도 보존되지 않습니다.
Karpathy의 비유: "Obsidian은 IDE, LLM은 프로그래머, 위키는 코드베이스"
이 한 줄이 LLM Wiki 패턴의 정수입니다. 코드를 한 번 짜면 다음에 그 함수를 호출하기만 하면 됩니다. 위키를 한 번 정리해두면 다음 질문에 그 페이지를 참조만 하면 됩니다. 매번 처음부터 추론할 필요가 없죠.
RAG와의 차이를 표로 정리하면 이렇습니다.
| 관점 | RAG | LLM Wiki |
|---|---|---|
| 저장 단위 | 원본 청크 (passive) | 요약·정리된 페이지 (active) |
| 지식 누적 | 없음 (매번 재추론) | 있음 (페이지가 산출물로 남음) |
| 업데이트 | 인덱스 재생성 | 해당 페이지만 재작성·교차참조 갱신 |
| 비용 구조 | 매 질문마다 청크 재로드 | 최초 정리 시 비용 큼, 이후 재사용 저렴 |
| 적합한 대상 | 수시 변하는 대규모 문서 | 천천히 변하는 깊은 도메인 지식 |
2. 3계층 구조 - raw / wiki / CLAUDE.md
Karpathy가 제시한 폴더 구조는 단순합니다. 하지만 단순함 자체가 핵심입니다.
my-knowledge/
├── raw/ # 원본 자료 (불변)
│ ├── papers/ # 논문 PDF
│ ├── articles/ # 블로그 글 마크다운
│ ├── transcripts/ # 영상·강의 전사본
│ └── images/ # 다이어그램, 스크린샷
├── wiki/ # LLM이 작성하는 정리된 페이지
│ ├── concepts/ # 개념 페이지 (예: "Attention.md")
│ ├── people/ # 인물 페이지
│ ├── papers/ # 논문 정리 페이지 (raw/papers의 요약)
│ └── index.md # 위키 진입점
└── CLAUDE.md # LLM 운영 규칙 (스키마)각 계층의 역할
| 계층 | 누가 쓰는가 | 특성 |
|---|---|---|
| raw/ | 사람만 (LLM은 읽기만) | 불변, 원자료 보존 |
| wiki/ | LLM이 작성·갱신 | 요약·정리·교차참조 |
| CLAUDE.md | 사람이 작성 | 구조 규칙, 명명, 워크플로 |
CLAUDE.md - 가장 과소평가된 파일
Karpathy의 핵심 통찰 중 하나는 "LLM에게 위키 관리자 직무 명세를 주어라"는 점입니다. CLAUDE.md는 일종의 운영 매뉴얼입니다. 예시:
# Wiki Operating Rules
## File naming
- 개념 페이지: PascalCase (예: ChainOfThought.md)
- 인물 페이지: FirstLast.md (예: AndrejKarpathy.md)
## Adding raw source workflow
1. raw/ 폴더에 새 파일 추가됨을 인지하면
2. 해당 자료의 요약 페이지를 wiki/papers/ 또는 wiki/articles/ 에 생성
3. 등장하는 개념·인물 각각에 대해
- 해당 페이지가 있으면 백링크 추가
- 없으면 stub 페이지 생성 + TODO 마커
4. wiki/index.md 의 "Recent Additions" 섹션 갱신
## Cross-reference rules
- 모든 위키 페이지는 [[다른 페이지]] 형식의 링크 1개 이상
- 출처 인용은 raw/ 경로로 (예: 출처: raw/papers/attention-is-all-you-need.pdf)
## Forbidden
- raw/ 내용 수정 금지
- 같은 개념의 중복 페이지 생성 금지 (먼저 grep 후 머지)
## Maintenance (주 1회)
- 고아 페이지 (백링크 0개) 식별 → 통합 또는 삭제 제안
- TODO 마커 정리이 규칙이 있으면 LLM은 매번 같은 방식으로 위키를 다듬습니다. 규칙이 없으면 매번 다른 스타일의 페이지가 쌓이고, 그게 바로 "잘 안 되는" 원인입니다.
3. Graphify - 48시간 만에 나온 실체
Karpathy의 gist는 "이런 패턴을 쓰면 좋다"는 아이디어 노트였습니다. 곧장 누군가 "/graphify install 한 번이면 끝"인 도구로 만들어 공개했습니다. 이게 safishamsi/graphify 입니다.
설치
# 권장: uv
uv tool install graphifyy && graphify install
# 또는 pipx
pipx install graphifyy && graphify install
# Claude Code 통합
graphify claude install
# Cursor / Copilot / Aider 등 다른 어시스턴트도 지원
graphify cursor install
graphify copilot install3-Pass 파이프라인
Graphify가 폴더를 그래프로 바꾸는 과정은 세 단계입니다.
| 패스 | 역할 | LLM 사용 여부 |
|---|---|---|
| 1. AST 패스 | 코드(13개 언어)에서 클래스·함수·import·호출 그래프·docstring 결정론적 추출 | X (tree-sitter) |
| 2. 미디어 전사 패스 | 비디오·오디오를 faster-whisper로 로컬 전사, 도메인 어휘 활용 | 로컬 모델 (네트워크 X) |
| 3. 의미 추출 패스 | 문서·논문·이미지·전사본에서 개념·관계·설계 의도를 Claude 서브에이전트가 병렬 추출 | O |
이 결과가 NetworkX 그래프로 합쳐지고, Leiden 커뮤니티 탐지로 클러스터링됩니다. 산출물은 graph.json 한 파일입니다. Obsidian vault 형식으로도 함께 출력되어, 사람도 그대로 열람·편집할 수 있습니다.
주요 명령어
/graphify . # 현재 디렉토리 분석
/graphify ./raw --mode deep # 깊은 추론 추출
/graphify ./raw --update # 변경된 파일만 재추출
/graphify query "인증 흐름" # 그래프 쿼리
/graphify path "Node1" "Node2" # 두 노드 간 최단 경로
graphify hook install # Git 훅 자동 동기화왜 이 구조가 효율적인가
- 코드는 LLM 없이 처리. 함수 시그니처 추출에 굳이 LLM을 쓸 필요가 없습니다. AST가 결정론적이고 무료입니다.
- 미디어는 로컬에서. faster-whisper는 네트워크 호출 없이 영상을 전사합니다. 폐쇄망 환경에도 적합.
- 의미 추출만 LLM. 가장 비용이 큰 부분만 LLM에 위임하고, 그것도 서브에이전트 병렬로 처리.
- Git 훅으로 점진 갱신. 파일이 바뀐 만큼만 그래프를 다시 그립니다. 전체 재빌드 비용 회피.
4. 71.5배 절감의 실제 조건
마케팅 카피만 보면 "무조건 71.5배 싸진다"고 들리지만, 실제 측정 조건을 살펴봐야 합니다.
측정의 베이스라인
Graphify 저장소의 worked/ 폴더에 실제 입출력이 공개되어 있습니다. 핵심 사례:
- 코퍼스: Karpathy 저장소 + 논문 PDF 5개 + 이미지 4개 = 약 52개 파일
- 측정 항목: 한 번의 질의에 들어가는 입력 토큰 수
- 결과: 평균 ~1.7k 토큰 (그래프 쿼리) vs ~123k 토큰 (모든 파일 raw 로드) → 약 71.5배 절감
이 수치가 의미하는 것과 의미하지 않는 것
| O 의미하는 것 | X 의미하지 않는 것 |
|---|---|
| 대규모 혼합 코퍼스에서 "raw 전체 로드" 대비 큰 절감 가능 | 모든 작업이 71배 빨라진다는 뜻 X |
| 코퍼스가 클수록 절감폭 커짐 (선형 이상) | 5개 파일짜리 미니 프로젝트는 절감 미미 |
| 구조화된 그래프 질의가 raw 검색보다 정확도도 보통 높음 | 순수 의미적 질문에선 RAG가 더 나을 수도 있음 |
| 매 세션마다 동일 코드베이스 재읽기 비용 회피 | 최초 그래프 빌드 비용은 별도 (LLM 호출 사용) |
실무 감각으로 환산
다른 사례에선 별도 측정에서 126개 파일 React + Supabase 프로젝트에서 쿼리당 토큰 499배 절감이 보고된 적도 있습니다. 즉 "71.5배"는 한 사례의 평균이고, 코퍼스에 따라 더 작을 수도 더 클 수도 있습니다.
합리적인 기대치는:
- 대형(파일 수백+) 코드베이스: 10~100배 (의미있게 큼)
- 중형(수십): 3~20배
- 소형(10개 미만): 차이 미미. 그래프 빌드 비용이 더 들 수도 있음
5. 실전 셋업 - Claude Code + Obsidian + Graphify
가장 자연스러운 조합은 다음 세 도구입니다.
| 도구 | 역할 |
|---|---|
| Obsidian | 위키 IDE (사람이 보고, 백링크·그래프뷰로 탐색) |
| Claude Code | 위키 작성자 (LLM = 프로그래머) |
| Graphify | 코드/문서 → 그래프 자동 생성기 |
디렉토리 셋업
$ mkdir -p ~/brain/{raw,wiki}
$ cd ~/brain
$ touch CLAUDE.md
$ pipx install graphifyy
$ graphify install
$ graphify claude install
# Obsidian Vault으로 ~/brain 폴더 등록
# (File → Open folder as vault)CLAUDE.md 최소 시작본
# Brain Wiki
## Layout
- raw/ : 원본 자료 (수정 금지, 추가만)
- wiki/ : 정리된 페이지 (LLM이 작성)
## Workflow when raw/ 에 새 파일이 추가됐을 때
1. raw/ 의 파일을 읽고 wiki/ 에 요약 페이지 생성
2. 등장 개념마다 wiki/concepts/Concept.md 생성/갱신
3. 모든 페이지에 [[다른 페이지]] 백링크 1개 이상 포함
4. wiki/index.md 의 "Latest" 섹션 갱신
## Naming
- 개념: PascalCase (KnowledgeGraph.md)
- 인물: FirstLast.md (AndrejKarpathy.md)
## Don't
- raw/ 수정 금지
- 중복 페이지 만들지 말 것 (먼저 grep)실제 사용 흐름
- raw/articles/ 에 새 글 마크다운 떨구기
- Claude Code에서 "raw/ 에 새 글 추가됨, 위키 갱신해" 한 줄
- Claude가 CLAUDE.md 규칙대로 wiki/ 에 페이지 생성/갱신
- 주기적으로
/graphify ./wiki --update실행해 그래프 동기화 - 다음 질문부터 Claude가 그래프를 먼저 쿼리해 적은 토큰으로 답변
6. 백엔드 개발자가 활용하는 법
이 패턴이 백엔드 실무에 어떻게 들어맞는지가 가장 궁금한 부분일 겁니다. 세 가지 케이스를 봅시다.
케이스 1: 모놀리식 코드베이스의 "이거 뭐 하는 코드야"
오래된 Spring 프로젝트에 새로 합류했다고 합시다. 패키지 200개, 클래스 3,000개. 모든 파일을 Claude Code에 통째로 던지면 컨텍스트가 즉시 폭발하고 비용도 끔찍합니다.
# 1. 코드베이스를 그래프로
$ cd ~/work/legacy-project
$ /graphify .
# 2. 그래프 기반 질의
$ /graphify query "OrderService 가 호출되는 모든 경로"
# → 함수 콜그래프에서 추적, raw 코드 거의 안 읽음
$ /graphify query "결제 실패 시 흐름"
# → 의미 추출된 노드(예: PaymentFailedHandler)와 연결 추적요점: 전체 코드를 매번 읽히지 않고, 그래프에서 필요한 노드 몇 개만 끌어와 답변에 사용합니다. 토큰도 적게, 정확도도 보통 더 높습니다.
케이스 2: 사내 지식 관리 - 회의록·결정 기록
스프린트 회의록, ADR(Architecture Decision Record), 장애 회고 등을 raw/ 에 마크다운으로 쌓아둡니다. CLAUDE.md에 "새 회의록이 들어오면 wiki/decisions/ 에 ADR 형식으로 정리, 관련된 시스템 페이지에 백링크" 규칙을 넣습니다.
3개월 뒤 "왜 그때 Kafka 대신 Redis Streams 썼지?" 질문에, 그래프가 ADR 페이지로 바로 안내합니다. RAG였다면 회의록 청크를 다시 검색하고 다시 추론해야 했을 일을, 정리된 페이지 한 장으로 끝냅니다.
케이스 3: 사이드 프로젝트 - 학습 노트
유튜브 강의·블로그 글을 보면서 정리하는 노트도 같은 패턴이 됩니다. raw/transcripts/ 에 영상 전사본, raw/articles/ 에 글, raw/papers/ 에 논문 PDF. wiki/concepts/ 에는 개념 페이지가 차곡차곡 쌓이고, 모든 페이지가 서로 백링크로 연결됩니다.
3개월 뒤 같은 개념을 다시 만나면 처음부터 다시 정리하지 않고 wiki/concepts/Foo.md 한 장만 다시 보면 됩니다. 그게 "AI 세컨드 브레인"이라는 표현의 실체입니다.
7. 비판적 관점 - 어디까지 믿을 것인가
도구가 신선할수록 과대 평가도 같이 옵니다. 냉정한 한계점을 정리합니다.
한계 1: 손실 압축은 손실이다
위키 페이지는 원본의 요약입니다. 원본의 미묘한 뉘앙스, 각주, 반박 등이 압축 과정에서 누락될 수 있습니다. "왜 X 대신 Y를 골랐나"의 미묘한 이유가 사라지면, 답변은 그럴듯해 보이지만 실제 결정의 근거를 놓칩니다.
대응책: 중요한 결정은 원본도 함께 인용. CLAUDE.md에 "결정 페이지는 항상 raw/ 경로 인용" 규칙을 박아둘 것.
한계 2: 빠르게 변하는 코퍼스에는 부적합
매일 100개 파일이 바뀌는 거대 모놀리스에서는 그래프 갱신 비용이 만만치 않습니다. 점진 갱신이 있더라도, 전혀 변하지 않는 분야(연구·도메인 지식)에 비해 ROI가 떨어집니다.
대응책: 천천히 변하는 영역에 우선 적용. ADR, 장애 회고, 도메인 모델 등.
한계 3: 벤치마크는 아직 부족하다
71.5배도 499배도 "한 사례의 측정"입니다. 정확도(answer quality)에 대한 표준 벤치마크는 아직 없습니다. 토큰만 줄고 답변 품질이 떨어지면 의미가 없죠.
대응책: 도입 초기 한 달은 RAG 모드와 비교. 같은 질문에 양쪽 답변을 받아 품질을 직접 평가. 그 후 단계적 전환.
한계 4: 운영 측면 미해결
위키에 권한·감사·롤백·동시 편집 같은 "엔터프라이즈 위키"가 가진 기능은 아직 없습니다. 개인·소규모 팀 단계에선 충분하지만, 100명짜리 조직에서 표준화하려면 빈자리가 많습니다.
대응책: 당분간은 개인/팀 단위로. 사내 표준 위키(Confluence 등)와 병행하면서 점진 비교.
8. 빠른 시작 체크리스트
오늘 저녁 30분 안에 시도해볼 수 있는 최소 셋업:
- [ ]
~/brain폴더 만들기, raw/ wiki/ 두 하위 폴더 생성 - [ ] CLAUDE.md 작성 (위 최소 시작본 복사)
- [ ] Obsidian으로
~/brain을 vault으로 등록 - [ ]
pipx install graphifyy && graphify install - [ ]
graphify claude install로 Claude Code 통합 - [ ] raw/articles/ 에 평소 보던 블로그 글 5~10개 마크다운으로 떨구기
- [ ] Claude Code에 "raw 보고 wiki 만들어" 한 마디
- [ ] Obsidian 그래프 뷰로 페이지 간 연결 시각적으로 확인
- [ ]
/graphify .실행해 토큰 비교용 그래프 생성 - [ ] 같은 질문을 (a) raw 통째로 (b) 그래프 기반 두 모드로 던져보고 토큰·답변 비교
마치며
핵심을 다시 정리합니다.
- RAG는 "꺼내 쓰는" 시스템, LLM Wiki는 "누적되는" 시스템. 두 패턴은 대체재라기보다 서로 다른 문제를 푸는 도구입니다. 천천히 깊어지는 도메인 지식에는 위키가, 빠르게 변하는 대규모 코퍼스에는 RAG가 자연스럽습니다.
- 3계층 (raw / wiki / CLAUDE.md) 의 단순함이 핵심. 폴더 두 개와 규칙 파일 하나면 LLM이 위키 관리자로 변신합니다. 더 복잡한 인프라 없이 시작 가능.
- Graphify의 71.5배는 "가능한 최대치"가 아니라 "한 사례의 평균". 코퍼스가 클수록 절감폭이 커집니다. 작은 프로젝트에선 그래프 빌드 비용이 더 클 수도 있으니 무턱대고 적용하지 말 것.
- 실전 도입은 천천히 변하는 영역부터. ADR, 장애 회고, 도메인 모델, 학습 노트. 매일 변하는 코드보다 한 달에 한 번 변하는 결정 기록이 ROI가 더 좋습니다.
- 운영 기능은 아직 미숙. 권한·감사·롤백이 필요한 환경에선 사내 표준 위키와 병행하면서 점진 비교가 안전합니다.
다음 글에서는 이 패턴을 한 단계 더 끌어올리는 "위키 페이지 자동 검증 - LLM-as-Judge로 잘못된 정리 잡아내기" 를 다룹니다. 한 번 잘못 정리된 페이지가 영구화되는 걸 막는 게, 위키 시스템의 다음 과제입니다. 영구 메모리 글의 검증 패턴과 같은 결입니다.