Obsidian 볼트를 Claude Code로 자동화한 이야기

노트 앱을 넘어서

Obsidian을 쓰기 시작한 건 메모를 모아두기 위해서였다. 그런데 기록이 늘어나면서 단순 메모장을 넘어 재정 관리, 여행 계획, 투자 기록, 건강 기록까지 들어가기 시작했고, 어느 순간 “이 데이터를 좀 더 체계적으로 다룰 수 없을까?” 하는 생각이 들었다.

Claude Code를 볼트에 연결하면서 상황이 바뀌었다. 마크다운 문서만으로 관리하기 어려웠던 정량 데이터를 SQLite로 이중 기록하고, 반복 작업을 Skills로 자동화하고, 문서 작성 규칙을 Rules로 강제하는 구조를 만들었다. 지금은 25개의 Skill, 15개의 Rule, 14개의 SQLite CLI 스크립트가 볼트 안에서 돌아가고 있다.

이 글에서는 구현 상세보다 “어떤 패턴으로 구성했고, 왜 그렇게 했는지”를 중심으로 이야기한다.

볼트 구조: 카테고리 기반 6-폴더

볼트는 번호 접두사로 카테고리를 구분한다.

00_Ontology/    → 메타 구조 정의 (인덱스, 카테고리, 네이밍 규칙)
10_Finance/     → 재정 (자산, 세금, 카드, 보험)
20_Life/        → 생활 (여행, 건강, 가족)
30_Work/        → 업무 (프로젝트, 커리어)
40_Learning/    → 학습 (기술, 영어)
99_File/        → 파일 저장소 (PDF, 이미지, Trash)

각 카테고리와 하위 폴더에는 _INDEX.md가 있어서 해당 영역의 문서 목록과 통계를 관리한다. 문서를 추가하거나 삭제할 때 이 인덱스가 자동으로 갱신되는데, 이건 뒤에서 설명할 Rules 시스템이 담당한다.

Rules: 문서 작업의 자동 규칙

.claude/rules/ 디렉토리에 마크다운 파일로 규칙을 정의하면, Claude Code가 볼트 작업 시 이 규칙을 자동으로 따른다. 현재 15개의 규칙 파일이 있는데, 크게 세 가지 역할로 나뉜다.

구조 규칙

프론트매터 강제 — 모든 문서에 title, date, category, type, tags 필드를 포함한 YAML 프론트매터가 필수다. 문서 타입은 index, record, plan, summary, reference, analysis 중 하나.

파일명 규칙 — 영문 소문자 + 언더스코어. 월별 기록은 YYYY-MM_description.md, 스냅샷은 YYYY-MM-DD_description.md 형식. 이 규칙이 없으면 한글 파일명, 대문자, 하이픈이 섞이면서 금방 혼란스러워진다.

동기화 규칙

Post-op Sync — 가장 핵심적인 규칙이다. 문서를 생성·수정·삭제할 때마다 자동으로 실행되는 후처리 파이프라인.

해당 _INDEX.md 갱신 (문서 링크·설명 추가/제거)
상위 _INDEX.md 전파 (수치가 인라인되어 있으면 함께 갱신)
신규 문서 간 양방향 링크 생성
파일 추가·이동 시 99_File/_INDEX.md 통계 갱신

예를 들어 구독 관리 문서의 월 결제액이 바뀌면, 해당 문서 → Banking 인덱스 → Finance 인덱스까지 2단계 전파가 일어난다. 수동으로 하면 빼먹기 십상인 작업인데, 규칙으로 정의해두면 빠짐없이 처리된다.

소프트 삭제 — 문서 삭제 요청 시 rm으로 영구 삭제하지 않고 99_File/Trash/YYYYMMDD/ 폴더로 이관한다. 30일 후 자동 영구 삭제. 실수로 지운 문서를 복구할 수 있어서 몇 번 살려준 적이 있다.

도메인 규칙

재정이나 여행처럼 특정 도메인에만 적용되는 규칙도 있다. 세액 계산 공식, 공모가 역산 공식, 마일리지 적립 구조 같은 것들을 규칙 파일에 하드코딩해두면, 관련 작업 시 Claude Code가 정확한 수치로 계산한다. 세법이 바뀌면 규칙 파일만 수정하면 된다.

Skills: 반복 작업의 자동화

.claude/skills/ 디렉토리에 SKILL.md 파일로 정의하는 실행 가능한 워크플로우다. 현재 25개가 등록되어 있는데, 자주 쓰는 것들을 몇 가지 소개한다.

재정 계열

자산 스냅샷 — 전체 자산 현황을 스냅샷으로 기록한다. 계좌별 잔액을 입력하면 마크다운 문서 생성 + SQLite insert + 인덱스 전파까지 한 번에.

투자 현황 업데이트 — 증권사 API로 시세를 조회해서 보유 종목의 평가금액·수익률을 자동 갱신한다. 3개 계좌 문서 + 통합 요약까지 한 번에 업데이트.

지출/수입 기록 — 거래 내역을 입력하면 월별 기록 문서에 추가하고, SQLite에도 insert하고, 인덱스 통계를 갱신한다.

생활 계열

여행 문서 생성 — 날짜와 도시를 입력하면 항공편·숙소·일정·경비 섹션이 포함된 여행 문서 템플릿을 생성한다.

영어 연습 — 일상 주제로 영어 회화 질문을 생성하고, 답변에 대한 피드백을 제공한다. 연습 기록이 SQLite에 쌓여서 복습 모드에서 과거에 틀린 표현을 다시 출제한다.

유틸리티 계열

볼트 싱크 — 전체 _INDEX.md의 일관성을 검증하고, 누락된 링크나 잘못된 통계를 자동 수정한다.

파일 임포트 — Telegram으로 받은 파일을 내용에 따라 자동 분류하고 적절한 폴더로 이동시킨다. 여행 예약 확인서면 99_File/Travel/로, 급여명세서면 99_File/Finance/로.

자연어 트리거

Skills에 슬래시 커맨드(/skill-name)를 붙일 수도 있지만, 자연어로 트리거하는 게 더 편하다. Rules 파일에 키워드 매핑 테이블을 정의해두면, “영어 공부 하자”라고 말하면 영어 연습 Skill이 자동 호출되고, “투자 현황 업데이트”라고 하면 투자 Skill이 실행된다.

"어떤 카드로 결제"  → 카드 추천 Skill
"마일로 발권"      → 마일리지 조회 Skill
"현행화"           → 볼트 싱크 Skill

키워드는 부분 일치로 판단하기 때문에, “오늘 영어 공부 할까?”도 “영어 공부” 키워드에 매칭된다.

SQLite Dual-Write: 마크다운과 DB의 공존

이 구조에서 가장 고민을 많이 한 부분이다. Obsidian은 마크다운 기반이라 정량 데이터(자산 금액, 거래 내역, 운동 기록)를 다루기에 한계가 있다. 그렇다고 별도 앱을 쓰면 데이터가 분산된다.

해결책은 Dual-Write였다. 정량 데이터를 기록할 때 마크다운 문서와 SQLite DB에 동시에 쓴다.

Skill 실행
  ├─ 1. SQLite INSERT (트랜잭션 보장)
  ├─ 2. 체크섬 갱신 (무결성 검증)
  ├─ 3. 마크다운 생성 블록 재렌더
  └─ 4. _INDEX 전파 (Post-op Sync)

마크다운 문서 안에는 “생성 블록”이라는 특수 마커로 감싼 영역이 있다. 이 영역은 SQLite에서 쿼리한 결과를 렌더링한 것이라서, DB가 업데이트되면 자동으로 다시 그려진다. Obsidian에서는 그냥 테이블로 보이지만 실제 데이터는 DB에 있는 셈이다.

왜 이렇게 했냐면, 두 가지 장점이 있다.

첫째, Obsidian에서의 가독성. DB만 쓰면 Obsidian에서 데이터를 볼 수 없다. Dual-Write로 마크다운에도 렌더링해두면 앱에서 바로 확인할 수 있다.

둘째, 쿼리 가능성. 마크다운만 쓰면 “최근 3개월 지출 추이” 같은 분석이 어렵다. SQLite에 데이터가 있으면 ad-hoc 쿼리로 원하는 분석을 즉시 할 수 있다.

현재 SQLite에 들어가는 데이터는 자산 스냅샷, 거래 내역, 보유 종목 시세, 마일리지 적립, 공모주 청약, 운동 기록, 영어 연습 기록, 구독 서비스, 미리 알림 등이다. CLI 스크립트 14개가 각각의 도메인을 담당하고, Node.js 22의 built-in node:sqlite를 사용해서 npm 의존성이 전혀 없다.

이 구조가 주는 것

몇 달 운영하면서 느낀 실질적인 이점은 세 가지다.

일관성. Rules가 강제하는 프론트매터, 파일명, 인덱스 동기화 덕분에 볼트가 무질서해지지 않는다. 200개 넘는 문서가 있지만 “어디에 뭐가 있는지” 항상 파악 가능하다.

데이터 활용. 마크다운만으로는 불가능했던 “월별 지출 추세”, “자산 변동 추이”, “카드별 마일리지 누적” 같은 분석이 SQLite 쿼리 하나로 된다. 기록하는 건 같은 노력인데, 활용도가 완전히 다르다.

반복 작업 제거. 투자 현황을 업데이트하려면 3개 계좌 문서 + 통합 요약 + 인덱스를 모두 수정해야 했다. Skill 하나로 전부 자동화하니 5분 걸리던 일이 한마디로 끝난다.

고려할 점

이 구조가 만능은 아니다. 몇 가지 트레이드오프가 있다.

초기 설정 비용. Rules 15개, Skills 25개를 처음부터 만든 건 아니고 필요할 때마다 하나씩 추가했지만, 그래도 누적 시간이 적지 않다. “그냥 노트 쓰는 것”과는 결이 다른 작업이다.

Claude Code 의존성. 이 자동화는 Claude Code 세션 안에서만 동작한다. Obsidian 앱 자체로는 Skills나 Rules가 실행되지 않는다. 다만 이 문제는 Telegram 채널 플러그인으로 상당 부분 해소했는데, 아래에서 설명한다.

SQLite 동기화. 볼트를 iCloud로 동기화하고 있는데, SQLite는 WAL 모드에서 iCloud와 충돌이 날 수 있다. 그래서 DELETE 저널 모드를 쓰고, 체크섬으로 무결성을 검증하는 방어 로직을 넣었다.

Telegram으로 어디서든 접근하기

이 볼트의 진짜 가치는 “내 삶의 데이터가 한곳에 있다”는 점인데, 터미널 앞에 앉아 있을 때만 접근할 수 있으면 반쪽짜리다. Claude Code의 Telegram 채널 플러그인을 연결하면서 이 제약이 풀렸다.

지금은 Telegram 메시지 하나로 볼트의 모든 자동화를 쓸 수 있다. “투자 현황 업데이트해줘”라고 보내면 Skill이 실행되고, 항공권 예약 확인서 PDF를 첨부하면 자동 분류되어 99_File/Travel/로 이동한다. 지출을 기록하고 싶으면 “오늘 점심 12,000원 신한카드”라고 보내면 된다. 출퇴근 지하철에서, 여행지 호텔에서, 어디서든 내 볼트에 접근할 수 있다는 게 생각보다 큰 차이를 만든다.

채널 접근 권한 관리

흥미로운 건 Rules로 권한 관리까지 구현한 부분이다. Telegram의 chat_id를 기반으로 사용자별 접근 가능 경로를 제한한다.

예를 들어, 나는 볼트 전체에 접근할 수 있지만, 짝꿍의 chat_id는 여행 관련 문서(20_Life/20.1_Travel/)만 읽기·요약이 허용된다. 동반자로 포함된 여행 문서에 한해서는 일정 변경이나 메모 추가 같은 수정도 가능하지만, 재정 정보는 수정할 수 없다.

허용 범위가 애매한 요청이 오면 작업을 보류하고 내 Telegram으로 권한 요청 메시지를 보낸다. “짝꿍이 이런 작업을 요청했는데, 허용할까요?”하는 식이다. 이 전체 흐름이 Rules 파일 하나에 테이블로 정의되어 있다.

별도의 인증 시스템을 만든 게 아니라 Rules의 자연어 규칙으로 접근 제어를 구현한 건데, Claude Code가 규칙을 충실히 따르기 때문에 실제로 잘 동작한다. 물론 보안이 중요한 시스템에 이 방식을 쓰라는 건 아니고, 개인 볼트 수준에서는 충분히 실용적이라는 이야기다.

마무리

Obsidian 볼트에 Claude Code를 연결하면, 노트 앱이 개인용 데이터 플랫폼에 가까워진다. 핵심은 세 가지 레이어의 조합이다.

Rules — 문서 구조, 동기화, 접근 권한을 자동으로 강제
Skills — 반복 작업을 자연어 한마디로 실행
SQLite — 정량 데이터를 마크다운과 DB에 이중 기록
Telegram — 장소에 구애받지 않는 볼트 접근 채널

처음부터 거창하게 만들 필요는 없다. 나도 처음에는 프론트매터 규칙 하나, 자산 스냅샷 스킬 하나로 시작했다. 반복되는 작업이 보일 때마다 Skill을 하나씩 추가하고, 문서가 어지러워질 때마다 Rule을 하나씩 잡아가면 된다.

참고

Claude Code Skills — Skills 공식 문서
Claude Code CLAUDE.md — 프로젝트 규칙 설정
Obsidian — 마크다운 기반 지식 관리 앱
Node.js SQLite — Node.js 22 built-in SQLite 모듈