claude-obsidian 소개
개인 자료를 모아두는 Obsidian 같은 노트 앱은 시간이 지날수록 정리가 어려워집니다. 자료를 모으는 속도는 빠른데, 새 글이 들어왔을 때 기존 페이지와 어떻게 연결되는지를 사람이 직접 관리해야 하고, 며칠만 지나도 어떤 문서가 어디 있었는지 잊어버리기 쉽습니다. claude-obsidian은 이 문제를 지속적으로 누적되는 자동 정리형 위키(persistent, compounding wiki vault) 라는 접근으로 풀려는 오픈소스 프로젝트입니다. Obsidian 볼트(vault) 위에서 Claude Code가 실제 운영자로 동작하며, 새로 추가되는 자료를 읽고, 엔티티와 개념을 추출하고, 교차 참조를 갱신하며, 페이지를 새로 만들거나 수정합니다.
claude-obsidian의 설계는 Andrej Karpathy가 제안한 LLM Wiki pattern 을 기반으로 합니다. 핵심 아이디어는 단순합니다. AI가 답을 즉석에서 만들어내는 대신, 사용자가 누적한 자료에서 직접 인용해 답하도록 만드는 것입니다. Claude는 인덱스, 도메인 서브 인덱스, 그리고 개별 위키 페이지를 단계적으로 읽어 답을 합성하고, 그 결과를 학습 데이터가 아닌 사용자의 위키 페이지(specific wiki pages) 로 인용합니다. 모든 세션이 끝날 때마다 hot cache 파일이 갱신되어 다음 세션의 출발점이 되기 때문에, 대화를 다시 시작하더라도 최근 맥락을 처음부터 설명할 필요가 없습니다.
claude-obsidian은 MIT 라이선스로 공개된 Claude Code 플러그인이자 Obsidian 볼트 템플릿으로, README 기준 11개의 스킬(skills)을 갖추고 있습니다. 본 게시물에서는 claude-obsidian이 노트 관리에 접근하는 방식, 핵심 명령과 모드, 그리고 설치하여 자신의 자료로 위키를 시작하는 방법을 살펴봅니다.
claude-obsidian의 동작 방식
claude-obsidian이 노트를 다루는 사이클은 크게 네 단계로 구성됩니다. 자료 수집, 위키 갱신, 질의 응답, 그리고 위키 점검입니다.
자료를 던지면 Claude가 그 자료를 읽고, 엔티티(entities)와 개념(concepts)을 추출해 위키 페이지를 8~15개 정도 생성하거나 갱신합니다. 그 과정에서 기존 페이지와의 교차 참조가 함께 업데이트되어, 새 자료가 들어올수록 위키 그래프가 더 촘촘해지는 효과가 생깁니다. 질문을 던지면 Claude는 hot cache(최근 맥락 캐시)와 인덱스를 먼저 읽고, 관련 페이지를 좁혀 들어가서 답을 합성한 뒤 구체적인 위키 페이지를 인용합니다.
위키가 커지면 자연스럽게 끊긴 링크나 사용되지 않는 페이지(orphan), 오래된 주장이 쌓이는데, claude-obsidian의 lint 모드가 이를 8개 카테고리로 점검합니다. README는 이를 orphans, dead links, gaps, suggestions 같은 항목으로 표현합니다. 마지막으로 모든 세션 종료 시점에 Claude는 hot cache를 갱신해 다음 세션 시작 시 자동으로 최근 맥락을 불러올 수 있게 만듭니다.
claude-obsidian의 주요 명령
claude-obsidian은 Claude Code 슬래시 명령과 자연어 명령의 조합으로 조작합니다. README에 정의된 핵심 명령은 다음과 같습니다. 모든 명령은 Obsidian 볼트와 같은 디렉토리에서 Claude Code를 실행했을 때 동작합니다.
/wiki: 셋업 점검, 새 볼트의 스캐폴딩, 또는 이전 세션 이어가기를 처리합니다.ingest [file]: 단일 자료를 읽어 8~15개의 위키 페이지를 만들고 인덱스와 로그를 갱신합니다.ingest all of these: 여러 자료를 일괄 처리한 뒤 교차 참조를 갱신합니다.what do you know about X?: 인덱스에서 관련 페이지를 찾아 답을 합성합니다./save: 진행 중인 대화를 위키 노트로 저장합니다./save [name]으로 제목을 직접 지정할 수도 있습니다./autoresearch [topic]: 자율 연구 루프(autonomous research loop)를 실행합니다. 검색, 문서 가져오기, 합성, 파일링까지 한 흐름으로 수행합니다./canvas: 시각 캔버스(Visual canvas)를 열어 이미지, PDF, 위키 페이지를 카드로 배치합니다.add image,add pdf,add note같은 서브 명령으로 콘텐츠를 추가합니다.lint the wiki: 위키 건강 점검(orphans, dead links, gaps, 보강 제안)을 수행합니다.update hot cache: 최근 맥락 요약을 담은hot.md를 갱신합니다.
claude-obsidian의 여섯 가지 위키 모드
claude-obsidian은 자료의 종류에 따라 위키 구조를 다르게 잡을 수 있도록 Six Wiki Modes 를 정의합니다. 모드는 조합해서 사용할 수도 있습니다.
| Mode | 적합한 시나리오 |
|---|---|
| A: Website | 사이트맵, 콘텐츠 감사, SEO 위키 |
| B: GitHub | 코드베이스 맵, 아키텍처 위키 |
| C: Business | 프로젝트 위키, 경쟁 정보 분석 |
| D: Personal | 세컨드 브레인, 목표, 저널 합성 |
| E: Research | 논문, 개념, 학위 논문 작업 |
| F: Book/Course | 챕터 추적기, 코스 노트 |
자료 한 묶음으로 위키를 처음 만들면, 시드(seed) 볼트와 결합되어 그래프 뷰에 5개 페이지의 연결된 클러스터가 나타납니다. 이후 자료를 추가할수록 그래프가 더 풍성해지는 구조입니다.
claude-obsidian 설치 및 사용법
claude-obsidian은 세 가지 설치 방식을 제공합니다. README는 가장 빠른 셋업으로 볼트 통째로 클론 하는 방식을 권장합니다.
git clone https://github.com/AgriciDaniel/claude-obsidian
cd claude-obsidian
bash bin/setup-vault.sh
setup-vault.sh 스크립트는 graph.json(그래프 필터·색상), app.json(플러그인 디렉토리 제외), appearance.json(커스텀 CSS 활성화)을 미리 구성해 주기 때문에, 처음 Obsidian에서 볼트를 열면 색상으로 분류된 파일 탐색기와 위키 구조가 그대로 준비되어 있습니다. 이후 Obsidian의 Manage Vaults → Open folder as vault 로 클론한 디렉토리를 열고, 같은 디렉토리에서 Claude Code를 실행한 뒤 /wiki 를 입력하면 첫 위키가 시작됩니다.
이미 다른 Claude Code 프로젝트에서 작업 중이라면, 해당 프로젝트의 CLAUDE.md 에 다음과 같은 블록을 추가해 위키를 별도 지식 베이스 로 연결할 수 있습니다.
## Wiki Knowledge Base
Path: ~/path/to/vault
When you need context not already in this project:
1. Read wiki/hot.md first (recent context cache)
2. If not enough, read wiki/index.md
3. If you need domain details, read the relevant domain sub-index
4. Only then drill into specific wiki pages
Do NOT read the wiki for general coding questions or tasks unrelated to [domain].
이렇게 하면 코딩 프로젝트, 콘텐츠 워크플로우, 그리고 일상 개인 어시스턴트가 같은 위키 볼트를 공유할 수 있습니다. 추가로 MCP(Model Context Protocol) 설정을 하면 Claude가 복사·붙여넣기 없이 직접 볼트 노트를 읽고 쓸 수 있는데, README는 Obsidian의 Local REST API 플러그인 기반 옵션을 안내합니다.
claude-obsidian 라이선스
claude-obsidian은 MIT 라이선스로 공개되어 있어, 개인 및 상업적 용도로 자유롭게 사용·수정·재배포할 수 있습니다. 다만 함께 사용하는 Obsidian 자체와 Claude Code, 그리고 Claude 모델은 각각의 약관과 가격 정책을 따르므로, 민감한 자료를 ingest하기 전에 어떤 모델에 어떤 자료가 전달되는지 확인해두는 것이 좋습니다.
claude-obsidian 공식 블로그 글
claude-obsidian 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 