Obsidian Claude Code 연동: 볼트 연결과 설정 방법
기획이나 설계 메모는 옵시디언(Obsidian)에 쌓여 있는데, 코딩 에이전트는 코드 저장소만 보고 일하죠. 이 글은 Obsidian과 Claude Code를 연동해서, 볼트(vault)의 노트를 Claude Code나 Codex 같은 코딩 에이전트가 읽고 쓸 수 있게 만드는 설정을 순서대로 정리했어요. 노트를 지시서로 쓰는 법이나 이슈로 쪼개는 법은 이전 글에서 다뤘어요. 이번에는 그 앞 단계인 연결과 설정만 다뤄요. 폴더를 어떻게 잇는지, 규칙 파일에 무엇을 적는지, 노트가 망가지지 않게 무엇을 걸어두는지, 그리고 Obsidian이 공식으로 내놓은 스킬과 CLI를 어떻게 쓰는지예요. Obsidian 볼트와 코드 저장소를 연결하는 방법 볼트는 결국 마크다운 파일이 든 폴더예요. 그래서 에이전트 입장에서는 "그 폴더에 접근할 수 있느냐"만 풀면 돼요. Dylan Boudro가 쓴 Obsidian + Claude Code 통합 가이드는 여러 연결 방식을 나눠서 소개하는데, 코딩에 쓰기 좋은 건 이 세 가지예요. 방식 어떻게 잘 맞는 경우 볼트를 작업 폴더로 볼트 루트에서 에이전트를 실행해요 노트 정리, 기획, 스펙 작성이 중심일 때 심볼릭 링크 볼트 안에 코드 저장소로 가는 링크를 만들어요 볼트 하나로 여러 프로젝트를 볼 때 저장소마다 볼트 저장소 자체를 볼트로 열어요 문서를 코드와 같이 버전 관리할 때 심볼릭 링크는 명령 한 줄이면 돼요. 볼트 폴더 안에서 실행해요. 볼트 안에 my-app이라는 이름으로 코드 저장소를 연결해요 ln -s ~/projects/my-app my-app 같은 가이드는 주의할 점도 적어뒀어요. 심볼릭 링크는 Obsidian 모바일에서 문제를 일으킬 수 있고, 저장소마다 볼트를 둘 때는 .obsidian/ 폴더를 .gitignore에 넣으라고 해요. Claude Code를 쓴다면 방법이 하나 더 있어요. 코드 저장소에서 실행하면서 --add-dir 옵션으로 볼트 폴더를 추가로 열어주는 거예요. 작업 폴더는 코드 저장소 그대로 두고, 노트도 함께 읽게 할 수 있어요. 코드 저장소에서 실행하면서 볼트 폴더도 함께 열어요 claude --add-dir ~/vault 다만 이 방식은 파일 접근만 열어줘요. Claude Code 메모리 문서에 따르면 --add-dir로 추가한 폴더의 지침 파일은 기본으로는 읽히지 않아요. CLAUDE.md는 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 환경 변수를 켜면 읽히지만, AGENTS.md는 그래도 읽히지 않아요. 아래에서 다룰 볼트의 권한 규칙도 이 방식에서는 적용되지 않아요. 규칙과 권한까지 쓰려면 볼트 루트에서 실행하세요. 볼트 루트에 AGENTS.md로 규칙 적기 연결만 해두면 에이전트는 볼트가 어떤 곳인지 몰라요. 어느 폴더에 무엇이 있고, 무엇을 건드리면 안 되는지 알려줘야 해요. 이 역할을 하는 게 볼트 루트의 지침 파일이에요. 저는 AGENTS.md 하나만 둬요. Codex가 읽는 파일이고, 같은 메모리 문서에 따르면 Claude Code도 v2.1.277부터는 CLAUDE.md가 없을 때 AGENTS.md를 직접 읽거든요. 파일이 하나면 에이전트마다 같은 내용을 맞춰둘 일이 없어요. 그보다 오래된 Claude Code를 쓴다면 @AGENTS.md 한 줄만 적은 CLAUDE.md를 옆에 두면 돼요. Kenneth Reitz는 Obsidian 볼트와 Claude Code를 함께 쓰는 글에서 이 파일에 볼트 개요, 작성 규칙, 하지 말아야 할 것의 목록을 적는다고 소개해요. 이 구성을 코딩용으로 옮기면 이런 모양이 돼요. 볼트 안내 구조 - `specs/` 기능별 스펙과 설계 메모 - `decisions/` 기술 결정과 그 이유 - `tasks/` 에이전트에게 맡기는 작업 노트 - `sources/` 외부 자료 원문 작성 규칙 - 노트끼리는 `[[위키링크]]`로 연결한다 - 새 노트에는 frontmatter에 `type`, `status`, `date`를 적는다 하지 말 것 - 요청받지 않은 새 파일을 만들지 않는다 - `sources/`는 고치거나 옮기거나 지우지 않는다 - 기존 노트를 고치기 전에 바꿀 파일 목록을 먼저 보여준다 하지 말 것이 가장 중요해요. 에이전트는 시키지 않은 정리까지 친절하게 해버리는 경우가 많거든요. 코드는 테스트가 잘못된 변경을 잡아주지만, 노트에는 그런 장치가 없어요. 에이전트가 노트를 건드리기 전에 걸어둘 안전장치 지침 파일은 부탁일 뿐이에요. Adam Reed는 노트를 잃지 않고 Claude Code와 Obsidian을 쓰는 법에서, 경계를 실제로 지켜주는 건 Claude Code의 권한 설정과 진짜 백업뿐이라고 짚어요. 이 글에서 코딩 작업에도 그대로 쓸 수 있는 건 이 정도예요. Git 체크포인트부터 만들어요 — 에이전트가 볼트를 건드리기 전에 커밋을 하나 남겨요. 동기화는 백업이 아니라는 점도 함께 짚어요. 폴더마다 역할을 정해요 — 원문 폴더는 읽기 전용, 기존 노트는 수정 전에 제안 먼저, 에이전트가 자유롭게 쓰는 출력 폴더는 따로 두는 식이에요. 읽기만 하는 작업으로 시작해요 — 처음에는 계획 모드로 볼트를 살펴보게 하고, 그다음 파일 하나만 써보게 해요. 끝날 때마다 변경을 확인해요 — git status --short와 git diff로 무엇이 바뀌었는지 봐요. 볼트 루트에서 Claude Code를 실행한다면, 에이전트의 편집 도구가 원문 폴더를 고치지 못하게 권한 규칙으로 막을 수 있어요. 볼트의 .claude/settings.json에 거부(deny) 규칙을 넣어요. { "permissions": { "deny": ["Edit(/sources/**)"] } } Claude Code 권한 문서에 따르면 프로젝트 설정에서 /로 시작하는 경로는 프로젝트 루트 기준이에요. 그리고 규칙은 거부, 확인, 허용 순서로 평가돼서, 거부 규칙에 걸린 경로는 허용 규칙으로 다시 열 수 없어요. 이 규칙이 막는 건 파일 편집이에요. 셸에서 실행하는 rm이나 mv는 Bash(rm *) 같은 규칙을 따로 넣어야 하고, 같은 문서는 Bash 규칙이 보안 경계는 아니라고 적어뒀어요. 그래서 1번의 Git 체크포인트가 마지막 안전망이에요. obsidian-skills로 에이전트에게 Obsidian 문법 가르치기 위키링크, 콜아웃, 속성(properties) 같은 Obsidian 고유 문법은 일반 마크다운과 달라서, 에이전트에게 따로 알려줘야 해요. Obsidian이 공식으로 관리하는 obsidian-skills 저장소가 이 부분을 채워줘요. 에이전트 스킬(Agent Skills)은 에이전트가 필요할 때 읽어 들이는 지침 묶음이에요. 저장소 설명에 따르면 Agent Skills 규격을 따르기 때문에 Claude Code, Codex, OpenCode처럼 스킬을 지원하는 에이전트에서 함께 쓸 수 있어요. 스킬 가르치는 것 obsidian-markdown 위키링크, 임베드, 콜아웃, 속성 같은 Obsidian 마크다운 obsidian-bases 뷰, 필터, 수식이 들어가는 Bases(.base) 파일 json-canvas 노드와 연결선으로 된 JSON Canvas(.canvas) 파일 obsidian-cli Obsidian CLI로 볼트 다루기 obsidian-headless 데스크톱 앱 없이 볼트 동기화와 게시 defuddle 웹 페이지에서 군더더기를 뺀 마크다운 추출 knap JSON, CSV 데이터로 마크다운 템플릿 채우기 설치 명령은 저장소 README에 나와 있어요. Claude Code에서는 플러그인으로 설치해요. Claude Code에 obsidian-skills 마켓플레이스를 추가하고 설치해요 claude plugin marketplace add obsidianmd/obsidian-skills claude plugin install obsidian@obsidian-skills Codex는 README 기준으로 codex plugin marketplace add obsidianmd/obsidian-skills를 실행한 뒤 플러그인 목록에서 Obsidian을 설치해요. 직접 넣고 싶다면 저장소의 plugins/obsidian/skills/ 폴더를 Claude Code는 볼트 루트의 .claude/skills/에, Codex는 ~/.agents/skills에 복사하면 돼요. Obsidian CLI로 볼트 검색하고 노트 읽기 에이전트는 파일을 직접 열어 읽을 수도 있지만, Obsidian CLI를 쓰면 Obsidian이 이미 만들어둔 검색, 태그, 백링크 정보를 터미널 명령으로 꺼내 쓸 수 있어요. 앞에서 본 Starmorph 가이드도 Claude Code와 Obsidian을 잇는 방법 가운데 CLI를 가장 빠르고 토큰 효율이 좋은 방법으로 꼽아요. Obsidian CLI 켜기 Obsidian CLI 공식 문서에 따르면 Obsidian 1.12 설치 파일이 필요하고, 설정은 이렇게 해요. Obsidian 설치 파일을 최신 버전(1.12.7 이상)으로 올려요. Settings → General에서 Command line interface를 켜요. 안내에 따라 CLI를 등록하고 터미널을 다시 열어요. 하나 알아둘 점이 있어요. CLI는 실행 중인 Obsidian 앱에 연결해서 동작해요. 앱이 꺼져 있으면 첫 명령이 Obsidian을 띄워요. 데스크톱 앱 없이 동기화가 필요한 경우에는 문서가 Obsidian Headless를 따로 안내해요. 에이전트가 자주 쓰는 읽기 명령 매개변수는 이름=값 형태로 써요. 아래 명령은 제 블로그 볼트에서 실행해본 것들이에요. 쓸 수 있는 명령 전체 보기 obsidian help 볼트에서 키워드 검색 (결과는 노트 경로 목록) obsidian vault=blog search query="Obsidian" limit=3 노트 내용 읽기 obsidian vault=blog read path="posts/202610012001.md" 태그를 사용 횟수 순으로 보기 obsidian vault=blog tags counts sort=count 볼트 지정 — vault=이름은 맨 앞에 써요. 터미널의 현재 폴더가 볼트 안이면 그 볼트가 쓰이니 생략해도 돼요. 파일 지정 — file=은 위키링크처럼 이름만으로 찾고, path=는 볼트 루트부터의 정확한 경로를 받아요. 이 밖에 backlinks, tasks, property:read 같은 명령도 있어요. 노트를 만들거나 덧붙이는 create, append도 있지만, 처음에는 읽기 명령만 쓰게 하는 편이 안전해요. "Your Obsidian installer is out of date" 경고가 뜰 때 앱은 최신인데 설치 파일이 오래된 경우 명령을 실행할 때마다 이 문구가 나와요. Your Obsidian installer is out of date. Please download the latest installer which includes better CLI support: https://obsidian.md/download Obsidian은 앱이 스스로 업데이트되기 때문에 앱 버전과 설치 파일 버전이 따로 있어요. obsidian version을 실행하면 1.15.1 (installer 1.8.4)처럼 둘 다 보여줘요. 경고가 떠도 위의 읽기 명령은 동작했지만, 공식 문서가 요구하는 대로 다운로드 페이지에서 설치 파일을 새로 받아 설치하는 게 맞아요. 저도 새로 설치한 뒤에는 1.15.1 (installer 1.15.1)로 바뀌고 경고가 사라졌어요. 연결한 뒤에는 노트를 작업 지시서로 써요 여기까지 하면 에이전트가 볼트를 읽고, 규칙을 알고, 함부로 망가뜨리지 못하는 상태가 돼요. 이제 노트에 무엇을 적어서 맡길지가 남아요. 작업 하나를 노트 한 장에 적는 형식은 Obsidian 노트를 AI 에이전트 작업 지시서로 쓰기에 있어요. 아이디어 노트를 PR 하나 크기의 이슈로 나누는 방법은 AI 에이전트 워크플로우: 아이디어를 완료 조건 있는 이슈로 쪼개기에 정리했어요. 노트를 감시해서 에이전트를 자동으로 돌리고 싶어진다면, 먼저 마크다운으로 AI 에이전트 작업 자동화할 때 챙길 것을 읽어보세요. 직접 만들어 굴려본 뒤에 남긴 기록이에요. 폴더 하나와 규칙 파일 하나부터 한 번에 다 갖출 필요는 없어요. 오늘은 볼트에 Git 커밋을 하나 남기고, 볼트 루트에 AGENTS.md를 만들어 구조와 하지 말 것만 적어보세요. 그 상태에서 에이전트에게 읽기만 하는 질문을 하나 던져보면, 스킬과 CLI 중에 무엇이 더 필요한지가 보여요. If you do what you've always done, you'll get what youve always gotten.— Tony Robbins