Claude Code x Obsidian 완벽 연동 가이드 | Vault를 키우는 AI 노트 기술

Obsidian 사용자라면 한 번쯤 생각해봤을 것입니다. “이 Vault, 좀 더 자동으로 정리해주면 좋을 텐데” 하고 말이죠. Claude Code는 Obsidian의 최고의 파트너입니다. 왜냐하면 Obsidian Vault는 결국 Markdown 파일이 담긴 폴더이고, Claude Code는 파일 트리를 읽고 쓰는 것이 가장 잘하는 일이기 때문입니다.

이 글에서는 Claude Code와 Obsidian을 조합해서 Vault를 자동으로 키우는 구조를, 작동하는 코드와 실제 예시와 함께 철저히 풀어봅니다. 데일리 노트 생성, 웹 클립 정리, 백링크 보완, 플러그인 개발까지 실제로 쓸 수 있는 절차를 한 번에 소개합니다.

왜 Obsidian x Claude Code인가

Obsidian의 강점은 세 가지입니다.

• 로컬 우선: 모든 것이 내 컴퓨터 안의 Markdown 파일
• 플레인 텍스트: 벤더 종속이 없고, 미래에도 읽을 수 있음
• 링크 중심: [[노트명]]으로 사방팔방 링크하며 생각을 엮음

Claude Code의 강점과 딱 맞아떨어집니다.

• 파일 트리를 그대로 조작 가능 (Read / Edit / Write / Glob)
• Markdown을 일급 시민으로 취급 (Wikilink도 파싱 가능)
• CLAUDE.md로 “이 Vault 전용 규약”을 학습시킬 수 있음

요컨대 **Obsidian Vault는 Claude Code가 보기엔 “매우 잘 정돈된 작은 프로젝트”**입니다. 코드를 쓰는 것과 같은 감각으로 노트 정리도 자동화할 수 있습니다.

기본 셋업: Vault에 CLAUDE.md 두기

먼저 Vault 루트에 CLAUDE.md를 둡니다. 그러면 Vault 안에서 Claude Code를 실행할 때 자동으로 로드됩니다.

# My Obsidian Vault 규약

## 디렉토리 구조
- `daily/YYYY-MM-DD.md` — 데일리 노트
- `zettel/` — 영속 노트 (1노트 1아이디어, 제목은 개념명)
- `literature/` — 독서 메모, 웹 기사 클립
- `project/` — 진행 중 프로젝트
- `meta/` — 태그 정의, 템플릿

## 기법 규칙
- 노트 간 링크는 `[[노트명]]`으로 작성
- 태그는 본문 상단의 frontmatter에 기재
- 데일리 노트는 `## Today / ## Learned / ## Questions` 3계층 고정
- 참조 URL은 frontmatter의 `source:`에 기재

## 금지 사항
- 기존 노트 리네임은 반드시 확인받기 (백링크가 끊기므로)
- `_archive/` 하위 노트는 수정하지 말 것

Vault 규칙을 명시하면 Claude Code는 규약에 맞게 노트를 생성·편집해줍니다. 제각각인 서식으로 오염되는 사고를 막을 수 있습니다.

구현 예1: 데일리 노트 자동 생성

매일 아침 작업 시작 시, 어제 노트를 요약해 오늘 템플릿을 만드는 스크립트.

#!/bin/bash
# ~/vault/scripts/daily-note.sh

TODAY=$(date +%Y-%m-%d)
YESTERDAY=$(date -d "yesterday" +%Y-%m-%d)
VAULT=~/vault

claude -p "
다음을 실행해주세요:

1. $VAULT/daily/$YESTERDAY.md를 읽기 (없으면 건너뛰기)
2. 어제의 'Today' 섹션에서 '미완료 태스크' 추출
3. 어제의 'Learned' 섹션에서 '오늘의 회고 포인트' 3개 추출
4. $VAULT/daily/$TODAY.md를 만들고 아래 템플릿으로 채우기:

---
date: $TODAY
tags: [daily]
---

## Today (오늘 예정)
- (어제 미완료 태스크를 여기에)

## Learned (배움·발견)
_공백_

## Questions (궁금한 점·탐구 메모)
_공백_

## Review (어제 회고)
- (추출한 3개를 여기에)

## Links
[[$YESTERDAY]] <-> [[$(date -d tomorrow +%Y-%m-%d)]]
---

5. 만든 후에는 '데일리 노트 작성 완료'라고만 보고
"

cron이나 macOS launchd, Windows 작업 스케줄러에 등록해두면 아침에 일어났을 때 이미 오늘의 노트가 준비되어 있습니다. Obsidian을 여는 것만으로 작업에 들어갈 수 있습니다.

구현 예2: 웹 기사를 Vault에 클립

Read Later 용도입니다. URL만 넘기면 literature/ 디렉토리에 정돈된 노트가 저장되는 구조.

// scripts/clip-url.mjs
import Anthropic from "@anthropic-ai/sdk";
import { writeFileSync } from "fs";

const url = process.argv[2];
const client = new Anthropic();

const res = await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 4096,
  tools: [{ type: "web_search_20250101", name: "web_search" }],
  messages: [{
    role: "user",
    content: `아래 URL의 기사를 가져와서 Obsidian용 노트 생성:
URL: ${url}

출력 형식:
---
title: (기사 제목)
source: ${url}
tags: [literature, (기사의 주제 태그 2-3개)]
clipped: ${new Date().toISOString().slice(0, 10)}
---

# (기사 제목)

## TL;DR
(3줄 이내 요약)

## Key Points
- (중요 포인트 5개)

## My Take
_나중에 추가_

## Related
[[기존 Vault 내 관련 노트(추측 가능)]]
`,
  }],
});

const body = res.content[0].text;
const slug = body.match(/title: "(.+?)"/)?.[1]?.replace(/[\/:]/g, "-") ?? "untitled";
writeFileSync(`${process.env.VAULT}/literature/${slug}.md`, body);
console.log(`Clipped to literature/${slug}.md`);

사용법: node clip-url.mjs https://example.com/article

브라우저 우클릭 메뉴에 연결해두면 읽고 싶은 기사를 우클릭 한 번으로 Vault에 저장 → 나중에 검색 가능한 워크플로가 완성됩니다.

구현 예3: 백링크 자동 보완

Obsidian은 [[노트명]]으로 쓰면 백링크가 만들어지지만, **“이 노트, 그 개념과 관련 있는데 링크를 깜빡했네”**는 비일비재합니다. Claude Code로 일괄 보완.

claude -p "
$VAULT/zettel/ 내 모든 Markdown을 읽고 다음을 실행:

1. 각 노트의 본문에서 '중요한 개념·인물·이론명' 추출
2. 그 개념이 다른 노트의 제목으로 존재하는지 확인
3. 존재하는데 링크되지 않은 부분을 [[...]]로 감싸기
4. 노트 말미에 '## Related' 헤딩이 없으면 추가하고,
   본문에 자연스럽게 등장하지 않는 관련 노트를 2-3건 나열

변경 전에 diff를 표시하고 승인을 요청한 후 적용할 것.
"

포인트: 승인 플로우를 잊지 말 것. 백링크 자동 삽입은 편리하지만 잘못된 링크가 섞이면 Vault의 신뢰성이 무너집니다. “변경 전 diff 확인 후 적용”이 철칙.

구현 예4: 회의록을 노트화 + 태그 부여

음성 문자 변환이나 원본 텍스트 회의록을 구조화된 노트로 변환.

claude -p "
$VAULT/inbox/raw-meeting-2026-04-16.txt를 읽고, 아래 구조로
$VAULT/literature/meeting-2026-04-16.md에 저장:

---
title: '(회의 제목 추측)'
date: 2026-04-16
type: meeting
tags: [meeting, (주제로부터 추측한 태그)]
attendees: [(참석자 이름 추출)]
---

## 결정 사항
## Action Items (담당자·기한 포함)
## 논의 내용 (주제별 정리)
## 다음까지의 숙제

말미의 인물 언급 부분을 [[인물명]]으로 링크화.
끝나면 inbox/raw-meeting-2026-04-16.txt를 _archive/로 이동.
"

inbox에 원본 텍스트를 던져두면 나중에 일괄 변환할 수 있습니다.

구현 예5: Obsidian 플러그인 개발을 Claude Code로

Obsidian 플러그인은 TypeScript로 작성합니다. Claude Code는 TS에 능하므로 플러그인 개발과의 궁합이 발군.

cd ~/my-obsidian-plugin
claude

# Claude Code 내에서:
> main.ts를 읽고, 이 플러그인이 하는 일을 3줄로 설명해줘
> 새 기능 "선택한 텍스트를 Claude API로 요약해 커서 위치에 삽입"을 추가해줘
> manifest.json도 대응 버전으로 업데이트해줘
> npm run build가 통과하는지 확인해줘

몇 분 안에 작동하는 플러그인이 완성됩니다. Obsidian 플러그인 공식 샘플 저장소를 git clone하면 Claude Code가 그걸 기반으로 확장해줍니다.

Obsidian 고유 기법과의 상호작용

Claude Code가 알아야 할 Obsidian 특유의 기법:

기법	의미	예
[[노트명]]	Wikilink (내부 링크)	[[Claude Code]]
[[노트명#헤딩]]	특정 헤딩 링크	[[FAQ#요금]]
[[노트명|표시문자]]	별칭 링크	[[Claude Code|CC]]
![[노트명]]	노트 전체 임베드 표시	![[인용집]]
%%코멘트%%	공개 뷰에서 숨김 코멘트	%%TODO: 퇴고 요%%

CLAUDE.md에 명시해두면 Claude Code가 자연스럽게 구분해서 사용합니다.

함정 5선

1. 동기화 충돌 (Obsidian Sync / iCloud / Dropbox) Claude Code가 파일을 고쳐 쓰는 중 모바일에서 동기화가 돌면 충돌이 발생합니다. Claude Code 실행 중엔 동기화를 일시 정지하는 것이 안전. 자동화 스크립트 첫머리에 “Obsidian Sync pause” 명령을 넣는 방법도 있습니다.

2. 파일명에 쓸 수 없는 문자 Obsidian 노트 제목에 콜론 :이나 슬래시 /를 넣으면 OS 레벨에서 파일 생성이 실패합니다. Claude Code에게 생성시킬 때는 **“파일명은 알파벳·숫자·하이픈·한글만”**이라고 지시를 명시.

3. 백링크의 대량 재작성 노트 리네임을 자동화하면 백링크 업데이트 누락으로 링크 끊김이 발생합니다. 리네임은 Obsidian UI에서 실행하고, 파일 자체 이동은 Claude Code에 맡기지 않는 방침이 무난.

4. 플러그인 의존을 전제로 쓰게 됨 Dataview나 Templater에 의존한 기법을 Claude Code가 생성하면, 플러그인 미설치 환경에서 깨집니다. 표준 Markdown + Wikilink 범위에서 쓰도록 CLAUDE.md로 제약을 걸어두면 좋습니다.

5. 너무 큰 Vault에 일괄 실행 5,000노트 Vault에서 Glob **/*.md + 전체 읽기를 돌리면 컨텍스트가 터집니다. 서브에이전트에 “zettel 하위만” 같이 범위 한정해서 위임합시다.

워크플로 예: 하루의 흐름

제 운용 예를 소개합니다.

07:00  daily-note.sh 자동 기동, 오늘의 노트 생성
09:00  Obsidian 기동 → Today 섹션에 기입
12:00  웹 기사를 읽고 재밌으면 clip-url.mjs로 저장
15:00  회의, 회의록을 inbox/에 던져 넣기
17:00  claude로 회의록을 literature/에 정형
22:00  그날의 배움을 zettel/에 영속 노트화
심야   주간으로 backlink-suggest.sh를 돌려 백링크 보완

“쓰는 것”은 나, “정리하는 것”은 Claude Code라는 역할 분담이 잘 맞습니다. 나는 사고와 아이디어 도출에 집중하고, 정리와 연결의 수고는 AI에 넘긴다. 이것이 Obsidian x Claude Code의 진가입니다.

정리

Obsidian Vault는 “키우는 정원”에 비유되곤 합니다. Claude Code를 원예 로봇으로 고용하면 **물주기 (데일리 노트) / 잡초 뽑기 (백링크 정리) / 수확 (요약 생성)**을 모두 자동화할 수 있습니다.

오늘 시도할 수 있는 첫걸음은:

1. Vault 루트에 CLAUDE.md를 두고 규약 작성
2. daily-note.sh를 등록해 매일 아침 노트 자동화
3. clip-url.mjs를 도입해 웹 기사 원샷 클립

이 세 개만으로도 Vault와의 관계가 근본부터 달라집니다.

관련 기사

• 하니스 엔지니어링 완벽 가이드
• Claude Code의 서브에이전트 활용 패턴 10선
• CLAUDE.md 베스트 프랙티스

참고 자료

• Obsidian 공식 문서
• Obsidian 플러그인 개발 가이드
• Claude Code 공식 가이드