나무위키는 하루 종일 읽으면서 전공책은 왜 못 읽을까

전공 교과서를 펼치면 10분 만에 잠이 옵니다. 그런데 나무위키에서 ‘양자역학’ 문서를 열면 두 시간이 순삭됩니다. 내용의 밀도로만 보면 교과서가 훨씬 알찬데, 왜 하나는 안 읽히고 하나는 밤을 새우게 될까요.

한참 생각해 보니 결국 탐색의 재미였습니다. 위키는 링크를 타고 옆길로 새는 맛이 있습니다. 하나의 개념에서 다른 개념으로 자연스럽게 넘어가고, 취소선 드립과 (괄호 안 부연설명)이 딱딱한 내용을 슬쩍 풀어줍니다. 그럼 교과서를 나무위키처럼 만들어 버리면 되는 거 아닌가? 이런 생각이 들었습니다.

2026년 3월 17일 오후 1시 55분, Claude Code에게 이 아이디어를 던졌습니다. 그날 저녁까지의 커밋 로그를 그대로 옮기면 이렇습니다.

13:55  Initial commit — Python CLI (1,145줄)
14:24  29분 후 — TypeScript/Bun 전면 리라이트
19:04  v0.3.0 — LLM 파이프라인 + 웹 UI + 다중 프로바이더
19:46  v0.4.0 — 나무위키 페르소나 시스템 탑재
20:13  v0.4.1 — 나무위키 CSS 테마

파이썬으로 시작했다가 29분 만에 갈아엎은 건, 웹 UI까지 붙일 거면 처음부터 TS/Bun이 낫겠다 싶어서였습니다. 그렇게 아이디어에서 배포까지 하루가 걸렸습니다. AI 코딩 에이전트를 쓰면 이 정도 속도는 나옵니다.

문제는, 여기까지가 쉬운 부분이었다는 겁니다.

동작하는 것과, 남한테 보여줄 수 있는 것

v0.4.2는 돌아갔습니다. 문서를 넣으면 위키가 나왔고, 브라우저에서 열렸고, 나름 나무위키처럼 생겼습니다. 그런데 딱 거기까지였습니다. 인증은 없었고, 테스트는 0개였고, 스스로 매긴 코드 품질 점수는 후하게 쳐도 4.0/10이었습니다. 데모로 보여줄 수는 있어도 누군가에게 “이거 써봐”라고 건네기엔 부끄러운 상태였죠.

혼자 만든 코드를 혼자 리뷰하는 게 원래 이렇습니다. 내가 놓친 걸 내가 다시 볼 수 있을 리가 없습니다. 이건 실력이 아니라 시야의 문제라서, 아무리 오래 들여다봐도 같은 자리에서 같은 걸 놓칩니다. 예전에 BurstPick에서 AI 리뷰어를 붙여 봤던 경험이 있어서, kiwimu에도 같은 걸 해보기로 했습니다. 이번엔 좀 더 밀어붙여서요.

그렇게 시작한 게 14명의 AI 페르소나 리뷰였습니다.

14명을 한 번에 부르지는 않았다

처음엔 6명이었습니다. 보안, 성능, 코드 품질, PM, UX, 아키텍처. 전부 “만드는 사람” 쪽의 관점입니다. 여기서 점수가 어느 정도 안정되고 나서야 “쓰는 사람”을 불렀고, 그다음에 전문 영역을 붙였습니다.

순서가 중요했습니다. 보안 구멍이 뻥 뚫린 상태에서 마케팅 피드백부터 받으면 우선순위가 엉킵니다. “가치 제안이 약하다”는 지적과 “누구나 API 키를 바꿀 수 있다”는 지적이 같은 테이블에 올라오면 판단이 흐려지거든요. 그래서 기술 → 사용자 → 전문 영역 순으로 렌즈를 하나씩 늘려갔습니다.

그리고 이 프로세스에서 제일 중요했던 결정은, 리뷰만 하고 끝내지 않는다는 것이었습니다.

리뷰 라운드 N (병렬 에이전트 3~6명)
    ↓
통합 리포트 → CRITICAL / HIGH / MEDIUM / LOW 분류
    ↓
수정 에이전트 팀 (파일 영역별로 나눠서 병렬)
    ↓
커밋 + 푸시 → 라운드 N+1 (수정이 진짜 됐는지 검증)

리뷰 에이전트와 수정 에이전트가 같은 대화 세션 안에서 돕니다. 리뷰 결과가 그대로 수정 에이전트의 프롬프트가 되니까, 지라 티켓을 끊을 필요도 스프린트를 계획할 필요도 없습니다. 컨텍스트가 살아 있는 채로 바로 고칩니다. 이게 혼자서 여러 프로젝트를 굴리는 방식과 잘 맞았습니다.

R01: 58건

첫 리뷰에서 6명이 병렬로 코드베이스 전체를 훑었습니다. 결과는 CRITICAL 9건, HIGH 12건, MEDIUM 17건, LOW 20건, 합쳐서 58건. 예상은 했지만 막상 숫자로 보니 좀 아득했습니다.

제일 뜨끔했던 건 인증 문제였습니다.

// 누구나 API key를 바꿀 수 있었다
POST /api/settings
{ "api_key": "attacker-controlled-key" }

이걸 Security만 잡은 게 아니라 Code Quality, Architecture, PM 네 명이 각자 독립적으로 지적했습니다. 서로 리포트를 보지 않은 상태에서 같은 곳을 가리켰다는 건, 그게 진짜 문제라는 뜻입니다. 이때부터 “몇 명이 합의했는가”가 우선순위를 정하는 기준이 됐습니다. 한 명만 짚은 이슈는 전문적 통찰일 수도 있고 과민 반응일 수도 있지만, 네 명이 짚으면 그냥 고쳐야 하는 겁니다.

성능 쪽에서는 LLM 호출이 완전히 직렬이라는 지적이 나왔습니다.

for (let i = 0; i < chunks.length; i++) {
    const raw = await chatComplete(system, prompt, 16384); // 10개면 50초+
}

Performance 페르소나의 계산으로는 Promise.allSettled + concurrency 3이면 wall-clock을 60% 줄일 수 있었습니다. API 비용은 똑같고 기다리는 시간만 줄어드는, 안 할 이유가 없는 개선이었죠.

그런데 정작 방향을 바꾼 건 PM의 한 줄이었습니다.

“kiwimu는 아직 ‘위키를 만드는 도구’에 머물러 있다. 위키로 학습하는 도구로 진화해야 사람이 다시 돌아온다.”

이 한 문장이 이후의 퀴즈, 간격 반복 같은 학습 기능을 전부 끌고 왔습니다. 당장 급한 건 보안이었지만, 이 프로젝트가 어디로 가야 하는지를 정해준 건 이 지적이었습니다.

수정은 세 팀을 병렬로 투입했습니다. security-fixes는 index.ts/web.ts의 인증·SSRF·경로 탐색을, perf-fixes는 store.ts/renderer.ts의 인덱스와 N+1을, quality-fixes는 chunker.ts/style.css의 잡다한 부채를 맡았습니다. 서로 다른 파일이라 충돌 없이 동시에 돌았고, 다 끝나면 한 번에 커밋했습니다. R04쯤 코드 품질이 4.0에서 8.0으로 올랐고, R05에서 처음으로 “SHIP IT” 판정을 받았습니다.

쓰는 사람은 아직 아무도 안 물어봤다

SHIP IT을 받고 나니 오히려 찜찜했습니다. 여덟 라운드를 돌았는데 리뷰어가 전부 “만드는 사람”이었거든요. 보안, 성능, 아키텍처. 정작 이걸 쓸 사람한테는 한 번도 안 물어봤다는 걸 그제야 깨달았습니다.

그래서 완전히 새로운 페르소나 넷을 만들었습니다. 대학생 사용자의 첫 반응은 이랬습니다.

“시험 벼락치기엔 쓸만한데, 매일 쓸 이유가 없어요. Anki 대체하기엔 SRS도 없잖아요?”

EdTech 전문가는 아예 성적표를 내밀었습니다.

“퀴즈는 있지만 간격 반복이 없고, 학습 이력을 전혀 추적하지 않고, 피드백이 이모지뿐이다. 이 상태를 ‘학습 도구’라고 부르긴 어렵다.”

여덟 라운드 동안 보안·성능·품질 리뷰어 누구도 이걸 문제 삼은 적이 없었습니다. 코드는 멀쩡한데 학습 도구로서는 F였던 거죠. 같은 코드라도 렌즈가 바뀌면 안 보이던 게 보입니다.

그래서 v0.8.0에서 학습 과학 기능을 넣었습니다. 미풀이 → 오답 → 오래된 정답 순으로 문제를 내는 기초적인 간격 반복(ORDER BY RANDOM()에서는 확실히 진화했습니다), 퀴즈마다 “왜 이게 답인지” 붙여주는 해설, 그리고 quiz_attempts 테이블로 쌓는 학습 이력. 다음 라운드에서 대학생 페르소나가 “해설이 제일 큰 변화”라고 평가했습니다.

같은 코드, 다른 렌즈

마지막으로 한 번도 안 써본 관점 넷을 붙였습니다. 여기서 나온 발견이 개인적으로 제일 인상 깊었습니다.

DB Architect가 첫 리뷰에서 이 버그를 잡았습니다.

// INSERT OR REPLACE는 내부적으로 DELETE + INSERT다.
// row의 ID가 바뀌면서 자식 행(quizzes, links)이 고아가 된다!
INSERT OR REPLACE INTO pages ...

// 수정: UPSERT — ID를 유지하니 자식 행이 안전하다
INSERT INTO pages (...) ON CONFLICT(slug) DO UPDATE SET ...

보안 리뷰어도, 성능 리뷰어도, 품질 리뷰어도 열 라운드 동안 못 본 데이터 무결성 버그를, DBA는 처음 보고 바로 찾았습니다. 같은 렌즈로 더 깊이 파는 것보다 다른 렌즈를 하나 추가하는 게 훨씬 남는 장사였던 순간입니다.

Marketing 페르소나는 성장이 없다는 걸 지적했습니다. “‘나만의 학습 위키를 만드세요’는 기능 설명이지 가치 제안이 아니다”, “생성된 위키에 ‘Built with kiwimu’ 배지가 없어서 바이럴 루프가 완전히 막혀 있다”. 당장 고칠 건 아니었지만 메모해 뒀고, 이건 나중에 v1.1에서 다시 튀어나옵니다.

해커톤 심사관은 8.075/10을 줬습니다. Demo Impact 8.5, Technical Depth 8.0, Completeness 8.5, Innovation 7.0, Polish 8.0. “상위 10~15%, 입상권이긴 한데 우승하려면 Innovation을 올릴 킬러 피처가 필요하다”는 평이었습니다. 이 Innovation 7.0이 다음 개발의 숙제가 됐습니다.

v1.0: 진짜 교과서를 넣다

리뷰가 끝나고 남은 건 두 가지였습니다. 심사관이 말한 킬러 피처, 그리고 EdTech가 준 F를 진짜로 지우는 것.

Dynamic Q&A가 킬러 피처였습니다. 위키를 읽다가 모르는 부분을 드래그하면 팝오버가 뜨고, 그 자리에서 LLM에게 물어볼 수 있습니다. 답변은 새 개념 페이지로 자동 생성되고, 드래그한 텍스트는 그 페이지로 가는 하이라이트 링크가 됩니다. 궁금증이 생기는 순간 위키가 유기적으로 확장되는 거죠. services/dynamic-qa.ts(서버)와 build/static/dynamic-qa.js(클라이언트)로 붙였습니다.

SM-2 간격 반복으로 EdTech의 F를 지웠습니다. Anki가 쓰는 그 알고리즘을 구현해서, 퀴즈 결과에 따라 복습 일정이 자동으로 조정되게 했습니다. 여기에 웹에서 각 페이지 마크다운을 바로 고치는 편집 모달까지 붙인 게 v1.0.0이었습니다.

그리고 마지막으로, 진짜 데모를 만들었습니다. kiwimu add <directory>로 디렉토리 안의 .md를 통째로 넣을 수 있게 하고, OpenStax의 University Physics·Astronomy 마크다운을 받아서 실제 대학 교과서 수준의 위키를 통으로 생성했습니다. KaTeX로 수식 렌더링까지 붙이니 물리 교과서의 복잡한 수식도 안 깨지고 나왔습니다. 이걸 Docker로 싸서 Traefik + CoreDNS + Let’s Encrypt로 홈랩 내부망에 올렸습니다. 여기까지가 딱 12일이었습니다.

12일 만에 여기까지 왔다는 게 스스로도 신기했는데, 정작 그다음이 더 오래 걸렸습니다.

만드는 것보다, 알리는 게 어려웠다 (v1.1)

v1.0을 올려놓고 한 달을 그냥 흘려보냈습니다. 개발자에게 “만들기”는 익숙한 일인데 “알리기”는 완전히 다른 근육이라, 손이 잘 안 갔습니다. 그러다 Marketing 페르소나가 짚었던 “바이럴 루프가 막혀 있다”는 말이 계속 걸렸습니다.

그래서 v1.1은 두 갈래로 진행했습니다. 하나는 실제로 알리기 위한 준비, 하나는 알릴 만한 게 되도록 만드는 것.

알리기 쪽은 30초짜리 데모 GIF가 핵심이었습니다. 이진탐색트리 페이지에서 “회전(rotation)“을 드래그 → 질문 → AI가 답변 → 클릭 한 번으로 정식 위키 페이지가 되는 흐름을 담았습니다. 자막은 한/영 두 버전으로 만들고, “정식 위키 페이지가 됩니다” 부분에서 나무위키 그린(#66bb6a)으로 강조를 줬습니다. 이 순간이 이 도구의 매직 모먼트니까요. LinkedIn·Threads·HN·Reddit용 카피까지 채널별로 따로 썼습니다.

만드는 쪽은, Karpathy가 공유한 LLM 위키 패턴에서 힌트를 얻어 여섯 가지를 붙였습니다. 이걸 한 문장으로 요약하면 “위키는 만드는 게 아니라 자라는 것”이었습니다.

• 출처 추적: AI가 쓴 모든 문장에 [^src:slug] 형태의 인라인 인용을 자동으로 붙입니다. AI가 만든 위키의 가장 큰 약점은 “이거 어디서 나온 거야?”인데, 클릭하면 원본으로 점프하고, 커버리지 행렬로 “원본 인용 없이 AI가 지어낸 페이지”를 한눈에 골라낼 수 있게 했습니다.
• 스키마 레이어: kiwi.toml에 카테고리·용어·템플릿을 정의하면 LLM이 그 틀 안에서만 씁니다. 위키가 커지면 일관성이 무너지는데, 사람이 잡으면 지치고 LLM에 맡기면 제멋대로가 됩니다. 그 사이를 스키마가 잡습니다.
• 질문 → 위키 승격: v1.0의 Dynamic Q&A를 한 발 더 밀었습니다. 답변을 받고 “위키에 저장”을 누르면 정식 페이지가 됩니다. 중복 자동 감지가 있어서 비슷한 페이지가 있으면 거기에 합칩니다. 읽다가 “이거 궁금한데” 하고 드래그하는 자연스러운 행동이 그대로 위키가 되는 것 — 사실 이게 kiwimu의 핵심 아이디어입니다.
• 여기에 콘텐츠 카탈로그, 활동 로그, 위키 린트까지. 위키를 살아 있는 문서로 유지하기 위한 장치들입니다.

이 여섯 기능은 마지막 페르소나 리뷰 라운드(R15)에서 한 번에 검토했습니다. 2,779줄짜리 diff를 보안·아키텍처·코드 품질·성능 네 관점으로 훑는 라운드였습니다. 이 무렵 UX 잔손질도 많이 했습니다. 토스트·사이드바 정리, SQLITE_BUSY 경합 수정, .kiwi-token과 쿠키로 인증 토큰이 유지되게 하기, /wiki/* 링크에 미리보기 패널 붙이기 같은 것들이요. 화려하진 않지만 매일 쓰다 보면 거슬리던 것들이었습니다.

위키가 스스로 답하게 (v1.2)

v1.1까지 오니 위키는 “자라는” 상태가 됐는데, 정작 다 자란 위키에 “질문하는” 방법은 여전히 없었습니다. 페이지를 하나하나 링크 타고 찾아가야 했죠. 그래서 v1.2의 중심은 Ask-the-Wiki, 그러니까 RAG였습니다.

kiwimu index로 위키 전체를 청크로 쪼개 임베딩을 만들어 두면, kiwimu ask "질문" 또는 웹의 검색창에서 위키 전체에 자연어로 물어볼 수 있습니다. 관련 청크를 검색해서 답을 만들고, 어느 페이지에서 나온 내용인지 인용을 붙입니다. 임베딩이 없거나 실패하면 키워드 검색으로 우아하게 폴백하고요. src/services/rag.ts 한 파일(285줄)에 indexWiki·askWiki가 들어 있고, POST /api/ask-wiki는 인증과 레이트 리밋을 겁니다.

그런데 v1.2에서 개인적으로 더 기록해 두고 싶은 건, 기능 자체보다 만드는 방식이 바뀌었다는 점입니다.

v1.0까지는 “리뷰 → 수정” 라운드를 돌렸다면, v1.2는 세 개의 구현 스트림을 병렬로 띄웠습니다. Stream A는 기존 파이프라인의 특성화 테스트, Stream B는 인제스트 개편(그림·비용·증분), Stream C는 RAG. 세 에이전트가 동시에 각자 코드를 썼습니다.

그리고 여기서 아주 사람 냄새 나는 사고가 하나 있었습니다. 세 에이전트가 같은 계정을 공유하다 보니 셋이 동시에 레이트 리밋에 걸린 겁니다. 오후 3시 10분(KST) 리셋을 다 같이 기다리는 상황이 됐죠. 결국 리밋이 덜 걸린 A와 C를 먼저 머지하고(86 테스트 통과, 배포 가능 상태), B는 잡아뒀다가 다음 라운드에 마저 붙였습니다(103 테스트). AI를 병렬로 굴리면 빨라지지만, 그 병렬성이 공유 자원 하나에서 다 같이 막힐 수 있다는 걸 실제로 겪은 순간이었습니다.

그림, 비용, 그리고 다시 안 만들기

RAG 말고도 v1.2에는 인제스트를 실제로 쓸 만하게 만든 세 가지가 들어갔습니다. 셋 다 데모용이 아니라 “진짜 문서를 반복해서 넣다 보면 아쉬웠던 것”들입니다.

그림 추출. 교과서 PDF는 그림이 절반인데 그동안 텍스트만 뽑고 있었습니다. pdfimages(poppler)로 이미지를 꺼내고, 비전 모델로 캡션을 달아서 ## Figures 섹션으로 페이지에 붙입니다(<!-- figures --> 마커 기준이라 여러 번 돌려도 중복 안 됩니다). 비전을 못 쓰거나 pdfimages가 없으면 조용히 건너뜁니다.

비용 프리뷰. 큰 PDF를 넣을 때 “이거 돌리면 얼마 나오지?”가 항상 불안했습니다. 그래서 add 실행 전에 예상 토큰과 비용을 보여주고 확인을 받게 했습니다(@clack/prompts). --yes로 넘길 수 있고요. 별거 아닌데 심리적으로 큰 차이가 있습니다.

증분 재인제스트. 같은 문서를 다시 넣으면 통째로 다시 LLM을 돌리던 걸, sources.content_hash(추출 텍스트의 sha256)로 바꿔서, 내용이 그대로면 LLM 호출을 0번으로 건너뜁니다. --force로 강제할 수 있습니다. 문서 하나 고칠 때마다 전체 비용을 다시 내던 걸 없앤 거죠.

재미없지만, 진짜 중요한 일

여기까지가 “기능”의 이야기이고, 요즘 붙잡고 있는 건 그걸 남한테 진짜로 공개할 수 있게 다듬는 일입니다. 화려하지 않아서 블로그에 잘 안 쓰이는 부분인데, 시간은 여기가 제일 많이 듭니다.

7월 11일 커밋 하나가 대표적입니다. ?token=으로 인증하던 걸 쿠키를 세팅한 뒤 클린 URL로 302 리다이렉트하게 바꿨고(토큰이 Referer나 히스토리에 남지 않도록), 토큰 비교를 crypto.timingSafeEqual로 교체하고, SSRF 필터(validateUrl)가 IPv6 루프백·ULA·링크로컬, IPv4 매핑, CGNAT, *.internal을 막고 DNS 결과까지 사설 대역이면 거부하도록 했습니다. 하드코딩돼 있던 버전 문자열을 package.json에서 읽게 고친 것도 이때입니다. 이 커밋 하나로 테스트가 112개가 됐고, 그중 9개가 새 SSRF 케이스였습니다.

그 뒤로도 CDN 의존을 없애느라 KaTeX·Mermaid·D3·폰트를 전부 셀프호스팅으로 내리고, 문서마다 SHA-256으로 스크립트를 고정하는 엄격한 CSP를 걸고, Mermaid는 아예 sandbox="allow-scripts" 격리 프레임 안에 가뒀습니다. 여러 인스턴스가 같은 SQLite를 건드릴 때를 대비해 Redis/Valkey 기반 코디네이터(Lua 원자 연산)와 리스 펜싱도 붙였고요. 서버 라우팅은 1,139줄에서 258줄로 쪼갰습니다. 접근성은 axe·키보드·reduced-motion·forced-colors 자동 게이트까지는 걸었는데, VoiceOver/NVDA 수동 검증은 아직 체크리스트에 “미검사”로 남아 있습니다. 정직하게 적자면 이게 지금 상태입니다.

이 과정을 거치며 테스트는 122 → 176 → 204개로 늘었고, 지금은 27개 파일에 212개가 돌고 있습니다. 숫자 자체가 목표는 아니지만, 처음 R01에서 0개였던 걸 생각하면 나름의 궤적입니다.

숫자로 보는 넉 달

주요 기능을 시간순으로 늘어놓으면 이렇습니다. 학습 퀴즈 + SM-2 간격 반복, Dynamic Q&A, 웹 편집, 학습 대시보드, LaTeX/Mermaid 렌더링(v1.0) → 출처 추적, 스키마 레이어, 질문→위키 승격, 카탈로그·활동 로그·린트, 미리보기 패널(v1.1) → Ask-the-Wiki(RAG), 그림 추출, 비용 프리뷰, 증분 재인제스트(v1.2).

마치며

넉 달을 돌아보면, 기억에 남는 건 기능이 아니라 몇 개의 순간입니다.

네 명이 각자 인증 문제를 짚었을 때. 여덟 라운드가 멀쩡하다던 코드를 EdTech가 F로 채점했을 때. 열 라운드가 못 본 버그를 DBA가 첫 리뷰에서 찾았을 때. 전부 “같은 코드를 다른 눈으로 봤더니 다른 게 보였다”는 이야기입니다. 혼자 하는 개발에서 제일 아쉬운 게 바로 그 다른 눈인데, AI 페르소나가 그걸 꽤 그럴듯하게 채워줬습니다.

동시에, AI를 병렬로 굴린다고 다 빨라지는 것도 아니었습니다. v1.2에서 세 에이전트가 같은 계정 하나에서 다 같이 막힌 것처럼, 병렬성은 어딘가의 공유 자원에서 결국 병목을 만납니다. 그리고 알리는 일(v1.1)이나 공개를 준비하는 일(지금)처럼, AI가 대신해 주기 애매한 부분에서는 여전히 사람이 손이 많이 갑니다.

그래도 확실한 건, “전공책은 안 읽히는데 나무위키는 하루 종일 읽을 수 있잖아”라는 한 문장이 실제로 돌아가는 도구가 됐다는 겁니다. 문서를 넣으면 위키가 되고, 읽다가 궁금하면 그 자리에서 물어보고, 그 질문이 다시 위키가 되고, 이제는 위키 전체에 되물을 수도 있습니다. 완성됐다고는 못 하겠습니다. 접근성 수동 검증도 남았고, 공개 릴리스도 아직입니다. 하지만 아이디어 한 줄에서 여기까지 온 궤적만큼은, 남겨둘 만하다고 생각했습니다.

kiwimu는 npm에서 설치할 수 있고, bunx @open330/kiwimu init --demo로 30초 만에 체험할 수 있습니다. GitHub에 소스가 있습니다.