옵시디언(Obsidian) vault 기록·조회

이 스킬은 어느 디렉터리에서 작업 중이든 고정된 개인 vault에 노트를 쌓거나 조회하기 위한 것이다. 옵시디언 앱이나 플러그인 API를 쓰지 않는다. 파일 도구(Read/Write/Edit/Grep/Glob)와 셸만 쓴다.

0. vault 경로 설정 (첫 사용 전 1회)

경로는 이 순서로 찾는다:

1. 환경변수 OBSIDIAN_VAULT
2. ~/.claude/obsidian.env 의 OBSIDIAN_VAULT=... 한 줄

VAULT="${OBSIDIAN_VAULT:-$(grep -E '^OBSIDIAN_VAULT=' ~/.claude/obsidian.env 2>/dev/null | cut -d= -f2-)}"
[ -d "$VAULT" ] || echo "vault 경로를 먼저 설정하세요"

• iCloud 동기화 vault의 경로에는 공백과 ~ 문자가 들어간다(예: ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/<vault명>). 셸에서는 항상 따옴표로 감싼다.
• 경로가 설정돼 있지 않으면 추측하지 말고 사용자에게 묻는다.
• 동기화되는 vault다. 파일 수정은 곧 모든 기기에 반영된다. 삭제·대량 변경은 신중히, 사용자가 요청한 범위만 건드린다.
• .obsidian/ 디렉터리는 앱 설정이다. 절대 수정하지 않고, 조회 대상에서도 제외한다.

1. 핵심 원칙 — 파일이 곧 그래프

• 진실의 원천은 .md 파일이다. 지식과 관계는 전부 마크다운 텍스트에 인코딩돼 있다.
• 폴더 = 카테고리. 최상위 폴더가 주제 분류다(예: JAVA/, DB/). 실제 폴더 구성은 매번 확인한다 — 사용자가 앱에서 수시로 바꿀 수 있다:

  ls "$VAULT"

• 옵시디언 기본 링크 해석은 vault 전체에서 파일명(제목) 기준이다. 노트를 폴더 간에 옮겨도 [[링크]]는 깨지지 않는다.

관계 문법 (옵시디언 표준)

명시적 [[링크]]만 확실한 엣지로 신뢰한다(본문에 제목이 그냥 언급된 것은 관계가 아니다).

2. 조회(맥락 수집) 워크플로우

작업 중 맥락이 부족하면 사용자에게 되묻기 전에 여기부터 찾아본다. 전용 CLI는 없다 — 파일 도구(Grep/Glob/Read)와 셸로 직접 탐색한다:

• 노트 목록/구조: ls "$VAULT" → 관심 폴더 재귀 탐색
• 검색: grep -rn --include="*.md" "키워드" "$VAULT" (.obsidian은 md가 없어 자연히 제외)
• 아웃링크(이 노트가 가리키는 것): 대상 노트를 Read 하고 본문의 [[...]]를 모은다.
• 백링크(이 노트를 가리키는 것): grep -rln --include="*.md" '\[\[대상제목' "$VAULT"
• 이웃(1-hop): 아웃링크 ∪ 백링크. 필요하면 이웃의 이웃으로 확장.
• 태그로 모으기: grep -rln --include="*.md" '#태그' "$VAULT"

3. 기록 워크플로우

1. 중복 방지 — 먼저 조회한다. §2로 같은 주제 노트가 이미 있는지 확인한다. 있으면 새로 만들지 말고 그 노트를 Edit로 보강한다.
2. 카테고리(폴더)를 고른다. 기존 폴더에 맞으면 거기에, 아니면 새 최상위 폴더를 만든다.
3. 파일명 = 제목 = 링크 대상이므로 신중히 정한다. 짧고 고유하며 다른 노트에서 [[이 제목]]으로 부르기 자연스러운 이름으로. 확장자는 .md 하나만 붙인다. 파일명에 옵시디언 금지 문자(# ^ [ ] | 및 / \ :)를 쓰지 않는다.
4. frontmatter를 일관되게 쓴다. vault 안에서 키를 통일한다:

   ---
   type: <note|person|service|runbook|reference …>
   tags: [태그1, 태그2]
   created: 2026-07-29
   ---

   기존 노트에 이미 쓰이는 키 컨벤션이 있으면 그것을 먼저 살펴 맞춘다.
5. 고립 금지 — 가능하면 최소 1개 [[링크]]로 기존 노트에 연결한다. 연결할 노트가 정말 없으면 상위 개념 노트를 만들어 잇거나, 같은 카테고리의 인접 노트에 역링크를 추가한다. 그래프에서 떠 있는 노드는 나중에 참조되지 못한다.
6. Write/Edit로 저장한다. 동기화는 옵시디언·클라우드가 처리하므로 파일 저장만 확실히 하면 된다.

무엇을 기록하고, 무엇을 기록하지 않는가

이 vault의 가치는 다른 도구·스킬이 이미 아는 것을 중복하지 않고, 그것들이 모르는 것을 채우는 데 있다.

• ✅ 기록한다: 도구 문서에 없는 보강·교정 지침, 사용자가 겪은 함정과 그 해법, 담당 서비스의 도메인 지식, 조직/사람/시스템 간 관계, 결정의 배경(why), 학습 노트.
• ❌ 기록하지 않는다: 이미 어떤 스킬의 SKILL.md나 레포 문서에 정의돼 있는 절차·규칙. 확실치 않으면 그 문서를 먼저 확인해 중복인지 판단한다.

기록할지 애매하면, 사용자가 "이건 기억해둬"라고 명시했거나 도구로 재현 불가능한 지식일 때만 남긴다.

4. 할일(todo) 관리

할일은 일간(日刊) 기준 — 하루치 할일을 그 날짜의 노트 하나에 모은다. todo 폴더에 날짜별 노트를 두고 체크박스 목록(- [ ]/- [x])으로 다룬다. 할일도 그래프의 일부다 — 각 줄에서 [[링크]]로 맥락 노트에 연결한다.

• 파일 = 하루치: todo/할일 <YYYY-MM-DD>.md. 오늘 날짜는 date +%F로 구한다.
• 마감일 기본값 = 그 노트의 날짜. 사용자가 다른 마감을 명시할 때만 항목 끝에 (~마감 MM-DD)를 붙인다.
• 섹션: 위쪽 ## 진행중, 아래쪽 ## 완료.
• 항목 형식: - [ ] <할 일> [[맥락노트]] #태그
• 추가: 오늘 날짜 노트가 있으면 ## 진행중 맨 아래에 한 줄 Edit, 없으면 아래 골격으로 생성.
• 완료: 해당 줄을 - [x]로 바꾸고 ## 완료로 옮긴다. 지우지 않는다(완료 이력도 맥락이다). 취소된 할일은 줄을 삭제한다.

새 일간 할일 노트 골격:

---
type: todo-list
date: 2026-07-29
tags: [todo]
---

# 할일 2026-07-29

## 진행중
- [ ] <할 일> [[맥락노트]] #태그

## 완료

5. 예시

예시 1 — 담당 서비스 지식 신규 기록 사용자: "billing은 결제 승인/취소를 담당하는 백엔드 서비스야. 옵시디언에 정리해둬." 동작: vault 폴더 확인 → 기존 billing 노트 grep(중복 확인) → 적절한 폴더(없으면 work/ 등 신설)에 Billing.md 생성, frontmatter(type: service) + 설명 + 관련 노트가 있으면 [[결제]] 등으로 연결.

예시 2 — 조회 후 되묻기 회피 이슈 트래커 스킬로 티켓을 만드는 중 "이 프로젝트 담당자 누구였지"가 필요할 때: 사용자에게 묻기 전에 grep -rn --include="*.md" "담당" "$VAULT"로 먼저 찾아본다.

예시 3 — 기존 노트 보강(중복 생성 금지) 사용자: "아까 그 타임아웃 이슈 원인, 옵시디언에 추가해줘." 동작: 관련 노트를 grep → 있으면 그 파일을 Edit로 섹션 추가, 없을 때만 새로 만든다.

예시 4 — 할일 추가/완료 (일간) 사용자: "billing 운영 배포 검증, 옵시디언 할일에 추가해줘." 동작: 오늘 날짜(date +%F) 노트 todo/할일 2026-07-29.md 존재 확인 → 있으면 ## 진행중에 - [ ] billing 운영 배포 검증 [[Billing]] #billing 한 줄 Edit, 없으면 골격으로 생성. 나중에 "그거 끝냈어"라고 하면 그 줄을 - [x]로 바꿔 ## 완료로 이동.