CLAUDE.md는 이미 LLM Wiki였다 — 모노레포 개발자가 본 Karpathy 방법론

4월 초, Karpathy가 X에 "LLM Knowledge Bases"라는 글을 올렸습니다. 1주일 만에 1,600만 조회를 넘기고, GitHub Gist에는 5,000개 넘는 스타가 붙었습니다. "토큰 처리량이 코드 조작에서 지식 조작으로 이동 중"이라는 선언과 함께요.

핵심은 이렇습니다. 원시 자료(raw/)를 LLM이 구조화된 위키(wiki/)로 컴파일하고, 최상위에 스키마(CLAUDE.md)를 두는 3계층 구조. RAG처럼 매번 검색하는 게 아니라, 한 번 구조화해서 지식을 누적하는 "컴파일 타임" 접근입니다. 벡터 DB도, 임베딩 파이프라인도 필요 없이 마크다운 파일시스템만으로 동작한다는 점이 반향을 일으켰습니다. 기존 RAG의 대안으로 주목받은 이유입니다.

사실 Karpathy의 원래 맥락은 연구 자료 정리였습니다. 본인이 직접 "토큰 사용이 코드 조작에서 지식 조작으로 이동 중"이라고 했고, 예시도 논문 정리, 개인 일기 위키화 같은 비코드 영역이었습니다. 그런데 개발자 커뮤니티에서 폭발적으로 반응한 건, 이 패턴이 개발 환경의 지식 관리와 묘하게 겹쳐 보였기 때문입니다. 스키마 파일 이름이 CLAUDE.md인 것부터가 그랬습니다.

Claude Code와 CLAUDE.md로 프로젝트 지식을 관리해온 입장에서, 저도 같은 반응이었습니다. "이거 내가 이미 하고 있는 거 아닌가?" 그래서 실제로 대입해봤습니다. 코드 개발 환경에 맞는지, 안 맞는다면 어디가 안 맞는지, 그래도 가져올 건 있는지.

LLM Knowledge Base를 모노레포에 대입해본 1:1 매핑

저는 NestJS + Next.js 기반의 모노레포를 운영하고 있습니다. 7개 패키지, MongoDB와 MySQL 이중 DB, Coolify 배포. 이 환경에서 Claude Code를 메인 도구로 쓰면서, 프로젝트 지식을 관리하기 위해 쌓아온 것들이 있습니다.

Karpathy의 구성요소를 하나씩 현재 환경에 대입해봤습니다.

Karpathy 구성요소	내 모노레포	상태
raw/ (원시 소스)	코드 자체 + git history	코드가 곧 소스
wiki/ (구조화된 위키)	CLAUDE.md 9개, 2,962줄	이미 존재
CLAUDE.md (스키마)	루트 CLAUDE.md + 스킬 정의	이미 존재
Ingest (입수)	CLAUDE.md 수동 업데이트	수동이지만 동작
Query (질의)	Claude Code가 CLAUDE.md 읽고 응답	이미 동작
Lint (건강검사)	없음	갭
도구 스택	Claude Code + 80여 개 스킬	더 정교함

체계적으로 정리한 적은 없었습니다. 그런데 매핑표를 그려놓고 보니, 7개 중 6개가 이미 동작하고 있었습니다. 빠진 건 Lint 하나뿐이었습니다.

돌이켜 생각해보면, Claude Code와 함께 프로젝트를 진행하면서 자연스럽게 도달한 구조였습니다. CLAUDE.md를 잘 써야 Claude Code가 맥락을 이해하고, memory에 피드백을 축적해야 다음 세션에서 같은 실수를 반복하지 않는다는 걸 경험적으로 알게 된 것입니다. Karpathy의 프레임워크는 이미 실천하고 있던 것에 이름을 붙여준 셈이었습니다.

그런데 전면 도입은 맞지 않습니다

매핑이 잘 된다고 해서, LLM Knowledge Base를 그대로 가져오는 것이 좋은 선택일까요. 며칠간 생각해본 결과, 코드 개발 환경의 LLM 지식 관리에는 구조적으로 맞지 않는 지점이 세 가지 있었습니다.

코드가 곧 Source of Truth

Karpathy의 방법론은 논문, 기사, 문서 같은 불변 자료를 구조화하는 데 최적화되어 있습니다. 논문 100편을 위키로 컴파일하면, 원본이 바뀌지 않으니 위키도 유효합니다.

모노레포는 다릅니다. 코드가 매일 변합니다. API 엔드포인트가 추가되고, 스키마 필드가 바뀌고, 패키지 의존성이 갱신됩니다. 코드를 위키로 컴파일하는 순간, 다음 커밋에서 이미 stale해집니다. 원본이 계속 변하는 환경에서 중간 계층을 두는 건 유지보수 부채를 만드는 일입니다.

Git이 이미 더 나은 지식 추적

git log는 변경 이력을, git blame은 누가 왜 바꿨는지를, git diff는 차이를 보여줍니다. 정확하고, 자동이고, 무료입니다. LLM이 생성한 위키가 이 세 가지를 대체할 수는 없습니다. 오히려 Git과 위키 사이의 불일치를 관리하는 비용이 새로 생깁니다.

규모 미스매치

Karpathy가 예시로 든 규모는 약 100개 문서, 40만 단어 정도의 정적 지식입니다. 모노레포는 수백 개의 .ts 파일이 매일 변경됩니다. 정적 지식을 한 번 컴파일하는 것과, 매일 바뀌는 코드를 계속 위키로 동기화하는 것은 비용 구조가 전혀 다릅니다. 후자는 결국 자동화하더라도 ROI가 나오지 않습니다.

Karpathy 방법론에서 가져올 세 가지

전면 도입은 맞지 않지만, 매핑표에서 드러난 빠진 조각은 분명히 있었습니다. Karpathy 방법론에서 코드 개발 환경에도 유효한 아이디어 세 가지를 골라봤습니다.

Lint: 문서 건강검사

매핑표에서 유일하게 "갭"으로 표시된 항목입니다. CLAUDE.md 9개 파일, 2,962줄이 있지만, 이것이 코드 현실과 동기화되어 있는지 검증하는 메커니즘이 없습니다.

예를 들어, backend CLAUDE.md에 적힌 API 엔드포인트가 실제로 존재하는지, 포트 번호가 맞는지, 환경변수 목록이 최신인지 아무도 확인하지 않습니다. CLAUDE.md를 업데이트하는 건 수동이고, 빠뜨리기 쉽습니다. Karpathy가 말하는 Lint는 이 문제에 정확히 대응합니다. "문서가 현실과 맞는가?"를 주기적으로 검증하는 루틴. hook이나 스킬로 자동화할 수 있다는 생각이 들었습니다.

ADR: 왜의 기록

"왜 MongoDB와 MySQL을 이중으로 쓰는가?" "왜 Worker를 분리했는가?" "왜 shared-types를 별도 패키지로 뺐는가?" 이런 질문에 대한 답이 코드 어디에도 없습니다. commit 메시지에 단편적으로 흩어져 있을 뿐, 체계적으로 기록되어 있지 않습니다.

Architecture Decision Records는 Karpathy 방법론에서 말하는 "정적 지식"에 해당합니다. 한 번 내린 결정은 변하지 않으니 stale해질 위험도 없습니다. _decisions/ 같은 디렉토리에 쌓아두면, LLM이 "왜 이런 구조인가?"라는 질문에 정확히 답할 수 있게 됩니다.

삽질 로그 축적

루트 CLAUDE.md의 Troubleshooting 섹션은 4줄뿐입니다. 하지만 실제로 겪은 문제는 훨씬 많습니다. pnpm-lock 동기화 실패, Coolify 빌드 타임아웃, ESM/CJS 호환성 충돌, Atlas 연결 끊김. 이런 문제들이 기록되지 않아서 다음에 같은 문제를 만났을 때 또 삽질합니다.

memory에 삽질 로그를 축적하면, 다음 세션에서 Claude Code가 바로 참조할 수 있습니다. 이것도 "정적 지식"입니다. 한 번 해결한 문제의 원인과 해법은 변하지 않으니까요.

방법론이 아니라 빠진 조각을 채우는 것

Karpathy의 방법론을 본 뒤 "나도 전면 도입해야 하나?"라고 고민했다면, 제 결론은 이렇습니다. 먼저 자기 환경을 매핑해보세요.

Claude Code를 쓰고 있다면 CLAUDE.md가 이미 wiki/이고, 코드가 raw/이고, Claude Code 자체가 Query 엔진입니다. 80%는 이미 하고 있을 가능성이 높습니다. 필요한 건 나머지 20%에서 자기 환경에 맞는 조각만 골라 채우는 것입니다.

Karpathy의 진짜 기여는 특정 도구나 디렉토리 구조가 아니라, LLM을 지식 컴파일러로 보는 시각의 전환이라는 생각이 들었습니다. 그리고 CLAUDE.md를 쓰고 있는 개발자라면, 이미 그 시각의 일부를 실천하고 있는 것입니다.