콘텐츠로 이동

카파시의 LLM 위키를 반년 운영해 보니: 마크다운 세컨드 브레인의 구조와 규칙

2026년 4월, 안드레이 카파시(Andrej Karpathy)가 "LLM Wiki"라는 짧은 문서를 공개했습니다. 사람이 원본 자료를 모으면 LLM이 마크다운 위키를 쓰고 고치며 키워 간다는 아이디어입니다. 같은 달 18일에 이 문서를 Claude Code에게 건네고 개인 위키를 시작했습니다. 그 위키가 지금의 wiki.wonslab.dev입니다. 이 글은 패턴을 소개하는 글이 아니라, 반년 동안 실제로 굴려 보며 원안에 무엇을 더해야 했는지에 대한 기록입니다.

이 글의 기준

2026년 4월에 올린 같은 주제의 글은 유튜브 영상 한 편을 요약한 것이었습니다. 2026-10-24에 직접 운영 중인 위키 저장소의 작업 기록(wiki/log.md), 운영 규칙 파일(CLAUDE.md), git 기록을 근거로 전면 다시 썼습니다. 날짜와 수치는 모두 그 기록에서 옮겼습니다.

1. 카파시가 제안한 것: 세 개의 층과 세 가지 작업

원문은 스스로를 "아이디어 파일"이라고 부릅니다. 구현을 정해 주지 않고, 에이전트에게 붙여 넣으면 에이전트가 사용자와 함께 세부를 만들어 가도록 쓰였습니다. 뼈대는 세 개의 층입니다.

구성 원문의 정의 누가 소유하는가
Raw sources 원본 문서, LLM이 읽기만 하고 고치지 않음 사람
Wiki LLM이 쓰고 유지하는 마크다운 페이지 묶음 LLM
Schema 위키의 구조와 규칙을 LLM에게 알려 주는 문서(CLAUDE.md 등) 사람과 LLM이 함께

작업은 세 가지입니다. 새 원본을 받아 요약하고 기존 페이지에 엮는 Ingest, 쌓인 페이지로 질문에 답하고 좋은 답은 다시 페이지로 남기는 Query, 모순·고아 페이지·빠진 링크를 찾는 Lint입니다. 여기에 페이지 목록인 index.md와 시간순 작업 기록인 log.md를 둡니다.

원문에서 가장 자주 떠올린 문장은 이것입니다. "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." 위키를 코드베이스로 본다면, 코드베이스에 필요한 것도 그대로 필요해집니다. 테스트, 린터, 리뷰, 그리고 사고가 나면 규칙을 고치는 습관입니다. 아래 사례가 전부 그 이야기입니다.

2. 지금의 모습: 숫자로 본 반년

저장소 구조는 원안을 거의 그대로 따릅니다.

my-wiki/
├── CLAUDE.md        # 스키마: 디렉터리 규칙, 워크플로, 작성 표준, 셀프 체크
├── raw/<주제>/      # 원본(불변). PDF·DOCX는 .md 변환본을 같은 곳에 둠
├── wiki/            # LLM 소유. index.md, log.md, 그리고 페이지들
└── scripts/         # style-lint.sh, scaffold-lint.sh, build-site.sh ...

git 기록에서 월말마다 wiki/ 안의 마크다운 파일 수를 세어 보면 이렇게 자랐습니다.

시점 페이지 수 그 시기의 주된 일
2026-04-30 36 위키 초기화, Java 스터디 자료 91편 ingest
2026-05-31 49 하네스 엔지니어링 실습 가이드 작성
2026-06-30 185 도서 5권 강의 교재(장별 페이지) 추가
2026-07-31 202 문체·실습 표준 정비
2026-10-24 214 페이지 병합·정리, 실행 검증, 검색 노출 정비

같은 기간 커밋은 230개, log.md에 남은 작업 기록은 151건입니다. 기록을 유형별로 세면 ingest 32건, fix 27건, feat 17건 순입니다. 새 자료를 넣는 일만큼 고치는 일이 많았다는 뜻입니다.

3. 사례 1 — 링크를 맞추려고 만든 페이지는 빚이 된다

위키를 연 첫날, 첫 Lint에서 깨진 링크 3건이 나왔습니다. LLM은 링크 대상이던 Dataview, Marp, Obsidian Web Clipper 페이지를 새로 만들어 문제를 "해결"했습니다. 링크 검사는 통과했지만 내용은 몇 줄짜리 소개뿐이었습니다. Ingest·Query·Lint도 처음에는 각각 별도 개념 페이지였습니다.

이 얇은 페이지들은 9월 28일 구조 정리 때 다시 합쳐졌습니다. 도구 페이지들은 Obsidian 페이지의 "플러그인·주변 도구" 절로, 워크플로 페이지 셋은 하나의 위키 워크플로 페이지로 들어갔습니다. 본문 없이 링크만 모아 둔 북마크 페이지는 삭제했고, 사라진 옛 주소 9개에는 301 리다이렉트를 걸었습니다.

교훈: LLM에게 "깨진 링크를 없애라"고 하면 가장 쉬운 방법을 고릅니다. 검사를 통과하는 방법과 위키가 좋아지는 방법은 다를 수 있으므로, 새 페이지를 만들지 기존 페이지에 합칠지는 사람이 정합니다.

4. 사례 2 — 원본도 틀린다

원안은 raw를 "불변"으로 둡니다. 운영해 보니 불변이라는 말이 "원본은 옳다"로 읽히는 것이 문제였습니다.

7월 4일, 노션에서 옮겨 온 스터디 자료 97편을 원본 블록 수와 대조했습니다. 65편은 이상이 없었고, 17건은 옮기는 과정에서 내용이 빠져 있었습니다. 한 챕터는 300줄이 넘는 분량이 통째로 없었습니다. 같은 작업에서 원본 자체의 오류도 나왔습니다. Java와 C++를 비교한 표에 "C는 함수형"이라고 적혀 있었고, 이것은 절차적 언어로 고쳤습니다.

6월 29일에는 실습 키트에 있던 Claude Code 훅 예제가 현재 사양과 맞지 않아 실제로는 아무것도 막지 못한다는 것을 확인했습니다. 도구 실행을 차단하려면 종료 코드 2를 돌려줘야 하는데 예제는 1을 쓰고 있었고, 입력도 표준 입력의 JSON이 아니라 명령행 인자로 받는다고 가정하고 있었습니다.

그래서 CLAUDE.md의 규칙을 이렇게 바꿨습니다.

원래 규칙 바꾼 규칙
raw는 수정하지 않는다 raw는 불변이되, 사실 오류는 고치고 교정 근거를 주석으로 남긴다
원본을 요약한다 원본도 공식 문서·정평 있는 도서와 대조한 뒤 요약한다
실습을 옮긴다 실습은 직접 돌려 보고 "실행 검증됨(날짜, 환경)" 배너로 재현 범위를 밝힌다

교훈: 위키가 원본을 충실히 옮길수록 원본의 오류도 충실히 퍼집니다. 원본 보존과 원본 신뢰는 다른 규칙이어야 합니다.

5. 사례 3 — 문체는 부탁하지 않고 스크립트로 검사한다

페이지가 180개를 넘자 문체가 흔들렸습니다. 7월 2일 점검에서는 최근에 덧붙인 실습 절이 전부 "~한다"체인데 기존 본문은 "~합니다"체여서, 한 절 안에서 말투가 꺾이는 문제가 가장 심각한 불일치로 나왔습니다. "커맨드/명령", "폴더/디렉터리/디렉토리" 같은 용어도 섞여 있었습니다.

프롬프트에 "문체를 통일해 줘"를 더하는 대신 scripts/style-lint.sh를 만들었습니다. 금칙 용어, 라벨형 성공 문구, 곡선따옴표, 챕터 본문의 평어 종결을 grep으로 찾고, 위반이 있으면 종료 코드 1로 끝납니다. LLM을 호출하지 않으니 비용은 0입니다. 만든 뒤에는 모범 챕터에 돌려 오탐이 없는지, 위반이 알려진 챕터에 돌려 그 위반을 정확히 잡는지 먼저 확인했습니다.

다음 날에는 같은 방식으로 scaffold-lint.sh를 만들었습니다. 실습 코드의 파일 이름, package 선언, public 클래스 이름이 서로 맞는지 검사합니다. 첫 실행에서 한 챕터의 실습 18개가 전부 Main이라는 같은 클래스 이름을 쓰고 있는 것이 드러났습니다. 한 프로젝트에서 따라 하면 서로 충돌하는 예제였습니다.

지금은 페이지를 저장할 때마다 다음 세 명령을 통과해야 합니다.

bash scripts/style-lint.sh wiki/새페이지.md       # 문체·용어
bash scripts/scaffold-lint.sh wiki/새실습.md      # 실습 예제가 있을 때만
bash scripts/build-site.sh                       # 위키 링크 변환 + MkDocs 빌드

교훈: 기계가 판정할 수 있는 규칙은 스크립트로 옮기고, 스크립트는 먼저 오탐과 미탐을 확인한 뒤에 믿습니다.

6. 사례 4 — 공개하자 페이지들이 서로 닮아 보였다

위키를 MkDocs로 빌드해 공개하자 다른 종류의 문제가 생겼습니다. 10월 8일 Search Console에는 212개 페이지가 "크롤링됨 - 현재 색인이 생성되지 않음"으로 나와 있었습니다. 원인을 보니 모든 페이지가 같은 사이트 설명문을 description으로 쓰고 있었고, 사이트맵의 수정일도 전부 빌드 날짜였습니다. 저자만 보는 백로그와 계획 메모까지 색인 대상이었습니다.

빌드 훅을 추가해 페이지마다 본문 첫 문단에서 description을 뽑고, 수정일은 frontmatter의 updated 값을 쓰고, 운영 메모에는 noindex를 붙였습니다. 10월 24일에는 강의 페이지 93개가 제목 5종을 나눠 쓰고 있던 것도 장 주제가 드러나는 제목으로 고쳤습니다.

교훈: 같은 규칙으로 찍어 낸 페이지는 사람 눈에는 일관돼 보여도 검색엔진 눈에는 구분되지 않는 묶음으로 보일 수 있습니다. 페이지마다 다른 점이 메타데이터에도 드러나야 합니다.

원안과 운영본의 차이 한눈에 보기

항목 카파시 원안 반년 운영 후 이 위키
raw 불변 불변이되 오류는 근거와 함께 교정
페이지 작성 LLM이 전부 작성 LLM이 작성, 병합·삭제 판단은 사람
품질 확인 Lint 작업 Lint + style-lint·scaffold-lint·빌드 + 실행 검증 배너
탐색 index.md, 규모가 커지면 검색 도구 index.md + 부모 페이지(강의 장은 목차 페이지로 대표)
세션 인계 따로 다루지 않음 백로그 페이지와 log.md를 새 세션이 먼저 읽음
공개 따로 다루지 않음 페이지별 description·수정일·noindex

원문은 index.md 방식이 "약 100개 소스, 수백 페이지" 정도의 중간 규모까지는 꽤 잘 통한다고 적었습니다. 214페이지인 지금도 별도 검색 엔진 없이 index.md로 운영하고 있습니다. 강의 장 페이지 약 110개를 index에 하나씩 올리지 않고 각 강의의 목차 페이지로 대표시킨 덕분입니다.

💡 원스의 인사이트: 위키가 코드베이스라면, 규칙 파일은 테스트다

반년 동안 CLAUDE.md는 디렉터리 설명 몇 줄에서 원본 검증 정책, 작성 표준, 저장 전 셀프 체크리스트까지 담은 문서로 자랐습니다. 거기 적힌 규칙은 대부분 사고가 한 번 난 자리입니다. 잘린 원본, 섞인 문체, 충돌하는 클래스 이름, 서로 닮은 메타데이터가 각각 한 줄씩 남겼습니다.

그래서 LLM 위키를 시작하려는 분께는 페이지보다 규칙 파일을 먼저 키우라고 말하고 싶습니다. 무엇을 자동으로 맡길지는 금방 정해집니다. 오래 걸리는 것은 무엇을 사람이 확인할지, 그리고 그 확인을 어떤 스크립트로 바꿀지 정하는 일입니다. 같은 지적을 두 번 하게 되면 그 지적을 CLAUDE.md나 스크립트로 옮기세요. 위키가 자랄수록 그 파일이 품질을 지켜 줍니다.

체크리스트 — LLM 위키를 시작하기 전에

  • [ ] 원본(raw)과 LLM이 쓰는 페이지(wiki)를 디렉터리로 분리했다
  • [ ] 스키마 파일(CLAUDE.md 등)에 페이지 형식, 파일 이름 규칙, 작업 절차를 적었다
  • [ ] 모든 작업이 log.md에 날짜와 유형으로 남는다
  • [ ] 원본의 기술적 사실을 공식 문서와 대조하는 단계가 있다
  • [ ] 페이지를 새로 만들지 기존 페이지에 합칠지 사람이 판단한다
  • [ ] 문체·형식처럼 기계가 판정할 수 있는 규칙은 스크립트로 검사한다
  • [ ] 공개한다면 페이지마다 고유한 제목과 설명이 붙는다

참고 자료 및 출처