옵시디언 + 깃허브: AI와 함께 쓰는 노트 만들기

옵시디언은 LLM이 일반화되면서 가장 강력한 포지션을 갖게 된 노트앱이라고 생각합니다. 이유는 하나입니다. md 파일과 폴더로만 이루어진 구조가 사람과 AI 사이의 노트 공유 간극을 무너트렸기 때문입니다.

다른 노트앱은 자기만의 포맷과 데이터베이스 안에 노트를 넣어둡니다. AI가 그 노트를 읽으려면 공식 API가 열려 있거나, 익스포트를 한 번 거쳐야 합니다. 옵시디언 볼트는 그냥 디렉토리입니다. 에이전트가 cat으로 읽고, grep으로 찾고, 파일을 열어서 고칩니다. 노트를 넘기기 위해 따로 해야 할 일이 없습니다.

이 차이는 생각보다 큽니다. 노트 앱을 바꿀 때마다 겪는 익스포트 지옥이 없어지는 것에서 끝나지 않습니다. AI가 노트를 읽는 방식이 제가 노트를 읽는 방식과 같아집니다. 제가 보는 화면과 에이전트가 보는 텍스트 사이에 변환 계층이 없으니, “그 파일 세 번째 문단 고쳐줘” 같은 말이 그대로 통합니다. 프론트매터도, 태그도, 링크도 전부 그냥 글자입니다.

그런데 로컬 폴더 하나만으로는 부족합니다. 백업이 없고, 노트북에서 쓴 글이 폰에 없습니다. 여기에 깃허브를 붙여서 백업과 디바이스 간 공유를 해결하면 거의 완벽한, AI와 함께 쓰는 노트가 됩니다.

볼트를 깃 저장소로 만들기

볼트 폴더가 그대로 저장소 루트가 됩니다. 별도 구조를 만들 필요는 없습니다.

cd ~/Obsidian
git init

첫 커밋 전에 .gitignore부터 씁니다.

.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/

workspace.json은 어떤 패널을 열어놨고 어떤 탭이 활성인지 같은 화면 상태만 담고 있습니다. 노트 데이터가 아닙니다. 그리고 디바이스마다 값이 다릅니다. 여러 기기에서 동기화할 때 나는 충돌은 대부분 이 파일에서 납니다. 처음부터 빼두는 게 낫습니다.

.obsidian 폴더를 통째로 무시하는 방법도 있습니다. 그러면 저장소는 순수하게 노트만 담게 되는데, 대신 플러그인·테마·핫키 설정이 기기를 따라오지 않습니다. 저는 워크스페이스 파일 두 개만 빼고 나머지 설정은 커밋하는 쪽을 씁니다. 새 기기에서 클론하면 세팅이 그대로 따라오는 게 편해서입니다.

첨부 파일은 한 번 생각하고 넘어가는 게 좋습니다. 텍스트 노트는 아무리 쌓여도 저장소가 가벼운 반면, 이미지와 PDF는 다릅니다. 깃은 바이너리를 고칠 때마다 통째로 새 버전을 저장하기 때문에, 스크린샷을 잔뜩 붙이는 볼트라면 저장소가 노트 용량과 상관없이 계속 불어납니다. 클론이 느려지기 시작하면 그때가 첨부 폴더를 무시 목록에 넣을지 결정할 때입니다.

이제 깃허브에 프라이빗 저장소를 만들고 연결합니다.

git remote add origin [email protected]:username/my-vault.git
git add .
git commit -m "Initial vault"
git push -u origin main

저장소는 반드시 프라이빗으로 만드세요. 노트에는 사람 이름도 있고, 아직 아무한테도 안 꺼낸 아이디어도 있습니다. 공개로 만들어놓고 나중에 비공개로 돌려도 이미 나간 건 나간 겁니다.

커밋을 손으로 안 하기

데스크톱에서는 그냥 git을 쓰면 됩니다. 하지만 글을 쓰다 말고 터미널로 넘어가 커밋하는 습관은 오래 못 갑니다. 며칠 지나면 안 하게 됩니다.

그래서 커뮤니티 플러그인 목록에서 Git(obsidian-git, Vinzent03)을 설치합니다. 주기적으로 자동 커밋과 푸시를 돌려주고, 사이드 패널에서 스테이징·커밋·디프·히스토리를 볼 수 있습니다. 저는 자동 커밋 간격만 정해두고 그 뒤로는 신경 쓰지 않습니다.

모바일은 사정이 조금 다릅니다. 이 플러그인은 모바일에서 isomorphic-git이라는 자바스크립트 구현체로 동작합니다. iOS와 안드로이드에서는 플러그인이 네이티브 git을 쓸 수 없기 때문입니다. 개발자도 README에서 모바일에는 제약이 많다고 직접 밝혀놨습니다. 그렇다고 포기할 일은 아닙니다. 저는 아이폰에서도 이 볼트를 쓰고 있습니다. 설정이 꽤 까다로운데, 한번 잡아두면 생각보다 잘 동작합니다. 그 세팅은 따로 정리할 생각입니다.

기기를 두 대 이상 쓰면 결국 충돌이 납니다. 노트북에서 고친 문서를 데스크톱에서도 고쳐놓고 둘 다 푸시하려 할 때요. 여기서도 md 파일이라는 게 이득입니다. 충돌 표시가 그대로 텍스트로 파일에 박히기 때문에, 옵시디언에서 그 노트를 열어 어느 쪽을 남길지 고르고 표시만 지우면 끝납니다. 바이너리 포맷이었으면 앱이 알아서 한쪽을 골랐을 테고, 무엇이 사라졌는지는 영영 몰랐을 겁니다. 습관 하나면 빈도가 확 줄어듭니다. 노트를 열기 전에 먼저 당기는 겁니다.

폴더는 숫자로 줄 세웁니다

옵시디언은 폴더를 규칙에 따라서만 정렬할 수 있습니다. 다른 노트앱처럼 폴더를 위아래로 끌어서 원하는 자리에 고정할 수 없습니다.

그래서 제가 쓰는 방법은 숫자를 앞에 붙이는 것입니다.

01_Ideas
02_Video-Scripts
03_Reference
04_Blogs

파일 탐색기 정렬을 이름 오름차순에 두면, 자연스럽게 제가 원하는 순서대로 폴더가 정렬됩니다. 한 자리가 아니라 두 자리를 쓰는 이유는 폴더가 열 개를 넘어가는 순간 1, 10, 11, 2 순서가 되기 때문입니다.

덤으로 AI한테도 이득입니다. 폴더 이름이 곧 분류라서 “이거 03_Reference에 정리해줘” 한마디면 지시가 끝납니다. 어디에 넣을지 설명할 필요가 없습니다.

이렇게 하면 뭐가 열리는가

노트가 깃허브에 올라가 있으면, 깃허브를 읽을 수 있는 도구는 전부 제 노트를 읽을 수 있습니다.

코딩 에이전트는 볼트 폴더를 그냥 작업 디렉토리로 엽니다. 검색해서 찾고, 초안을 새 파일로 씁니다. 흩어져 있던 메모 여러 개를 한 문서로 합치는 일도 여기서 합니다. 깃허브에 접근할 수 있는 챗봇이라면 클론 없이도 저장소를 읽을 수 있습니다.

여기서 진짜로 달라지는 건 히스토리입니다. AI가 노트를 고쳐도 커밋 하나로 남습니다. 무엇을 바꿨는지 diff로 확인하고, 마음에 안 들면 되돌립니다. AI에게 쓰기 권한을 주는 게 무섭지 않은 이유가 이겁니다. 백업은 부수적이고, 되돌릴 수 있다는 게 본론입니다.

챗GPT를 이 볼트에 연결하는 방법은 이어지는 가이드에서 다룹니다.