
기획이나 설계 메모는 옵시디언(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-skillsCodex는 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/downloadObsidian은 앱이 스스로 업데이트되기 때문에 앱 버전과 설치 파일 버전이 따로 있어요. 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


