Obsidian 볼트를 Claude Code의 지식 베이스로 쓰기 — 실제로 되는 것과 안 되는 것

공식 연동 기능은 없다. 그런데도 잘 된다

먼저 오해부터 걷어내자. Obsidian과 Claude Code 사이에 공식 연동 기능은 존재하지 않는다. Obsidian 공식 문서에도, Anthropic의 Claude Code 문서에도 서로를 위한 전용 커넥터나 플러그인은 없다. 설치할 "연동 모듈" 같은 것을 찾고 있다면, 그런 건 없다.

Obsidian 공식 페이지

▲ Obsidian은 로컬 마크다운 파일을 그대로 쓰는 구조라, 외부 도구가 볼트에 접근하기 쉽다. (출처: obsidian.md 공식 페이지 캡처)

그런데도 이 조합이 성립하는 이유는 훨씬 시시하고, 그래서 훨씬 튼튼하다. Obsidian 볼트는 그냥 폴더이기 때문이다.

Obsidian 공식 문서는 볼트를 이렇게 정의한다. "여러분의 노트, 첨부파일, 그리고 Obsidian 전용 설정이 담긴 설정 폴더를 포함하는, 파일 시스템상의 한 폴더." 그리고 Obsidian 홈페이지는 저장 방식을 이렇게 못박는다. "Obsidian은 여러분의 노트를 로컬에 일반 텍스트 마크다운 파일로 저장한다."

한편 Claude Code는 공식 문서상 "코드베이스를 읽고, 파일을 수정하고, 명령을 실행하는 에이전틱 코딩 도구"다. 터미널에서 이렇게 시작한다.

cd your-project
claude

즉 Claude Code는 자신이 실행된 디렉터리의 파일을 읽고 쓴다. 볼트는 마크다운 파일이 들어 있는 디렉터리다. 여기서 끝이다. 볼트 폴더에서 claude를 실행하면, 그 순간부터 Claude Code에게 여러분의 노트는 그냥 작업 대상 파일이다. 별도의 API도, 웹훅도, 커넥터도 필요 없다.

패턴 1: 볼트 안에서 그냥 실행하기

가장 단순한 방법이다.

cd ~/Documents/MyVault
claude

이제 Claude Code는 볼트의 .md 파일들을 검색하고, 읽고, 새로 만들고, 고칠 수 있다. Obsidian은 파일 변경을 감지해 화면에 반영하므로, 에이전트가 파일을 고치면 앱에서도 바뀐 노트가 보인다.

패턴 2: 코드 저장소에서 작업하면서 볼트를 함께 열기

현실적으로 더 쓸모 있는 쪽은 이것이다. 코드는 저장소에 있고, 설계 메모·장애 기록·의사결정 로그는 볼트에 있다. Claude Code는 작업 디렉터리 밖의 디렉터리를 추가로 붙일 수 있다.

cd ~/git/my-service
claude --add-dir ~/Documents/MyVault

공식 문서 기준으로 --add-dir로 추가된 디렉터리는 원래 작업 디렉터리와 동일한 권한 규칙을 따른다. 읽기는 프롬프트 없이 되고, 편집은 현재 권한 모드를 따른다. 세션 도중에 붙이려면 /add-dir를, 매번 자동으로 붙이려면 설정 파일의 permissions.additionalDirectories를 쓰면 된다.

주의할 점이 하나 있다. 추가 디렉터리는 파일 접근 권한을 줄 뿐, 설정 루트가 되지는 않는다. 볼트 안의 CLAUDE.md를 함께 읽히고 싶다면 환경 변수를 켜야 한다.

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ~/Documents/MyVault

패턴 3: 볼트 루트에 CLAUDE.md를 두고 규칙을 고정하기

Claude Code는 세션이 시작될 때마다 작업 디렉터리의 CLAUDE.md를 읽는다. 볼트를 에이전트에게 맡길 생각이라면, 이 파일에 볼트의 규칙을 적어두는 것이 핵심이다. 노트 파일명 규칙, 프론트매터 형식, 태그 체계, 건드리면 안 되는 폴더 같은 것들이다.

공식 문서의 권고는 명확하다. 파일당 200줄 이내로 유지하고, 검증 가능할 만큼 구체적으로 쓰라는 것이다. "정리를 잘 해라" 대신 "일일 노트는 Daily/YYYY-MM-DD.md에 만든다"처럼 쓴다.

규칙이 늘어나면 .claude/rules/ 디렉터리로 쪼갤 수 있고, 각 규칙 파일에 paths 프론트매터를 달아 특정 파일 패턴에 걸릴 때만 로드되게 할 수도 있다.

---
paths:
  - "Daily/**/*.md"
---

# 일일 노트 규칙
- 프론트매터에 `date`, `tags`를 반드시 포함한다
- 기존 항목을 지우지 말고 아래에 덧붙인다

반드시 알아야 할 한계

여기서부터가 이 글의 진짜 요점이다.

CLAUDE.md는 강제가 아니다. Anthropic 공식 문서가 직접 명시한다. CLAUDE.md와 자동 메모리는 "설정이 아니라 컨텍스트"로 취급되며, 지시를 따르리라는 보장이 없다. 즉 "내 볼트의 이 폴더는 절대 수정하지 마"라고 CLAUDE.md에 써두는 것만으로는 보호가 되지 않는다.

진짜로 막으려면 권한 규칙을 써야 한다. Read/Edit 권한 규칙은 gitignore 패턴 문법을 따르며, 설정 파일의 permissions.deny에 넣는다. Obsidian의 설정 폴더를 에이전트로부터 지키고 싶다면 이런 식이다.

{
  "permissions": {
    "deny": [
      "Edit(.obsidian/**)"
    ]
  }
}

규칙 평가 순서는 deny → ask → allow이며, 어느 계층에서든 deny된 것은 다른 계층에서 allow할 수 없다. 더 강한 보장이 필요하면 PreToolUse 훅으로 차단하거나 샌드박스를 켠다.

그리고 볼트를 버전 관리하라. 이 조합의 본질은 "AI 에이전트에게 내 노트 폴더에 대한 쓰기 권한을 주는 것"이다. 에이전트는 파일을 직접 고친다. 볼트를 git 저장소로 만들어두면 마음에 들지 않는 변경을 되돌릴 수 있다. 이건 선택이 아니라 전제 조건에 가깝다.

서드파티 플러그인에 대하여

Obsidian 안에서 Claude Code를 띄우는 커뮤니티 플러그인들이 GitHub에 존재한다(예: deivid11/obsidian-claude-code-plugin). 다만 이들은 Obsidian이나 Anthropic이 만든 공식 제품이 아니라 개인 개발자의 서드파티 프로젝트다. 노트 전체에 대한 접근 권한을 주는 도구인 만큼, 설치 전에 코드와 관리 상태를 직접 확인할 것을 권한다.

정리

Obsidian ↔ Claude Code 공식 연동 기능은 없다.
필요도 없다. 볼트가 마크다운 파일이 든 폴더이고, Claude Code가 폴더의 파일을 다루는 도구이기 때문이다.
볼트에서 claude를 실행하거나, 코드 저장소에서 --add-dir로 볼트를 붙인다.
볼트 루트의 CLAUDE.md로 규칙을 주되, 그것은 강제가 아니다. 진짜 차단은 permissions.deny로 한다.
볼트를 git으로 관리하고 시작하라.