| name | obsidian-vault |
| description | Obsidian vault 및 마크다운 문서 작업 시 사용. markdown-oxide LSP 기반 백링크/태그 검색,
ripgrep 기반 fallback, 토큰 최적화 전략 제공. Obsidian, vault, 마크다운, 태그, 노트 정리,
zettelkasten, 백링크, wiki-link, PKM 관련 작업 시 자동 적용.
출처: msbaek/dotfiles의 obsidian-vault skill을 로컬 환경에 맞게 어댑테이션.
|
Obsidian Vault 작업 가이드
경로 정보
| 항목 | 경로 |
|---|
| 기본 vault | ~/Desktop/ueibin.kim/ (.obsidian/ 존재) |
| 신규 노트 저장 위치 | <vault>/001-INBOX/ (Zettelkasten 표준) |
| 첨부파일 | <vault>/ATTACHMENTS/ |
vault 경로가 변경되면 이 표를 SSOT로 업데이트.
검색 도구 우선순위
1순위: markdown-oxide LSP (백링크/태그/링크 그래프) ← 설치 권장
2순위: ripgrep (Grep tool) — 단순 키워드/문자열
3순위: fd / Glob — 파일명 패턴
markdown-oxide 설치 (선택)
cargo install --locked markdown-oxide
설치 후 claude-code-lsps 마켓플레이스에 markdown-oxide LSP 플러그인이 있는지 확인:
ls ~/.claude/plugins/marketplaces/claude-code-lsps/ | grep -i markdown
없으면 markdown-oxide MCP 서버 설정으로 대체 (별도 작업 필요).
LSP 기반 검색 (markdown-oxide 설치 시)
| 작업 | 도구 |
|---|
[[링크]] → 정의 위치 | goToDefinition |
| 백링크 (이 노트를 참조하는 곳) | findReferences |
#태그 사용처 | findReferences (태그 심볼) |
| 깨진 링크 | diagnostics |
| 파일 내 헤딩/심볼 트리 | documentSymbol |
| 워크스페이스 노트 검색 | workspaceSymbol |
사용 예시
"TDD 노트를 참조하는 모든 노트 찾아줘" → findReferences
"#project/active 태그 노트 목록" → findReferences (#project/active)
"vault에서 깨진 링크 확인" → diagnostics
"이 노트의 헤딩 구조" → documentSymbol
Fallback (markdown-oxide 미설치 시)
rg -l '\[\[NoteName(\||\]])' "$VAULT_ROOT"
rg '#project/active(\s|$)' "$VAULT_ROOT" --type md
fd 'TDD' "$VAULT_ROOT" -e md
Zettelkasten 폴더 구조 (권장)
| 폴더 | 용도 | 권한 |
|---|
000-SLIPBOX | 개인 인사이트 / atomic notes | 읽기/쓰기 |
001-INBOX | 임시 수집함 (신규 노트 기본 위치) | 읽기/쓰기 |
002-LITERATURE | 책/논문/아티클 노트 | 읽기/쓰기 |
003-RESOURCES | 참고자료 | 주로 읽기 |
archive | 보관 자료 | 접근 금지 |
.obsidian/ | Obsidian 설정 | 건드리지 말 것 |
신규 노트는 명시적 지시가 없으면 001-INBOX/에 저장.
Hierarchical Tags
- 형식:
#category/subcategory/detail
- 카테고리 5종: Topic / Document Type / Source / Status / Project
- 예:
#topic/tdd, #type/article, #source/web, #status/draft, #project/payment-refund
토큰 최적화 (vault 작업 한정)
rules/token-optimization.md 의 일반 원칙에 더해:
- 한 번에 10개 이하 파일만 처리 — vault 전체 스캔 금지
archive/, .obsidian/, ATTACHMENTS/(이미지) 무시
- MOC(Map of Content) 노트가 있으면 먼저 읽고 거기서 가리키는 노트만 선택적 로드
- frontmatter 만 필요하면 Read 대신
rg --max-count 1 -A 10 '^---$' 로 첫 블록만 추출
- 20회 이상 반복 작업 후
/compact 권장
효율적 요청 패턴
# ❌ 비효율적 — 전체 스캔, 토큰 폭발
"vault의 모든 파일을 분석해줘"
"모든 노트의 주제를 정리해줘"
# ✅ 효율적 — 범위·필터 명시
"003-RESOURCES에서 'kubernetes' 태그가 있는 노트 목록"
"001-INBOX의 최근 7일 노트 frontmatter만 보여줘"
"#status/draft 태그 노트 5개의 제목과 첫 문단"
노트 생성 시 frontmatter 템플릿
---
created: 2026-04-11
modified: 2026-04-11
tags:
- topic/<주제>
- status/draft
source: <URL or 책 제목>
related: []
---
안티패턴
- ❌
.obsidian/ 또는 archive/ 폴더 수정
- ❌ vault 전체에 대해 grep 후 결과를 통째로 컨텍스트 로딩
- ❌ 이미지 첨부파일을 Read 도구로 열기 (binary)
- ❌ frontmatter 파싱을 위해 전체 파일 Read (
rg 로 충분)
- ❌ 백링크 찾을 때 노트 한 개씩 Read (LSP 한 번 호출이면 끝)