에이전트가 읽을 수 있는 Vault 만들기

Obsidian Vault 는 로컬 파일 시스템의 폴더다. 공식 문서에 그렇게 적혀 있고, 노트의 속성은 YAML frontmatter 로 파일 안에 들어간다. 그래서 에이전트가 Vault 를 읽는 데는 플러그인도 API 도 필요하지 않다 — 폴더를 가리키면 된다.

읽기가 공짜인 만큼, 정해야 하는 건 다른 쪽이다.

1. Git 으로 만든다

Vault 는 폴더이므로 그 자리에서 git init 이 된다. 이걸 먼저 하는 이유는 백업이 아니라 차이를 볼 수 있게 하는 것이다. 에이전트가 무엇을 고쳤는지 git diff 로 확인하고, 잘못됐으면 되돌린다.

cd /path/to/vault
git init
git add -A && git commit -m "vault: 에이전트 작업 전 기준점"

.gitignore 에 무엇을 넣을지는 Vault 안을 열어 확인한 뒤 정한다. Obsidian 설정은 Vault 루트의 .obsidian/ 에 JSON 몇 개로 들어간다 — app.json · appearance.json · core-plugins.json · community-plugins.json · graph.json · workspace.json.

여기서 갈라야 하는 건 “설정”과 “보기 상태”다. 앞의 넷은 실제로 설정을 바꿀 때만 변하지만, workspace.json(열린 탭·레이아웃)과 graph.json 은 쳐다보기만 해도 바뀐다. Vault 를 열고 그래프를 한 번 연 것만으로 graph.json 의 scale 값이 바뀌어 git status 가 더러워졌다. 노트는 하나도 안 고친 상태였다.

이게 왜 문제냐면, 5번의 승인 지점이 git diff 를 사람이 보는 것이기 때문이다. 의미 없는 diff 가 섞이면 그 게이트의 신호가 묻힌다.

그런데 graph.json 은 깔끔하게 안 갈린다. 한 파일에 설정과 상태가 같이 들어 있다. 그래프 뷰의 저장된 검색 필터, 태그·첨부 표시 여부, 색 그룹은 진짜 설정이고, 줌 배율과 패널 접힘은 보기 상태다. Obsidian 은 둘을 나눠주지 않는다.

graph.json 안의 값	성격
search (저장된 필터) · showTags · colorGroups	설정 — 머신 간에 맞추고 싶은 것
scale (줌) · close (패널 접힘)	상태 — 볼 때마다 바뀌는 것

그래서 이건 정리가 아니라 교환이다. 추적하면 매 세션 노이즈 diff 를 받고, 빼면 그래프 설정을 머신마다 다시 잡아야 한다. 나는 빼는 쪽을 골랐다 — 그래프 설정은 한 번 잡으면 거의 안 건드리는데 노이즈는 매번 오고, 무엇보다 승인 게이트를 흐리는 비용이 더 크다고 봤다. 그래프를 정교하게 쓰고 있다면 반대로 고를 만하다.

# .gitignore — 상태는 제외. graph.json 은 설정도 섞여 있어 교환이 있다
.obsidian/workspace.json
.obsidian/graph.json
.obsidian/plugins/   # 플러그인 바이너리(main.js)가 수 MB 씩 쌓인다

플러그인은 설치 목록이 community-plugins.json 에 남아 재설치가 되므로, 바이너리까지 이력에 넣을 이유가 없다.

2. 지침을 Vault 루트에 둔다

AGENTS.md 는 여러 코딩 에이전트가 읽는 관례이고, Claude Code 는 CLAUDE.md 를 읽는다(AGENTS.md 글에 정리해뒀다). Vault 도 결국 마크다운 폴더이므로 같은 방식이 그대로 통한다. Obsidian 쪽에서는 그냥 노트 하나로 보이고, 에이전트 쪽에서는 규칙으로 읽힌다.

# 이 Vault 에서 일하는 규칙

## 구조
- 노트 유형은 type 속성으로 구분한다: project / reference / thought / inbox
- 링크는 [[노트 이름]] 형식이다. 이름이 곧 식별자다

## 해도 되는 것
- inbox/ 안의 노트를 유형별 폴더로 옮기고 속성을 채운다
- reference 노트의 source 를 열어 verified 날짜를 갱신한다

## 하지 말 것
- 노트 이름을 바꾸지 않는다 (링크가 이름 기반이다)
- 여러 노트를 한 번에 재구성하지 않는다
- 판단이 담긴 thought 노트의 문장을 고쳐쓰지 않는다 — 제안만 남긴다

## 완료 판정
- git diff 로 변경을 확인할 수 있어야 한다
- 새로 만든 노트는 반드시 type 속성이 있다

“하지 말 것”과 “완료 판정”이 실제로 값을 한다. 지침은 강제가 아니라 컨텍스트라서 어길 수 있지만, 적어두면 어긋났을 때 무엇이 어긋났는지 말할 수 있다.

3. 속성 이름을 고정한다

속성은 YAML frontmatter 의 이름: 값 이고, 이름은 자유롭게 정할 수 있다. 자유롭다는 게 문제다 — status, 상태, state 를 섞어 쓰면 에이전트는 그중 무엇이 진짜인지 추론해야 하고, 추론은 틀린다.

노트 유형 글에서 정한 유형별 속성을 지침에 그대로 적어두면 추론할 일이 없어진다. 새 속성이 필요하면 에이전트가 만들지 않고 물어보게 한다.

4. 쓸 자리를 정한다

읽기는 Vault 전체로 열어도 되지만, 쓰기는 폴더로 좁힌다. 처음에는 수집 폴더 하나만 열어주는 게 무난하다 — 그 폴더는 원래 정리되지 않은 상태이고, 무엇이 잘못돼도 잃을 게 적다.

Vault 를 프로젝트별로 여러 개 둘 수 있다는 점도 여기서 쓸모가 있다. 공식 문서에 “하나의 Vault 에 전부 두거나, 프로젝트마다 여러 Vault 를 만들 수 있다”고 적혀 있다. 에이전트를 붙여 시험할 때는 작은 Vault 를 따로 만들어 거기서 먼저 돌려보는 편이 낫다.

5. 승인 지점을 둔다

커밋 전에 사람이 git diff 를 본다. 이 한 줄이 승인 게이트의 가장 단순한 형태다. 자동 커밋까지 넘기는 건 다음 문제이고, 그때도 조건은 같다 — 되돌릴 수 있고, 실패가 사람에게 닿을 때만.

무엇을 넘기고 무엇을 넘기지 않나

넘긴다

• 정해진 폴더에 새 노트 만들기
• 속성 채우기·정리
• 링크 후보 제안 (걸지는 않고)
• 레퍼런스 노트의 출처 확인·날짜 갱신

↔

넘기지 않는다

• Vault 전체 재구성
• 노트 이름 일괄 변경
• 설정 파일 수정
• 판단이 담긴 노트 고쳐쓰기

오른쪽 두 번째가 가장 위험하다. 링크는 노트 이름을 가리킨다. Obsidian 에는 이름을 바꿀 때 내부 링크를 자동으로 갱신하는 옵션이 있는데, 처음엔 그게 “Obsidian 이 그 변경을 알 때”의 이야기라고 적었다. 직접 시험해보니 그 짐작이 틀렸다.

Obsidian 은 외부 이름 변경을 안다. CLI 에서 mv 로 파일 이름을 바꾸자 파일 탐색기가 곧바로 새 이름으로 갱신됐다. 그런데도 그 노트를 가리키던 [[링크]] 는 고쳐주지 않았다. 링크를 담고 있던 파일은 바이트 하나 안 바뀌었고(해시 동일), 화면에서는 그 링크가 흐린 색으로 변했다 — 같은 색상에 투명도만 낮춘, Obsidian 이 “가리키는 노트가 없다”를 표시하는 방식이다.

링크	색	뜻
옛 이름을 가리킴	#7a6bb2 (흐림)	끊김 — 클릭하면 새 노트를 만들자고 한다
실제 있는 노트	#a28cf2 (밝음)	살아있음

그래서 결론은 그대로다 — 이름 변경은 에이전트에게 넘기지 않는다. 다만 이유가 달라졌다. “Obsidian 이 모를 수 있어서”가 아니라, 알면서도 안 고쳐주기 때문이다. 링크 자동 갱신은 이름 변경이 Obsidian 안에서 일어날 때만 작동한다.

같은 이유로 .canvas 파일도 조심스럽다. Canvas 데이터는 JSON Canvas 형식으로 저장되는데, 그 안에는 카드 위치 같은 좌표가 많다. 사람이 보기에는 관계도지만 에이전트가 텍스트로 읽으면 대부분이 노이즈다. 관계를 정리하게 하려면 Canvas 보다 노트의 링크를 쓰게 하는 편이 낫다.

시험해서 확인한 것

초안을 쓸 때 네 가지를 모른다고 적어뒀다. 공식 문서에 답이 없어서 짐작으로 메우지 않고 남겨둔 자리였다. 실제로 쓰고 있는 Vault(노트 130여 개)를 열어놓고 CLI 로 하나씩 쳐봤다.

몰랐던 것	확인 결과
열려 있을 때 외부가 파일을 고치면	조용히 자동 갱신된다. 경고도 충돌 안내도 없다. 열려 있던 편집기가 옛 내용으로 되돌리지도 않았다
외부에서 이름을 바꾸면 링크가	안 따라온다. 파일 목록은 즉시 갱신되는데 [[링크]] 는 그대로 남아 끊긴다
설정 파일이 커밋에 섞이면	깨지진 않는다. 대신 보기 상태가 계속 diff 로 뜬다 — 그래프를 열기만 해도 graph.json 이 변한다
에이전트가 만든 노트를 인식하는지	즉시 뜬다. 재시작 불필요. [[링크]] 의 백링크까지 그 자리에서 잡힌다

세 번째 줄이 이 문서의 5번(승인 지점)과 직접 이어진다. 커밋 전에 사람이 git diff 를 본다는 게 게이트인데, 노이즈가 섞이면 그 게이트가 눈에 안 들어온다. 보기 상태 파일을 빼는 건 정리 취향이 아니라 게이트를 살리는 일이다.

첫 줄과 둘째 줄이 갈리는 게 실무에서 제일 쓸모 있다. 파일 내용을 고치는 일은 넘겨도 된다 — Obsidian 이 알아서 따라온다. 이름을 바꾸는 일은 넘기지 않는다 — Obsidian 이 알면서도 안 고쳐준다. 넘길 것과 넘기지 않을 것의 경계가 여기서 한 번 더 선명해진다.

아직 확인 못 한 것

• 에이전트에게 쓰기를 실제로 맡기고 한동안 운영했을 때 무엇이 어긋나는지. 위는 전부 단발 동작 시험이다
• 동기화(Obsidian Sync·iCloud 등)를 켠 상태에서 외부 편집이 어떻게 되는지 — 시험한 Vault 는 Git 만 쓴다
• 여러 노트를 한 번에 고칠 때 자동 갱신이 어디까지 따라오는지

이 문서를 덮어도 되는 시점

git init 을 했고, 지침 파일에 “하지 말 것” 세 줄이 적혀 있고, 에이전트가 쓸 폴더가 하나로 정해져 있으면 된다. 나머지는 그 위에서 늘린다.

변경 로그

• 2026-07-26초안 작성(근거: 일부 경험 + 조사). 다섯 단계, 넘길 일과 넘기지 않을 일의 경계, 지침 파일 예시. Vault 대상 실행은 미검증이고 확인 못 한 항목 네 가지를 명시 (성숙도: 탐색 중)
• 2026-07-28실제로 쓰는 Vault 에서 네 항목 전부 시험해 답을 채웠다. 짐작 하나가 틀렸다 — 외부 이름 변경을 Obsidian 이 “모를 것”이라고 썼는데, 알면서도 링크를 안 고친다. 설정 파일 위치와 보기 상태 노이즈(graph.json)를 1번 단계에 반영. 단발 동작은 검증됐고 지속 운영은 아직이라 근거는 mixed 유지
• 2026-07-28정정 — graph.json 을 “보기 상태”로만 소개했는데 부정확했다. 저장된 검색 필터·색 그룹 같은 진짜 설정도 같은 파일에 섞여 있어서 무손실 선택지가 없다. 깔끔한 정리가 아니라 교환이라는 점을 그림 1 로 명시
• 예정에이전트에게 쓰기를 맡기고 한동안 운영한 뒤 practiced 로 올린다 · 동기화를 켠 Vault 에서 외부 편집이 어떻게 되는지