1. 이게 뭐고 왜 쓰나
RAG와 다르다. RAG는 질문마다 문서를 재검색 — 지식이 안 쌓인다. LLM Wiki는 소스를 넣을 때 한 번 컴파일해서 영속 위키로 만들고 계속 최신화한다. 교차참조·모순표시·종합이 이미 걸려 있는 복리형 산출물.
역할 분담
사람: 소스 큐레이션(회의록·메일·기사 넣기), 질문, 탐색 방향
LLM: 요약·교차링크·신뢰도 계산·정리·부기 — 한 번에 15개 파일 갱신, 지치지 않음
실제 효용 (우리 팀 사용 사례)
회의록을 넣으면 → 결정사항이 개념 페이지로 승격되고, 관련 과거 회의·메일과 자동 연결
"이번주 뭐 했나" 물으면 → 흩어진 데일리·회의·메일을 종합해 신뢰도 붙여 답
며칠 지나면 → 오래된 정보를 자동 식별(망각), 3번 이상 반복된 사실은 신뢰도 상승
2. Obsidian 설치·설정
LLM Wiki는 폴더 안의 마크다운 파일이라 Obsidian 없이도(Claude Code만으로) 돌아간다. 하지만 Obsidian으로 열면 위키를 사람이 브라우징하고 그래프로 볼 수 있어 강력히 권장한다.
2-1. Obsidian 설치
obsidian.md에서 다운로드 (Windows/macOS/Linux 무료).
설치 후 실행 → Open folder as vault → 하네스를 clone한 폴더(my-wiki)를 선택.
2-2. 필수 코어 설정 (Settings ⚙️)
LLM Wiki가 wikilink·계층 구조에 의존하므로 아래를 맞춘다.
설정 위치 | 값 | 이유 |
|---|
Files & Links → New link format | Shortest path when possible | [[파일명]]만으로 링크 (경로 불필요) |
Files & Links → Use Wikilinks | ON | 위키 전체가 [[ ]] 문법 |
Files & Links → Default location for new notes | raw/notes/ 또는 지정 폴더 | 새 노트가 아무데나 안 생기게 |
Files & Links → Detect all file extensions | ON | md 외 파일도 보임 |
Editor → Readable line length | 취향 | 긴 문서 가독성 |
Appearance → Theme | 취향 | — |
2-3. 권장 코어 플러그인 (내장, 켜기만)
Settings → Core plugins:
Templates — 회의록·데일리·메일 템플릿 삽입 (필수)
Daily notes — 하루 노트 자동 생성
Graph view — 위키 연결 구조 시각화 (LLM이 만든 링크망을 눈으로 확인)
Backlinks / Outgoing links — 페이지 간 참조 추적
Command palette / Quick switcher — 빠른 이동
2-4. 유용한 커뮤니티 플러그인 (선택)
Settings → Community plugins → Browse:
Agent Client ⭐ — Obsidian 안에서 Claude Code와 대화(핵심 연동, → 2-5에서 상세). ACP 어댑터 선행 설치 필요.
Templater — 템플릿에 {{date}}·{{time}} 자동 치환 (meeting·email 템플릿이 이 문법 사용)
Obsidian Web Clipper (브라우저 확장) — 웹 기사를 마크다운으로 raw/article/에 바로 저장 → 인제스트
Table Exporter — 위키 표를 Excel/CSV로 내보내기 (보고용)
Marp Slides 또는 Pandoc — 노트를 PPT/문서로 변환 (발표·보고)
주의: 커뮤니티 플러그인은 처음에 "Restricted mode(제한 모드)"로 꺼져 있다. Settings → Community plugins → 제한 모드 활성화 해제 후 설치.
Settings → 커뮤니티 플러그인 화면. 제한 모드 해제 후 "탐색"으로 설치. (이 볼트는 Agent Client 1개 설치된 상태)
2-5. Agent Client 플러그인 — Obsidian 안에서 AI 대화 (권장 방식)
별도 터미널을 오가지 않고 Obsidian 안에서 바로 Claude Code와 대화하려면 커뮤니티 플러그인 Agent Client를 쓴다. 이 볼트도 이 방식으로 운영한다.
핵심 전제 — ACP 어댑터 필수. Agent Client는 ACP(Agent Client Protocol, Zed 제정) 위에서 동작한다. 플러그인만 깔면 안 되고, 에이전트(Claude Code)와 그 ACP 어댑터를 먼저 설치해야 연동된다. ACP 어댑터가 Obsidian ↔ Claude Code 사이 통신을 중계한다.
① 플러그인 설치 — Settings → Community plugins → Browse → "Agent Client" 검색 → Install → Enable.
② 에이전트 + ACP 어댑터 설치 (터미널: macOS/Linux는 Terminal, Windows는 PowerShell)
# Claude Code 설치 (이미 있으면 생략)
curl -fsSL https://claude.ai/install.sh | bash
# ★ ACP 어댑터 설치 — 이게 없으면 Agent Client가 연결 안 됨
npm install -g @agentclientprotocol/claude-agent-acp
③ 로그인 (API 키 대신 CLI 인증 쓸 때)
claude # 프롬프트 따라 Anthropic 계정 인증
④ 경로 확인 — 설정에 넣을 절대경로를 찾는다
which node # macOS/Linux
which claude-agent-acp
# Windows: where.exe node / where.exe claude-agent-acp
⑤ 플러그인 설정 — Settings → Agent Client
Node.js path — ④의 node 경로 (예: /usr/local/bin/node)
Built-in agents → Claude Code → Path — ④의 claude-agent-acp 경로 (⚠️ claude가 아니라 claude-agent-acp)
API key — CLI 로그인했으면 비워둠, 아니면 키 입력
⑥ 사용 — 리본의 로봇 아이콘 클릭 → 채팅 시작.
Agent Client가 주는 것
@노트명 멘션 — 채팅에서 볼트 노트를 직접 참조 (이 가이드 사례들이 다 이 방식)
이미지 첨부 — 붙여넣기·드래그 (회의 화이트보드 사진 등)
슬래시 명령 — 에이전트 / 명령 (/graphify 등 스킬 호출)
멀티 에이전트·멀티 세션 — Claude Code·Codex·Gemini 전환, 여러 세션 동시
세션 히스토리·채팅 내보내기 — 대화 재개·포크, 마크다운으로 저장
MCP 지원 — 에이전트에 설정된 MCP 서버를 그대로 사용(플러그인 추가 설정 불필요)
사전 릴리스를 쓰려면 BRAT 플러그인으로 https://github.com/RAIT-09/obsidian-agent-client 추가. 수동 설치는 Releases의 main.js·manifest.json·styles.css를 .obsidian/plugins/agent-client/에 넣고 Enable.
2-6. 대안 — 터미널·IDE에서 Claude Code 실행
Agent Client 없이 쓸 수도 있다. 위키 유지보수 로직은 동일.
Claude Code를 볼트 폴더에서 실행: cd my-wiki && claude
볼트 폴더를 IDE(VS Code 등)로 열면 Claude Code IDE 확장으로 편함.
이 경우 Obsidian은 브라우징 전용으로 나란히 띄워 쓴다.
3. 하네스 받기·설치
3-1. 하네스 repo
https://github.com/cookyman74/llmwiki-harness
받는 건 구조·스킬·스크립트만 — 남의 콘텐츠는 안 딸려온다(콘텐츠·개인 프로필은 .gitignore).
3-2. 사전 요구사항
Claude Code (CLI/데스크톱/IDE 아무거나)
python3 (스크립트·훅용 — 표준 라이브러리만, 별도 패키지 불필요)
Obsidian (2장 — 브라우징용, 권장)
git
크로스플랫폼: macOS·Linux·Windows 네이티브 전부 작동. python3만 PATH에 있으면 됨(WSL 불필요).
3-3. 설치 4스텝
git clone https://github.com/cookyman74/llmwiki-harness my-wiki && cd my-wiki
개인 프로필 — CLAUDE.local.md 생성 (gitignore라 공유 안 됨). Claude가 세션마다 읽어 설명 톤·깊이를 맞춘다.
# CLAUDE.local.md
## 목적 / 사용자 프로필
- 역할: (백엔드 / 데이터 / 기획 …)
- 스택: (언어·프레임워크·인프라)
- 관심/학습: (현재 파고드는 주제)
시드 복사 — 빈 색인·로그·현관 지도를 제자리로:
cp templates/seeds/index.md templates/seeds/log.md .
cp templates/seeds/home-moc.md wiki/moc/
활성화 — Claude Code 실행 → /hooks 한 번 열기(훅 로드) → Obsidian에서 볼트 열기.
첫 소스 — raw/에 파일 하나 넣고 "인제스트해줘" → 위키가 자라기 시작.
업데이트: git pull — 하네스만 갱신, 내 콘텐츠·프로필은 그대로.
4. 폴더 구조 (핵심만)
├── raw/ # 원본 소스 — 내가 넣는 곳. 본문 수정 금지(진실의 원천)
│ ├── meetings/ # 회의록
│ ├── notes/ # 데일리 노트
│ └── mail/·article/ …
├── wiki/ # LLM 소유 — 나는 읽기만
│ ├── L2-episodic/ # 소스 증거 (source-*.md)
│ ├── L3-semantic/ # 사실·개념·엔티티 (신뢰도 붙음)
│ ├── L4-procedural/ # 반복된 절차
│ └── moc/ # 주제 지도 (home-moc = 현관)
├── templates/ # 회의록·데일리·메일 템플릿
├── index.md # 전체 카탈로그 (자동)
├── log.md # 시간순 로그 (자동)
└── CLAUDE.md # 규약 정본 (건드릴 일 거의 없음)
기억할 것 2개:
5. 문서 작성·관리법
LLM이 정리를 잘하려면 넣는 문서를 어디에·어떻게 두느냐가 중요하다.
5-1. 어디에 넣나 (raw/ 분류)
소스 성격대로 raw/ 하위에 넣는다. 폴더는 자유 — 아래는 우리 팀 관례.
폴더 | 넣는 것 | 소스 유형(신뢰도 영향) |
|---|
raw/meetings/ | 회의록·미팅 속기 | verbal (−0.1, 구두정보) |
raw/notes/ | 데일리 노트 | session (스크래치, pending 스캔 제외) |
raw/mail/ | 메일 스레드·공지 | normal |
raw/article/ | 웹 기사·블로그·기술문서 | normal (공식문서면 +0.1) |
raw/manual/ | 공식 문서·매뉴얼 | official (+0.1) |
raw/working/ | 진행 중 작업 문서(정의서·기획서 초안) | normal |
유형이 신뢰도를 바꾼다: 같은 사실도 공식문서 근거면 +0.1, 회의 구두면 −0.1. LLM이 폴더·내용으로 자동 판별.
5-2. 파일명 규칙
본문 한국어 / 파일명 자유 — 회의록·데일리는 YYYY-MM-DD 날짜 프리픽스 권장.
<, >, 이중 마침표 피하기 — Obsidian이 를 HTML로 삼켜 링크가 깨진다. 제목에 필요하면 Re로.
wiki/ 안 파일은 LLM이 영문 kebab-case로 만든다(concept-ax-work-process.md) — 손대지 말 것.
5-3. 넣기 전 정리 (선택이지만 권장)
날것 그대로 넣어도 되지만, 회의록은 한 번 정리 요청하면 품질이 확 오른다.
raw/meetings/ 에 속기 붙여넣고
→ "논의·결정 구조화하고 액션 뽑아줘"
→ LLM이 결정사항 번호화 + 담당·기한 + 확인필요 분리 (원문 속기는 하단 보존)
→ "인제스트해줘"
5-4. 웹 기사·문서는 Web Clipper로 (수집 자동화)
기사·블로그·기술문서·공식문서를 복붙하지 말고 Obsidian Web Clipper(브라우저 확장)로 바로 볼트에 저장한다. 마크다운으로 깔끔하게 들어오고, 출처 URL·제목·날짜가 프론트매터로 자동 기록돼 인제스트 품질이 오른다.
설치·설정
브라우저 확장 설치 — Chrome/Edge/Firefox 스토어에서 "Obsidian Web Clipper" (공식).
확장 설정 → Vault = 내 볼트, 기본 저장 폴더 = raw/article/(또는 성격별 raw/manual/).
(선택) 템플릿 설정 — 클리핑 시 source(URL)·author·published·tags: [clippings] 프론트매터 자동 삽입.
워크플로우
① 웹에서 기사 열기 → Web Clipper 아이콘 클릭 → 본문만 마크다운 추출 → raw/article/ 저장
② Claude Code에서 "방금 클리핑한 기사 인제스트해줘"
③ LLM이 소스 유형 판별(공식문서면 신뢰도 +0.1) + 기존 개념과 자동 연결
실제 사례
웹 기사 클리핑 → 인제스트 시 프론트매터의 source URL이 그대로 L2 증거 페이지 source_url이 됨(출처 추적 자동).
tags: [clippings]가 붙어 있어 "클리핑한 것 중 미인제스트 뭐 있나" 조회가 쉬움.
긴 기사는 클리핑 후 "핵심만 요약하고 우리 위키 개념과 뭐가 연결되는지 알려줘"로 먼저 훑고 인제스트 여부 판단.
팁: 클리핑 본문도 raw/ 규칙 그대로 — 본문 immutable. 클리퍼가 가끔 광고·내비 잔여를 섞는데, 지우지 말고 인제스트 시 LLM이 본문만 골라 쓰게 둔다(원본 보존).
5-5. 템플릿으로 시작 (일관성)
templates/의 골격으로 시작하면 LLM이 파싱하기 좋다.
meeting.md — 안건·논의·결정·액션. 회의 시작할 때 삽입.
daily.md — 할일·한일·메모. Daily notes 플러그인이 자동 적용.
email.md — 수신자·발신·날짜 프론트매터 + 서명. 메일 초안·발송 기록용.
5-6. 절대 하지 말 것
❌ wiki/ 안 파일 직접 수정 — LLM 소유. 고칠 게 있으면 "이 페이지 이렇게 고쳐줘"로 요청.
❌ raw/ 원본 본문 수정 — 진실의 원천. 오타도 그대로 두고 정리본(wiki)에서 교정됨.
❌ 파일 이름·위치 임의 변경 — wikilink 깨짐. 옮길 땐 "이 파일 옮겨줘"로(LLM이 링크까지 갱신).
5-7. 관리 리듬
인제스트 즉시 — 회의·메일 오면 그날 넣기(밀리면 맥락 잊음).
주 1회 린트 — 신뢰도 재계산·모순 검사·병합.
세션 종료 시 압축 — "마무리하자"로 L1 관찰을 L2에 저장.
index·log는 자동 — 손대지 않는다.
6. 사용법 — 자연어로 요청하면 끝
모든 작업 진입점은 wiki-ops. 위키 관련 요청을 하면 자동으로 알맞은 전문가로 라우팅된다. 명령어 외울 필요 없이 한국어로 말하면 된다.
6-1. 인제스트 — "이거 위키에 넣어줘"
raw/meetings/ 에 회의록 넣고 → "인제스트해줘"
LLM: 소스 읽고 → 증거 페이지(claim 나열) + 신규 개념 초안 생성 → index·log 갱신 → 원본에 완료 스탬프.
싸고 빠름(lazy). 병합·신뢰도 계산은 나중 lint에서 배치로.
6-2. 질의 — "위키에 물어봐"
"이번주 AX 관련해서 뭐 했는지 종합해줘"
"vault-mcp 지금 신뢰도랑 진행상황 알려줘"
LLM: 관련 페이지 찾아 → 신뢰도·출처 병기해 답 → stale(낡은) 정보는 주근거로 안 씀 → 좋은 답은 위키에 환류 제안.
6-3. 린트 — "위키 점검해줘"
"위키 린트" (또는 SessionStart 훅이 "3일+ 경과" 알릴 때)
LLM: 끊긴 링크·고아·망각 검사 → 신뢰도 재계산 → 반복 사실 승격 → 모순·누락 찾아 수리목록. 자동 삭제 안 함, 제안만.
6-4. MoC — "네비게이션 정리해줘"
주제 지도 생성·갱신, 모든 페이지가 지도에서 도달 가능한지 점검(고아 방지).
6-5. 세션 종료 — "마무리하자 / L1 압축"
현재 세션 관찰을 3~5줄로 압축해 일화기억(L2)에 저장.
▶ 원문 출처: https://github.com/cookyman74/llmwiki-harness
