Obsidian Vault 작업 가이드

경로 정보

$VAULT_ROOT

~/git/vault-intelligence/

markdown-oxide LSP 활용

사용 가능한 LSP 기능

markdown-oxide MCP 서버가 연결되어 있으면 다음 기능을 활용할 수 있다:

1. Go to Definition:

   [[링크]]

   → 해당 파일로 이동
2. Find References (백링크): 특정 노트를 참조하는 모든 노트 검색
3. Tag Search:

   #태그

   가 사용된 모든 위치 검색
4. Completion: 링크, 태그, 프로퍼티 자동완성
5. Diagnostics: 깨진 링크, 존재하지 않는 노트 감지

LSP 기반 검색 예시

# 백링크 찾기
"TDD 노트를 참조하는 모든 노트 찾아줘"
→ LSP find_references 사용

# 태그 검색
"#project/active 태그가 있는 노트들 찾아줘"
→ LSP find_references 사용

# 깨진 링크 확인
"이 vault에서 깨진 링크가 있는 노트 확인해줘"
→ LSP diagnostics 사용

LSP 우선 원칙

마크다운 파일 검색 시:

1. 우선: markdown-oxide LSP 도구 사용 (빠르고 정확)
2. 차선: vis CLI (시맨틱 검색 필요 시)
3. 최후: grep/ripgrep (단순 텍스트 매칭)

태그 체계

Hierarchical Tags

• 형식:

  #category/subcategory/detail

• 5가지 카테고리: Topic, Document Type, Source, Status, Project

Zettelkasten 폴더 구조

상세 가이드

• 태그:

  vault_root/vault-analysis/improved-hierarchical-tags-guide.md

vault-intelligence CLI

기본 사용법

# vis daemon 서버 실행 시 HTTP API 직접 호출 (0.4초, CLI는 9초)
curl -s --get --data-urlencode "query=검색어" "http://localhost:8741/search?search_method=hybrid&top_k=10" | jq -r '.results[] | "\(.score) \(.path)"'

# 서버 미실행 시 fallback
vis search "검색어" --search-method hybrid --top-k 10

주요 옵션

--search-method

--rerank

--expand

--top-k

자주 실수하는 옵션

--method

--search-method

--k

--top-k

--output-file

--output

--reranking

--rerank

vis search --query "TDD"

vis search "TDD"

vis collect --topic "TDD"

vis collect "TDD"

vis related --file "문서.md"

vis related "문서.md"

vis tag --target "문서.md"

vis tag "문서.md"

상세 가이드

• ~/git/vault-intelligence/CLAUDE.md

토큰 최적화 전략

작업 원칙

1. 한 번에 10개 이하 파일 처리
2. archive, .obsidian 폴더 무시
3. MOC 노트 먼저 읽고 관련 노트만 선택적 로드
4. 20회 반복 후

   /compact

   또는

   /clear

효율적인 요청 패턴

# ❌ 비효율적
"vault의 모든 파일을 분석해줘"

# ✅ 효율적
"003-RESOURCES에서 'kubernetes' 태그가 있는 노트 목록만 보여줘"

컨텍스트 관리

/compact

/clear

/cost

파일 처리 시 주의사항

제외 대상

• .obsidian/

  폴더

• archive/

  폴더

• .canvas

  파일
• 이미지 파일 (

  .png

  ,

  .jpg

  ,

  .gif

  등)

오류 처리

• 읽기 오류 파일은

  UNPROCESSED-FILES.md

  에 기록
• 인코딩 문제 시 UTF-8로 재시도

검색 도구 선택 가이드