LLM Wiki 만드는 법 — 30분 따라하기

답부터. 벡터DB도 임베딩도 필요 없다. 폴더 세 개와 규칙 파일 하나면 되고, 30분이면 만든다.

자료가 쌓이는데 AI가 그걸 기억을 못 한다. 어제 정리해준 내용을 오늘 또 처음부터 설명해야 한다. 이 문제를 푸는 방법이 LLM Wiki다. 안드레이 카파시가 2026년 4월 공개한 패턴이고, 제품이 아니라 폴더 구조와 규칙의 조합이라 오늘 당장 만들 수 있다.

이 글은 개념 설명이 아니라 따라하기다. 명령어를 순서대로 치면 된다.

질문	한 줄 답
뭐가 필요한가	폴더 3개 + 규칙 파일 1개. 벡터DB·임베딩 없음
얼마나 걸리나	30분 (클로드 코드 설치 포함)
뭘 깔아야 하나	클로드 코드 하나. 단 Pro 이상 유료 플랜이 필요하다
코딩 할 줄 알아야 하나	코딩은 필요 없다. 다만 터미널에 명령어를 붙여넣을 수는 있어야 한다

Bookshelves in a library with a vintage tone Photo by Mario Spencer on Pexels

만들면 뭐가 달라지나

답부터: AI가 내 자료를 기억하기 시작한다.

말로 하면 와닿지 않으니 실제 차이를 보자.

지금 (위키 없음)

나: 작년에 내가 가스터빈 관련해서 정리한 내용 좀 찾아줘 AI: (폴더를 뒤져서 파일 몇 개를 읽고) 네, 이런 내용이 있습니다… — 찾아주긴 한다. 그런데 정리한 결과가 어디에도 안 남는다. 내일 같은 걸 물으면 파일을 처음부터 다시 읽는다.

위키를 만든 뒤

나: 가스터빈 관련해서 내가 정리한 내용 다 모아줘 AI: 위키에 세 곳에 걸쳐 있습니다. · [[가스터빈 공급 병목]] — 납기가 2028~30년까지 밀려 있다는 내용. 근거는 raw/oilprice-2026-09.md · [[데이터센터 전력수요]] — 이 병목의 원인으로 연결돼 있습니다 · [[GE 베르노바]] — 수주잔고 관련. 다만 confidence: medium이라 재확인이 필요합니다

차이는 두 가지다. 정리한 결과가 문서로 남는다는 것, 그리고 답에 근거 파일이 붙어 나온다는 것.

그리고 결정적으로 — 쓸수록 좋아진다. 자료를 넣을 때마다 AI가 기존 문서를 함께 고쳐놓기 때문이다.

따라하기 ⓪ 준비물 (10분)

답부터: 클로드 코드를 깔아야 하고, 유료 플랜이 필요하다.

먼저 솔직하게 짚고 가자. 클로드 코드는 Pro 이상 유료 플랜에서만 쓸 수 있다. 무료 claude.ai 플랜에는 포함되지 않는다. 이미 쓰고 있다면 이 단계를 건너뛰어도 된다.

설치는 한 줄이다.

# 맥 · 리눅스 · WSL
curl -fsSL https://claude.ai/install.sh | bash

# 윈도우 파워셸
irm https://claude.ai/install.ps1 | iex

설치 확인:

claude --version

2.1.222 (Claude Code) 같은 버전이 찍히면 성공이다.

첫 실행 때는 브라우저가 열려 로그인을 요구하고, 이어서 “이 폴더를 신뢰하느냐”고 묻는다. 둘 다 승인하면 된다.

터미널은 맥이면 터미널 앱을 열면 된다. 윈도우는 파워셸로도 클로드 코드가 돌아가지만, 이 글의 명령어는 bash 기준이라 WSL이나 Git Bash에서 치는 게 편하다. (뒤에 나오는 옵시디언 연동까지 생각한다면 WSL보다 Git Bash 쪽을 권한다. WSL은 파일이 리눅스 쪽에 들어가 윈도우 앱인 옵시디언에서 열기 번거롭다.)

따라하기 ① 폴더 만들기 (2분)

터미널에 이 한 줄을 붙여넣는다.

mkdir -p ~/mywiki/{raw,wiki,outputs} && cd ~/mywiki && git init

이게 전부다. 폴더 세 개를 만들고, 그 안으로 들어가고, 깃(버전 관리)을 켰다.

화면에 이게 뜨면 성공이다.

Initialized empty Git repository in /Users/이름/mywiki/.git/

각 폴더가 뭐냐면:

폴더	뭘 넣나	누가 건드리나
`raw/`	원본. 기사, PDF, 회의록, 내가 쓴 글	내가 넣기만. AI는 읽기만
`wiki/`	정리본. AI가 만든 문서들	AI가 씀. 나는 읽음
`outputs/`	점검 리포트	AI가 씀

깃을 처음 쓴다면 이름과 메일을 한 번 등록해야 한다. 안 하면 나중에 저장(커밋)할 때 에러가 난다.

git config --global user.name "내이름"
git config --global user.email "내메일@example.com"

한 번만 하면 되고, 깃을 써본 적 있다면 건너뛰어도 된다.

깃을 켜는 건 선택이 아니다. 뒤에서 설명하겠지만 AI가 한 번에 파일 열댓 개를 고치는 구조라, 되돌릴 수단이 없으면 실수 한 번에 위키가 망가진다.

따라하기 ② 규칙서 붙여넣기 (5분)

이제 AI에게 “너는 이 위키의 관리자다”라고 알려주는 파일을 만든다. 파일 이름은 CLAUDE.md 또는 AGENTS.md다.

둘 중 아무거나 써도 된다. AGENTS.md는 클로드 코드·커서·코덱스가 공통으로 읽는 규격으로 자리잡는 중이라, 도구를 갈아탈 생각이면 이쪽이 안전하다. (커서의 .cursorrules는 예전 방식이다. 지금은 .cursor/rules/나 AGENTS.md를 쓴다.)

저장은 AI에게 시키는 게 제일 쉽다. 터미널에서:

cd ~/mywiki && claude

그리고 아래 내용을 복사한 뒤 이렇게 말하면 된다.

아래 내용을 그대로 CLAUDE.md 파일로 저장해줘. (여기에 붙여넣기)

메모장으로 직접 만들어도 되지만, 맥 기본 텍스트편집기는 서식 있는 문서로 저장돼 .rtf가 붙는 함정이 있다. AI에게 시키는 쪽이 확실하다.

# 이 폴더는 LLM Wiki다

## 폴더 규칙
- `raw/` — 원본. 절대 수정·삭제하지 마라. 읽기만 해라.
- `wiki/` — 네가 만들고 관리하는 정리본.
- `outputs/` — 날짜를 단 점검 리포트.

## 페이지 쓰는 법
파일명은 영문 소문자와 하이픈으로. 문서끼리는 [[대괄호 두 개]]로 연결.
네가 만드는 위키 페이지마다 맨 위에 아래 머리말을 붙여라 (이 파일이 아니라 위키 페이지에).

---
title: 문서 제목
sources:            # 근거가 된 raw/ 파일 경로
  - raw/...
related:            # 관련 문서
  - "[[...]]"
confidence: high | medium | low
updated: YYYY-MM-DD
---

근거 없는 문장을 쓰지 마라. 모든 주장은 sources의 파일로 되짚어갈 수 있어야 한다.
sources에 쓸 게 없으면 그 페이지는 만들지 마라.
추정이면 confidence를 낮추고 본문에 추정이라고 밝혀라.

## 내가 "정리해줘"라고 하면 (ingest)
1. raw/의 새 파일을 읽고, 무엇이 중요한지 먼저 나에게 말해라
2. wiki/sources/ 에 그 자료의 요약 페이지를 만들어라
3. **관련된 기존 페이지를 전부 찾아서 함께 고쳐라** — 이 단계를 건너뛰지 마라
4. 필요하면 새 페이지를 만들어라
5. wiki/index.md (목차)를 갱신해라
6. wiki/log.md 맨 아래에 한 줄 추가해라 (날짜 · 넣은 자료 · 바뀐 페이지)

## 내가 질문하면 (query)
1. wiki/index.md 를 먼저 읽고 관련 페이지를 골라라
2. 그 페이지들을 읽고 답해라. raw/ 를 다시 뒤지지 마라
3. 답에 [[위키링크]]로 근거를 달아라
4. 위키에 없는 내용이면 "위키에 없다"고 말해라. 지어내지 마라

## 내가 "점검해줘"라고 하면 (lint)
아래를 찾아서 outputs/lint-날짜.md 로 보고해라.
- 페이지끼리 말이 안 맞는 곳
- 아무도 링크하지 않는 외톨이 페이지
- 링크는 걸렸는데 실제로 없는 페이지
- updated 가 6개월 넘은 페이지

여기서 진짜 중요한 문장은 두 개다.

“sources에 쓸 게 없으면 그 페이지는 만들지 마라”
“위키에 없으면 없다고 말해라. 지어내지 마라”

이 둘이 빠지면 AI가 그럴듯한 내용을 채워 넣기 시작한다. 그 순간 위키를 못 믿게 되고, 못 믿는 위키는 없느니만 못하다. 다른 건 다 빼도 이 두 줄은 꼭 넣자.

따라하기 ③ 자료 넣고 첫 정리 시키기 (10분)

먼저 자료를 넣는다. ~/mywiki/raw/ 폴더에 파일을 몇 개 복사해 넣으면 된다.

스크랩해둔 기사
PDF 보고서
회의록
예전에 쓴 글
웹페이지를 복사해 붙인 텍스트 파일

무엇이든 된다. 다섯 개 정도면 충분하다. 처음부터 백 개를 넣지 말자. 결과물이 마음에 안 들 때 되돌리기 힘들다.

그다음 AI를 부른다. 터미널에서:

cd ~/mywiki && claude

그리고 이렇게 말한다.

raw/ 폴더에 자료를 넣었어. CLAUDE.md 규칙대로 정리해줘.

AI가 이 순서로 움직이면 정상이다.

파일들을 읽는다
무엇이 중요한지 먼저 말해준다 — 여기서 방향이 틀렸으면 바로잡자
wiki/sources/ 아래에 요약 페이지를 만든다
wiki/ 아래에 개념 페이지들을 만든다
wiki/index.md(목차)를 만든다
wiki/log.md에 기록을 남긴다

완료 확인은 이렇게 한다.

ls ~/mywiki/wiki/

index.md, log.md, 그리고 폴더 몇 개가 보이면 성공이다. index.md를 열어보면 무엇이 어디 있는지 목차가 잡혀 있다.

그리고 바로 저장해둔다.

cd ~/mywiki && git add . && git commit -m "첫 정리"

앞으로도 정리시키기 전후로 이 명령을 치는 습관을 들이자. 저장해두면 AI가 엉뚱하게 고쳤을 때 되돌릴 수 있다.

되돌리는 명령은 이것이다.

cd ~/mywiki && git reset --hard && git clean -fd

git clean -fd가 꼭 같이 있어야 한다. git reset --hard만 치면 AI가 새로 만든 파일은 그대로 남는다. 저장한 적이 없는 파일이라 깃이 손대지 않기 때문인데, 그러면 절반만 되돌아간 어중간한 상태가 되어 더 헷갈린다.

⚠️ 주의. 이 두 명령은 마지막 저장 이후의 모든 변경을 되살릴 수 없게 지운다. 내가 손으로 넣어둔 raw/ 파일도 저장 전이면 같이 날아간다. 되돌리기 전에 남길 게 없는지 꼭 확인하자.

지우기가 불안하면 **git stash -u**를 쓰자. 똑같이 되돌아가면서 지운 내용을 따로 보관해둔다.

white printer paper on brown wooden table Photo by Carolina Gonçalo on Unsplash

따라하기 ④ 질문해보기 (3분)

이제 써보자. 같은 폴더에서 클로드 코드를 띄우고 그냥 물어보면 된다.

내가 넣은 자료에서 ○○에 대해 뭐라고 정리돼 있어?

제대로 됐다면 답이 이렇게 나온다.

위키에 두 곳에 있습니다. · [[○○ 개념]] — (내용). 근거: raw/파일명.md · [[관련 개념]] — (내용). 다만 confidence가 medium입니다

근거 파일이 붙어 나오는지를 꼭 확인하자. 그게 안 붙으면 규칙서의 sources 규칙이 안 먹히고 있다는 뜻이다.

그리고 “위키에 없는 것”을 일부러 물어보자. “없다”고 답하면 규칙이 제대로 작동하는 것이고, 그럴듯하게 지어내면 규칙서를 손봐야 한다. 이 테스트를 꼭 해보길 권한다. 위키를 믿을 수 있는지 없는지가 여기서 갈린다.

자료를 더 넣을 때

똑같다. raw/에 파일을 넣고 “정리해줘”라고 하면 된다.

이때 AI가 기존 페이지들까지 함께 고치는지 보자. 새 자료가 기존 내용과 관련 있으면 그 문서들도 갱신돼야 한다. 이게 이 패턴의 핵심 값어치다. 사람은 절대 안 하는 일이고, 안 하면 위키가 금방 낡는다.

한 달에 한 번은 점검

점검해줘

이러면 모순된 곳, 외톨이 페이지, 깨진 링크를 찾아 outputs/에 리포트를 남긴다. 위키는 커지면 반드시 망가지므로 월 1회 정도 돌리는 걸 루틴으로 잡자.

더 쉬운 길 — 스킬 한 줄로 끝내기

답부터: 규칙서 쓰기가 부담이면 이미 만들어진 걸 깔면 된다.

먼저 위키를 둘 폴더를 만들고 그 안에서 실행해야 한다. 이 명령은 현재 폴더에 설치되기 때문에, 홈 디렉터리에서 치면 엉뚱한 곳이 어질러진다.

mkdir -p ~/mywiki && cd ~/mywiki
npx skills add Astro-Han/karpathy-llm-wiki

(예전 이름인 npx add-skill도 아직 동작하지만, 패키지가 skills로 이름을 바꿨다.)

명령을 치면 어느 도구에 설치할지 고르는 화면이 뜬다. 깔려 있는 도구는 자동으로 선택돼 있으니 그대로 진행하면 된다. MIT 라이선스라 무료로 쓰고 고쳐도 된다.

설치 화면에 경고가 하나 뜬다. 스킬은 AI 에이전트의 권한을 그대로 갖고 실행되므로, 남이 만든 스킬을 깔 때는 내용을 한 번 훑어보는 게 좋다. 이 스킬은 마크다운 파일을 읽고 쓰는 게 전부지만, 습관을 들여두자.

Agent Skills라는 공통 규격을 따르기 때문에 클로드 코드·커서·오픈코드에서 그대로 동작한다. (코덱스 CLI는 스킬 폴더에 수동으로 복사해야 한다.)

단, 주의할 게 하나 있다. 이 스킬은 주제별 폴더(raw/주제이름/, wiki/주제이름/)를 쓴다. 위에서 만든 구조와 다르다. 스킬을 쓸 생각이면 폴더를 미리 만들지 말고, 설치한 뒤 스킬이 시키는 대로 따라가자. 안 그러면 구조가 어긋나 헷갈린다.

이게 왜 되는가 — 구조 이해하기

여기까지 따라했으면 이미 작동하는 위키가 생겼다. 이제 왜 이렇게 생겼는지 보자. 알고 나면 본인 일에 맞게 고칠 수 있다.

핵심은 “정리하는 시점”을 앞당긴 것

보통 AI에게 자료를 물어보는 방식(RAG라고 부른다)은 질문을 받고 나서 원문을 뒤져 답을 만든다. 잘 작동하지만 어제 답한 내용이 오늘 남아 있지 않다. 같은 자료를 백 번 물으면 백 번 처음부터 읽는다.

LLM Wiki는 자료를 넣는 시점에 정리를 끝낸다. 질문이 오면 이미 정리된 걸 읽는다. 그래서 쓸수록 좋아진다.

카파시가 쓴 문장이 핵심을 찌른다.

“지식베이스 유지에서 지루한 부분은 읽기나 생각이 아니라 **기록 관리(bookkeeping)**다.”

“LLM은 지루해하지 않고, 교차 참조 갱신을 잊지 않으며, 한 번에 파일 15개를 손볼 수 있다.”

사람이 위키 관리에 실패하는 지점은 새 글을 쓰는 게 아니다. 새 글을 쓴 뒤 관련된 기존 문서 열 군데를 고치는 일이다. 귀찮아서 다들 안 한다. LLM은 그걸 안 귀찮아한다.

`raw/`를 안 건드리는 이유

이게 이 패턴에서 가장 중요한 규칙이다. 위키의 모든 주장은 raw/의 파일로 되짚어갈 수 있어야 한다. 원본이 변하면 무엇이 근거였는지 알 수 없게 되고, 그러면 AI가 쓴 내용을 검증할 방법이 사라진다.

고치고 싶은 내용이 생기면 원본을 고치지 말고 새 자료로 넣는다.

비유 둘

카파시 본인은 이렇게 비유했다. “옵시디언이 IDE, LLM이 프로그래머, 위키가 코드베이스다.” 사람이 도구를 고르고, LLM이 그 안에서 일하고, 결과물이 쌓인다.

이 패턴을 풀어 쓴 Starmorph 가이드는 한 걸음 더 나간 비유를 든다.

위키	컴파일러로 치면
`raw/` (원본)	소스코드
LLM	컴파일러
`wiki/` (정리본)	실행 파일
점검(lint)	테스트
질문	런타임

소스코드를 고치면 다시 빌드한다. 자료를 넣으면 위키를 다시 정리한다. 같은 이야기다.

폴더 구조는 정답이 없다

카파시가 말한 세 층은 원본(raw) · 위키(wiki) · 규칙서다. 즉 세 번째 층은 폴더가 아니라 우리가 ②단계에서 만든 CLAUDE.md 그 자체다. (outputs/는 점검 리포트를 모아두려고 이 글에서 덧붙인 것이고, 원문에는 없다.)

그리고 폴더 이름은 원문이 정해 두지 않았다. 카파시 본인이 “정확한 디렉터리 구조, 스키마 관례, 페이지 형식, 도구는 전부 당신의 분야에 달려 있다”고 썼다. 흔히 쓰는 관례는 이렇다.

wiki/
├── index.md      (목차 — 매번 갱신)
├── log.md        (기록 — 추가만)
├── concepts/     (개념)
├── entities/     (인물·기업·기관)
├── sources/      (원본 요약)
└── comparisons/  (비교)

본인 일에 맞게 바꿔도 된다. 리서치를 한다면 hypotheses/(가설)를 두고, 인물을 많이 다룬다면 people/을 따로 빼는 식이다. 규칙서에 적기만 하면 AI가 따른다.

RAG 대신 이걸 쓰는 기준

답부터: 자료가 100개 안팎이면 위키, 수백만 건이면 RAG다.

	RAG	LLM Wiki
지식이 쌓이나	안 쌓임 — 매번 처음부터	쌓임
뭘 깔아야 하나	벡터DB, 임베딩 파이프라인	폴더만
문서 간 연결	물어볼 때마다 새로 찾음	미리 만들어 둠
관리	임베딩 갱신 필요	넣을 때마다 AI가 알아서
근거 추적	조각 단위 — 불완전	원본 파일까지

비교 항목은 Starmorph 가이드 기준. 다만 비용은 단정하기 어렵다 — 위키는 페이지 전문을 통째로 읽히므로, 위키가 커지면 조각만 가져오는 RAG보다 토큰이 더 들 수도 있다.

위키가 맞는 경우

자료가 100개 안팎 — 카파시는 “소스 약 100개, 페이지 수백 개 규모까지 놀랄 만큼 잘 된다”고 썼다. 해설 가이드들은 50~200개를 범위로 본다
지식이 쌓이는 것이 중요할 때
나중에 왜 그렇게 답했는지 확인해야 할 때

RAG가 맞는 경우

문서가 수백만 건
문서가 수시로 바뀜
밀리초 단위 응답이 필요한 서비스
대규모 팀이 공유

개인이나 소규모 팀이라면 거의 언제나 위키 쪽이다. 벡터DB를 세우고 유지하는 품이 얻는 것보다 크다.

옵시디언을 쓰고 있다면

답부터: 이미 절반쯤 만들어져 있다.

옵시디언 보관함은 그대로 마크다운 파일 폴더이고, [[대괄호 링크]]도 문법이 같다. 구조만 나누면 된다.

보관함 안에 raw/와 wiki/ 폴더를 만든다
기존 노트를 raw/로 옮긴다
보관함 최상단에 CLAUDE.md를 놓는다
보관함 폴더에서 클로드 코드를 실행한다

별도 도구를 깔 필요가 없고, AI가 만든 페이지를 옵시디언 그래프 뷰에서 바로 볼 수 있다.

주의할 점. 기존 노트를 raw/로 옮겼다면 그 뒤로는 손으로 고치지 않는 게 원칙이다. 계속 손으로 쓰고 싶은 노트가 있다면 raw/ 밖에 따로 두자. 원본이 흔들리면 근거 추적이 끊긴다.

막히기 쉬운 곳 5가지

① AI가 근거 파일을 안 붙인다 규칙서의 sources 부분이 안 먹히고 있다. “모든 페이지에 sources를 반드시 넣어라. 없으면 페이지를 만들지 마라”를 더 강한 표현으로 다시 적자.

② 위키에 없는 걸 지어낸다 가장 위험한 증상이다. 규칙서에 “위키에 없으면 없다고 말해라”를 맨 위로 올리고, 실제로 없는 걸 물어 테스트하자.

③ 새 자료를 넣어도 기존 페이지가 안 바뀐다 AI가 3단계를 건너뛰는 것이다. 규칙서에 “이 단계를 건너뛰지 마라”를 명시하고, 정리시킬 때 “기존 페이지도 함께 갱신해줘”를 덧붙이자.

④ 위키가 뒤죽박죽이다 자료를 너무 많이 한꺼번에 넣었을 가능성이 크다. git reset --hard && git clean -fd로 되돌리고(위의 주의 사항을 먼저 읽자) 다섯 개씩 나눠 넣자. 깃을 켜두라는 이유가 이것이다.

⑤ 뭘 물어야 할지 모르겠다 wiki/index.md를 열어보자. 목차가 곧 “지금 이 위키가 답할 수 있는 것들”의 목록이다.

정리

핵심은 하나다. 정리하는 시점을 앞당기는 것.

보통은 질문을 받고 나서 자료를 뒤진다. LLM Wiki는 자료를 받을 때 이미 정리해 둔다. 그래서 답이 빠르고, 근거가 남고, 무엇보다 쓸수록 좋아진다.

지금 바로 시작하려면 이 한 줄이면 된다.

mkdir -p ~/mywiki/{raw,wiki,outputs} && cd ~/mywiki && git init

그다음 규칙서를 붙여넣고, 자료를 다섯 개 넣고, “정리해줘”라고 하면 된다. 30분이면 내 자료를 기억하는 AI가 생긴다.

이 글은 공개된 자료를 바탕으로 한 사용 안내이며 특정 도구 사용을 권유하지 않는다. LLM Wiki는 제품이 아니라 패턴이라 구현체마다 세부가 다를 수 있으니, 각 저장소의 최신 문서를 함께 확인하기 바란다.

참고 자료

Andrej Karpathy — llm-wiki (원문 gist) — 패턴의 원 출처. 3계층 구조와 ingest·query·lint 정의
Astro-Han/karpathy-llm-wiki — Agent Skills 호환 구현체, npx add-skill로 설치
lucasastorian/llmwiki — MCP로 클로드를 연결하는 또 다른 오픈소스 구현
Starmorph — Karpathy’s LLM Wiki: The Complete Guide — 폴더 구조 관례, 규칙서 템플릿, RAG 비교표

함께 보면 좋은 글

오픈클로(OpenClaw) 2.0 설치·사용법 — 컴퓨터를 조작하는 에이전트 세팅
GPT-6 아스트라 사용법 — 요금제·설치·설정