LLM 위키 구축 안내 — 하네스 다음 단계

대상: Claude Code 데스크탑 앱을 설치하고 기본 CLAUDE.md(하네스)까지 채운 분. 앞 단계 안내: 클로드코드 데스크탑앱 안내 왜 이렇게 하는지, 배경 이야기: AI가-내-생각을-쓰게-하는-법

1. LLM 위키가 왜 필요한가

CLAUDE.md에 규칙을 쌓다 보면 금방 한계가 옵니다.

파일이 길어질수록 매 대화마다 그 전체를 읽는 비용(토큰)이 커지고,
규칙이 많아질수록 AI가 정작 중요한 원칙을 놓치기 시작합니다.

해법은 문서를 위키처럼 계층화하는 것입니다. AI 연구자 안드레 카파시(Andrej Karpathy)가 제안한 패턴으로, “AI가 항상 읽는 것”과 “필요할 때만 찾아 읽는 것”을 분리합니다. 품앗이에서 실제 적용해 보니 매 세션 자동 로드되는 분량이 절반으로 줄었습니다.

2. 3계층 구조

계층	무엇	로드 시점	예
L1 코어	원칙·금지선·단축명령·L2 포인터만	매 세션 자동	`~/.claude/CLAUDE.md` (60줄 안팎 유지)
L2 상세	주제별 상세 문서	AI가 필요할 때 찾아 읽음	코딩 규칙, 환경 설명, 팀 구조 등 별도 파일
L3 기록	개별 기억·레슨 파일	명시적으로 찾을 때만	메모리 파일 수십~수백 개 + 인덱스

핵심 규칙은 하나입니다: L1에는 “무엇을 어디서 찾는지”만 남기고, 내용 자체는 아래 계층으로 내린다.

3. 구축 순서 (하네스가 이미 있다는 전제)

① CLAUDE.md 다이어트 (L1 만들기)

지금 CLAUDE.md를 열어 항목마다 물어보세요 — “이게 매 대화마다 필요한가?”

남길 것: 절대 금지선, 핵심 원칙, 자주 쓰는 단축 명령, 그리고 상세 문서로 가는 포인터(한 줄 링크)
내릴 것: 코딩 스타일 상세, 도구 사용법, 프로젝트별 설명 — 각각 별도 파일로

## L2 참조 (필요시 읽기)
- 코딩 시: `docs/coding-rules.md`
- 배포 시: `docs/deploy.md`

이렇게 포인터만 남기면 AI가 코딩할 때만 coding-rules.md를 읽으러 갑니다.

② 주제별 상세 파일 분리 (L2)

내린 내용을 주제 단위 파일로 만듭니다. 파일 하나 = 주제 하나. 위치는 자유지만 한 폴더에 모으세요 (예: ~/.claude/detail/ 또는 프로젝트의 docs/).

③ 메모리 인덱스 (L3)

AI가 대화에서 알게 된 사실들(내 취향, 프로젝트 사정, 실수에서 배운 것)을 파일 하나에 사실 하나로 저장하게 하고, 인덱스 파일(MEMORY.md)에는 한 줄 요약 + 링크만 씁니다.

# Memory Index
- [백업 규칙](backup-rules.md) — 삭제 전 반드시 백업
- [내 문체 취향](writing-style.md) — 번역투 금지

인덱스의 철칙: 어디를 볼지만 가리킨다. 수치·값·경로 같은 내용은 개별 파일에. 인덱스에 내용을 쓰기 시작하면 인덱스가 다시 비대해집니다.

④ 레슨 습관 만들기

삽질하고 해결할 때마다 AI에게 “이거 레슨으로 저장해”라고 시키세요. 레슨 파일 + 인덱스 한 줄이 쌓이면, 같은 삽질을 다음 세션이 반복하지 않습니다. “배웠다”는 말이 나올 때마다 저장하는 걸 규칙(L1)에 박아두면 습관이 됩니다.

4. 옵시디언 설치 — 위키를 눈으로 보는 창

AI는 위키를 마크다운 파일로 읽고 쓰지만, 사람에게는 그걸 훑어볼 창이 필요합니다. 옵시디언(Obsidian) 이 그 창입니다 — 같은 폴더를 AI와 사람이 공유하는 구조입니다.

obsidian.md에서 내려받아 설치합니다 (개인 사용 무료, Windows/macOS/Linux).
첫 화면에서 “폴더를 볼트로 열기(Open folder as vault)” 를 누르고, 아래 5절에서 만들 wiki/ 폴더를 선택합니다.
이제 AI가 파일을 만들면 옵시디언에 바로 나타납니다. [[링크]]를 클릭해 노드 사이를 이동하고, 그래프 뷰(왼쪽 아이콘)로 지식이 연결되는 모양을 봅니다.

역할 분담: 쓰는 건 주로 AI, 읽고 다듬는 건 사람. 옵시디언에서 직접 고쳐도 됩니다 — 같은 파일이니 AI가 다음 대화에서 그대로 읽습니다.

5. AI와 함께 위키 만들기 — 붙여넣는 지시문 (품앗이 위키 모델)

아래 지시문을 자기 Claude Code에 그대로 붙여넣으세요. 품앗이에서 실제 운영하는 위키 관례를 그대로 옮긴 것입니다.

지금부터 내 LLM 위키를 만들자. 다음 규칙을 따른다.

1. 내 홈 폴더에 `wiki/` 폴더를 만들어라. (내가 옵시디언 볼트로 열 폴더다)

2. 노드 규칙 — 파일 하나 = 주제 하나:
   - 파일명은 한글 서술형으로 (예: "백업 규칙.md", "글쓰기 문체.md")
   - 파일 맨 위에 frontmatter를 넣어라:
     ---
     title: 노드 제목
     description: 한 줄 요약
     tags: [분류]
     최종수정: 날짜
     ---
   - 관련 노드끼리는 본문에서 [[파일명]] 위키링크로 연결해라

3. `wiki/index.md`를 만들어라 — 전체 인덱스다.
   - 노드마다 "- [[노드명]] — 한 줄 훅" 형식으로 딱 한 줄만
   - 인덱스에는 내용을 쓰지 마라. 어디를 볼지만 가리킨다
   - 주제가 늘어 대분류가 생기면 폴더로 나누고 인덱스에 섹션(##)으로 반영해라

4. 앞으로 내가 "위키에 정리해"라고 하면:
   - 해당 주제 노드를 만들거나 갱신하고, index.md의 한 줄도 같이 갱신해라
   - 이미 있는 주제면 새 파일을 만들지 말고 그 노드를 고쳐라 (중복 금지)
   - 사실이 바뀌면 본문과 인덱스를 반드시 같이 고쳐라

첫 작업: 지금 CLAUDE.md에서 상세(L2)로 내리기로 한 내용을 위키 노드로
옮기고, index.md를 만들어서 보여줘라.

이 지시문 자체를 CLAUDE.md(L1)에 “위키 규칙: wiki/규칙.md 참조” 식으로 노드화해 두면, 매 세션 다시 설명할 필요가 없습니다.

6. 운영 원칙 다섯 가지

중복 금지 — 같은 사실이 두 파일에 있으면 하나는 반드시 낡습니다. 정본 하나 + 링크.
정정은 인덱스까지 — 사실이 바뀌면 본문만 고치지 말고 인덱스 한 줄도 같이. 인덱스가 옛 정보를 계속 뿌리는 게 흔한 사고입니다.
자주 어기는 규칙은 문서 말고 장치로 — 세 번 이상 반복되는 실수는 규칙을 더 쓰는 게 아니라 훅(hook)·스크립트로 막는 겁니다.
L1은 늘리지 말고 지켜라 — 새 규칙이 생기면 먼저 “L2로 내릴 수 없나”를 묻습니다. L1 비대화가 이 구조의 제1 실패 원인입니다.
백업 먼저 — 구조 개편 전에 기존 CLAUDE.md를 복사해 두세요. 며칠 써보고 AI가 원칙을 놓치면 되돌려 보강합니다.

7. 잘 됐는지 확인하는 법

새 세션을 열고 L2 주제 질문을 해봅니다 — AI가 해당 파일을 읽으러 가는지 확인.
지난주에 저장한 레슨과 같은 상황을 만들어봅니다 — 같은 실수를 반복하는지.
매 세션 자동 로드 분량(CLAUDE.md 글자 수)을 개편 전후로 비교해 봅니다.

다음 단계 예고: 위키가 쌓이면 이를 팀·조직과 공유하는 공개 위키(퍼블리싱)로 확장할 수 있습니다.

품앗이 위키

탐색기

LLM 위키 구축 안내