vault-linter

name	vault-linter
description	Use when user says "vault lint", "노트 점검", "vault 정리", "orphan notes", "링크 점검", or wants to check Obsidian vault health. Do NOT use for individual note creation (use obsidian-note) or tag management (use til-tagger).

Vault Linter

Obsidian Vault의 건강 상태를 점검하고 지식 그래프의 일관성을 유지하는 스킬. Karpathy의 "LLM Knowledge Base Linting" 패턴.

기본 설정

항목	값
Vault 경로	~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Note
기본 산출물	_Inbox/Vault-Index.md
진단 리포트 저장 위치	_Inbox/Vault-Lint-Report-{YYYY-MM-DD}.md (명시적으로 리포트를 요청한 경우만)
검사 제외	Templates/, .obsidian/, Vault-Lint-Report*, Vault-Semantic-Report*, Vault-Index.md, Vault-Log.md

사용법

/vault-linter                    # 전체 점검
/vault-linter --orphans          # 고아 노트만
/vault-linter --links            # 깨진 링크만
/vault-linter --stale            # 오래된 노트만
/vault-linter --suggestions      # 새 노트 후보만
/vault-linter --semantic         # 의미 기반 유사 노트 연결
/vault-linter --index            # Vault 인덱스만 갱신
/vault-linter --report           # 명시적으로 Vault-Lint-Report 생성

Scripts

스크립트	용도
scripts/vault-scan.sh list-notes	제외 대상 빼고 전체 노트 목록 출력
scripts/vault-scan.sh extract-links <file>	파일에서 [[wikilink]] 추출 (alias 처리 포함)
scripts/vault-scan.sh check-links <file>	깨진 링크만 출력
scripts/vault-scan.sh check-links-all	전체 vault의 깨진 링크를 한 번의 노트 인덱스로 TSV 출력
scripts/vault-scan.sh find-orphans	어디서도 참조되지 않은 노트 목록
scripts/vault-scan.sh tag-list	태그별 사용 횟수
scripts/semantic-linker.py	bge-m3 임베딩 + 코사인 유사도 후보 추출
scripts/semantic-linker.py --cache-only	임베딩 캐시만 빌드 (유사도 계산 생략)
scripts/vault-index.py	폴더별 노트 카탈로그 생성

스크립트가 결정적 검증을 수행하고, Claude는 결과를 해석하고 제안한다.

Instructions

Step 1: Vault 스캔

bash scripts/vault-scan.sh list-notes

결과로 전체 노트 목록을 확보. 이후 단계에서 스크립트를 활용한다.

Step 2: 고아 노트 점검 (Orphan Notes)

bash scripts/vault-scan.sh find-orphans

결과로 나온 고아 노트에 대해 tags와 키워드 기반으로 연결 후보를 제안한다.

Step 3: 깨진 위키링크 점검 (Broken Links)

각 노트에 대해:

bash scripts/vault-scan.sh check-links "$NOTE"

깨진 링크가 발견되면 "새 노트를 만들까요?" 또는 "링크를 제거할까요?" 제안.

Step 4: 오래된 노트 점검 (Stale Notes)

90일 이상 된 노트 중, 버전/날짜 의존적 내용이 있는 것을 찾는다.

• 날짜 판단 우선순위: frontmatter created → 없으면 파일 수정 시간(stat -f %Sm macOS / stat -c %y Linux)
• 본문에서 연도(202X), 버전(v1.x, 버전 N), "최신", "현재" 등 시간 의존적 표현 검색
• 해당 노트 목록 출력 + tavily_search로 정보 유효성 확인 제안

Step 5: 태그 비일관성 점검 (Tag Inconsistency)

모든 태그를 수집하여 유사하지만 다른 태그 쌍을 찾는다.

대소문자 차이(ai/llm vs ai/LLM), 유사 표현(database/sql vs db/sql) 등을 탐지하고 통일 제안.

Step 6: 새 노트 후보 제안 (Article Candidates)

여러 노트의 ## 더 알아보기 섹션에서 공통 언급 주제를 추출한다.

• 모든 "더 알아보기" 섹션 텍스트 수집
• 주제 빈도 분석
• 2개 이상 노트에서 언급된 주제를 새 노트 후보로 제안

Step 6.5: Wiki INDEX 동기화 점검

Wiki/_INDEX.md에 누락된 아티클이 있는지 점검한다.

1. Wiki/ 폴더의 .md 파일 목록 수집 (_INDEX.md 제외)
2. Wiki/_INDEX.md 본문에서 [[...]] wikilink 추출
3. diff: 폴더에 있지만 INDEX에 없는 파일 = 누락
4. diff: INDEX에 있지만 폴더에 없는 링크 = 깨진 참조

누락 파일이 있으면:

• 파일 내용 첫 100줄을 읽고 적절한 카테고리(INDEX의 기존 ## 섹션)를 추천
• 기존 섹션에 맞지 않으면 새 섹션 이름도 제안
• 리포트에 "어느 섹션에 넣을지"까지 포함

📋 Wiki INDEX 동기화
├── 누락: 3개
│   ├── Spring-AI-ChatClient.md → "## Spring > Spring AI" 추천
│   ├── Docker-Compose-v2.md → "## Docker / DevOps" 추천
│   └── RAG-패턴.md → "## AI / LLM" 추천
└── 깨진 참조: 0개

Step 7: 리포트 생성 (--report 명시 시에만)

기본 실행과 --index 실행은 Obsidian vault에 Vault-Lint-Report-*를 남기지 않는다. 사용자가 명시적으로 진단 리포트를 요청했을 때만 결과를 _Inbox/Vault-Lint-Report-{YYYY-MM-DD}.md에 저장한다.

---
tags:
  - vault/maintenance
created: {YYYY-MM-DD}
---

## Vault Lint Report — {YYYY-MM-DD}

### 요약

| 항목 | 건수 | 심각도 |
|------|------|--------|
| 고아 노트 | N건 | ⚠️ |
| 깨진 링크 | N건 | 🚫 |
| 오래된 노트 | N건 | 💡 |
| 태그 비일관성 | N건 | 💡 |
| INDEX 누락 | N건 | 📋 |
| 새 노트 후보 | N건 | ✨ |

### 🚫 깨진 링크

| 노트 | 깨진 링크 | 제안 |
|------|-----------|------|
| [[노트A]] | [[존재하지않는것]] | 새 노트 생성 or 링크 제거 |

### ⚠️ 고아 노트

| 노트 | 연결 후보 |
|------|-----------|
| [[고아노트]] | [[관련노트]] (태그 매칭) |

### 💡 오래된 노트

| 노트 | 생성일 | 시간 의존적 내용 |
|------|--------|-----------------|
| [[구형노트]] | 2025-01-01 | "v2.x 기준" 언급 |

### 💡 태그 비일관성

| 태그 A | 태그 B | 건수 | 통일 제안 |
|--------|--------|------|-----------|
| ai/llm | ai/LLM | 5+2 | ai/llm |

### ✨ 새 노트 후보

| 주제 | 언급 노트 수 | 출처 노트 |
|------|-------------|-----------|
| RAG vs Long Context | 3 | [[A]], [[B]], [[C]] |

Step 8: 의미 기반 연결 (Semantic Linking) — --semantic

8-1: 사전 조건 확인

ollama list | grep bge-m3

bge-m3가 없으면:

ollama pull bge-m3

8-2: 후보 추출

python3 scripts/semantic-linker.py

JSON 출력의 candidate_pairs를 파싱한다.

8-3: LLM 검증 (이어가기 지원)

리뷰 큐 파일이 있으면 이어서 진행:

ls scripts/semantic-review-queue.json 2>/dev/null && echo "리뷰 큐 있음 — 이어가기 모드"

리뷰 큐가 있으면 next_batch_start부터 batch_size(50)만큼 읽어서 처리하고, llm_reviewed: true로 업데이트. 없으면 새로 시작.

각 후보 쌍에 대해:

1. 두 노트의 내용을 Read로 읽는다
2. 연결 가치를 판단한다:
   • 연결: 의미적으로 유의미한 관계 (보충, 선행지식, 대안 관점, 사례)
   • 거절: 우연한 키워드 겹침, 의미 없는 유사도
3. 연결이면 양쪽 노트의 related_notes에 [[상대노트]] 추가
4. 10-20쌍 단위로 배치 처리하여 컨텍스트 관리

8-4: 리포트 생성

_Inbox/Vault-Semantic-Report-{YYYY-MM-DD}.md에 저장:

---
tags:
  - vault/maintenance
created: {YYYY-MM-DD}
---

## Vault Semantic Link Report — {YYYY-MM-DD}

### 요약

| 항목 | 건수 |
|------|------|
| 분석 노트 | N개 |
| 후보 쌍 | N개 |
| 연결 완료 | N개 |
| 거절 | N개 |

### 새 연결

| Note A | Note B | 유사도 | 관계 유형 |
|--------|--------|--------|----------|
| [[A]] | [[B]] | 0.82 | 보충 |

### 거절된 쌍

| Note A | Note B | 유사도 | 거절 사유 |
|--------|--------|--------|----------|
| [[C]] | [[D]] | 0.76 | 키워드 우연 겹침 |

Step 9: Vault 인덱스 — --index

카파시의 "LLM Wiki" 패턴에서 index.md는 LLM이 vault 탐색 시 가장 먼저 읽는 메타 레이어다. 매번 전체 노트를 Glob 하지 않고, 카탈로그에서 관련 폴더를 좁히고 진입한다.

9-1: 인덱스 생성 (결정적)

python3 scripts/vault-index.py

동작:

• _Inbox/Vault-Index.md 전체 덮어쓰기 (폴더별 노트 + 본문 첫 줄 요약)
• _Inbox/Vault-Log.md는 생성하지 않음
• _Inbox/Vault-Lint-Report-{YYYY-MM-DD}.md는 생성하지 않음

Self-Check

□ 제외 대상(Templates, .obsidian)을 빼고 스캔했는가
□ 깨진 링크에서 Obsidian alias([[이름|별칭]])를 올바르게 처리했는가
□ `--index` 실행은 `Vault-Index.md`만 생성/갱신했는가
□ 리포트는 사용자가 명시적으로 요청한 경우에만 _Inbox에 저장했는가
□ 고아 노트에 구체적 연결 후보를 제안했는가
□ 새 노트 후보의 출처 노트를 명시했는가
□ 각 플래그(--orphans, --links 등) 단독 실행이 가능한 구조인가
□ --semantic 실행 전 ollama + bge-m3 설치를 확인했는가
□ 이미 연결된 노트 쌍을 중복 제안하지 않았는가
□ --index는 Vault-Index.md 덮어쓰기만 수행했는가

Gotchas

• Obsidian alias 문법 [[파일명|표시명]]에서 파일명만 추출해야 함 — vault-scan.sh가 처리
• 파일명에 특수문자가 포함될 수 있음 — vault-scan.sh가 grep 이스케이프 처리
• vault 경로에 공백이 포함됨 (iCloud path) — 항상 따옴표로 감싸기
• --stale의 tavily_search는 시간이 오래 걸릴 수 있음 — 노트 수가 많으면 상위 5개만 점검
• --orphans도 대형 vault(300+)에서 느릴 수 있음 — vault-scan.sh가 xargs로 일괄 처리하므로 개별 grep보다 빠름
• --semantic 첫 실행 시 877개 임베딩 생성에 수 분 소요 — 이후 캐시로 신규/변경 노트만 처리
• ollama가 실행 중이어야 함 — ollama serve로 데몬 시작 필요할 수 있음
• embeddings-cache.json은 gitignore됨 — 머신 간 동기화 안 됨 (의도적)
• --index의 요약은 본문 첫 줄(heading/frontmatter/table row 제외)을 100자로 자름 — 프론트매터에 description: 필드가 있으면 나중에 그걸 우선 쓰도록 확장 가능