Claude Code 세션마다 프로젝트 배경을 다시 설명하는 비효율을 해결하는 Obsidian Mind, 설치 5단계와 첫 세션 실행까지 10분이면 완료됩니다.
Claude Code로 업무를 하다 보면 한 가지 패턴을 반복하게 됩니다. 어제 정리한 프로젝트 방향을 오늘 다시 설명하고, 지난주에 내린 기술 결정을 또 전달하는 것입니다. 세션이 바뀌면 맥락이 초기화되기 때문입니다.
Obsidian Mind는 이런 반복을 구조적으로 없애주는 볼트 템플릿입니다. GitHub에서 클론 한 번이면 CLAUDE.md 운영 매뉴얼, SessionStart 훅, North Star 목표 파일이 포함된 완성된 구조가 준비되고, 첫 세션부터 Claude Code가 볼트의 맥락을 자동으로 파악합니다.
이 글에서는 Obsidian Mind를 처음 설치하는 과정부터 첫 세션을 실행하고 "start session" 커맨드로 컨텍스트가 주입되는 것을 확인하는 단계까지, 초보자도 따라 할 수 있도록 단계별로 안내합니다.
🛠️ 준비물
- Obsidian 1.12 이상 (CLI 지원 필수)
- Claude Code (Anthropic 구독 필요)
- Git (터미널에서
git --version으로 확인) - 터미널 기본 사용 가능 환경 (macOS Terminal, Linux Shell, Windows WSL)
⚠️ 윈도우 사용자: 이 글은 macOS/Linux 기준으로 작성되었습니다. 윈도우11 환경에서의 Claude Code 설치(네이티브/WSL2 선택)와 경로 설정은 윈도우11 전용 설치 가이드를 먼저 참고하신 뒤, 이 글의 볼트 설정 단계부터 이어서 진행하는 것을 권장합니다.
⏱️ 예상 소요시간: 약 10~15분
☐ 오늘 할 일
- ☐ Obsidian과 Claude Code 버전 확인
- ☐ obsidian-mind 저장소 클론
- ☐ Obsidian에서 볼트로 열기 + CLI 활성화
- ☐ 볼트 디렉터리에서 Claude Code 실행
- ☐ North Star 목표 파일 작성
- ☐ "start session" 커맨드로 컨텍스트 주입 확인
설치 전 확인 사항
설치를 시작하기 전에 필요한 도구가 제대로 설치되어 있는지 확인합니다. 터미널을 열고 아래 커맨드를 각각 실행해 보세요.
| 확인 항목 | 터미널 커맨드 | 기대 결과 |
|---|---|---|
| Git | git --version |
git version 2.x.x 이상 |
| Claude Code | claude --version |
버전 번호 표시 |
| Node.js (Claude Code 의존) | node --version |
v18 이상 권장 |
Obsidian은 버전 1.12 이상이어야 CLI(명령줄 인터페이스) 기능을 사용할 수 있습니다. Obsidian 앱의 설정 → 일반 → 정보에서 현재 버전을 확인할 수 있습니다. Obsidian Mind의 전체 기능과 구조가 궁금하다면 Obsidian Mind 핵심 기능 정리를 먼저 읽어보시는 것을 권장합니다.
초보 따라하기 — 설치 5단계
Step 1. 저장소 클론
터미널을 열고 원하는 디렉터리로 이동한 뒤 아래 커맨드를 실행합니다.
git clone https://github.com/breferrari/obsidian-mind.git ~/obsidian-mind홈 디렉터리 아래에 obsidian-mind 폴더가 생성됩니다. 경로는 자유롭게 바꿀 수 있지만, 공백이 포함된 경로는 피하는 것을 권장합니다.
Step 2. Obsidian에서 볼트로 열기
Obsidian을 실행하고 왼쪽 하단의 "볼트 열기(Open folder as vault)"를 선택합니다. Step 1에서 클론한 ~/obsidian-mind 폴더를 선택하면 됩니다. 볼트로 열면 사이드바에 work, perf, claude, thinking, templates 폴더가 표시됩니다.
Step 3. Obsidian CLI 활성화
Obsidian 설정(⚙️) → 코어 플러그인 → "CLI"를 검색해 활성화합니다. 이 기능은 Obsidian 1.12부터 지원되며, Claude Code가 터미널에서 Obsidian 볼트를 직접 조작할 수 있게 해줍니다.
⚠️ CLI를 활성화하지 않으면 Claude Code가 Obsidian의 일부 기능(노트 생성, 검색 등)을 활용하지 못합니다. 반드시 활성화하는 것을 권장합니다.
Step 4. Claude Code 실행
터미널에서 볼트 디렉터리로 이동한 뒤 claude 커맨드를 실행합니다.
cd ~/obsidian-mind
claudeClaude Code가 시작되면서 볼트 루트의 CLAUDE.md를 자동으로 읽습니다. 동시에 .claude/settings.json에 설정된 SessionStart 훅(hook)이 실행되어 볼트의 전체 파일 목록이 컨텍스트에 주입됩니다.
Step 5. North Star 목표 작성
claude/North Star.md 파일을 열고 현재 목표와 집중 영역을 작성합니다. 이 파일은 Claude Code가 매 세션 시작 시 참조하는 핵심 파일이므로, 간결하되 구체적으로 작성하는 것이 중요합니다.
# North Star
## 현재 목표
- 서비스 아키텍처 마이크로서비스 전환 완료 (Q2)
- 팀 온보딩 문서 체계화
## 집중 영역
- 백엔드 성능 최적화
- 기술 부채 해소
## 이번 주 우선순위
1. API 게이트웨이 설계 리뷰
2. 모니터링 대시보드 구축첫 세션 실행과 컨텍스트 확인
설치가 완료되면 Claude Code에 "start session"이라고 입력해 봅니다. 필자가 직접 테스트한 결과, Claude Code는 North Star 파일을 읽고 현재 목표를 요약한 뒤, 활성 프로젝트가 있는지 확인하고 오늘 할 수 있는 작업을 제안합니다.
아직 업무 노트가 없는 초기 상태에서는 "새 프로젝트를 시작하겠습니까?" 또는 "어떤 작업부터 시작할까요?" 같은 질문이 나옵니다. 여기서 업무 내용을 말하면 Claude Code가 자동으로 work/ 폴더에 적절한 형식의 노트를 생성하고, work/Index.md에 링크를 추가합니다.
세션을 마칠 때는 "wrap up"이라고 입력합니다. Claude Code가 생성된 노트를 검증하고, 인덱스를 업데이트하며, 성과로 기록할 만한 내용이 있는지 자동으로 확인합니다. 이 세션 흐름의 고급 활용법은 세션 훅 활용법에서 더 자세히 다루고 있습니다.
North Star 목표 파일 작성 요령
North Star 파일은 Claude Code의 방향감각을 결정하는 나침반 역할을 합니다. 작성 시 몇 가지 원칙을 지키면 세션 품질이 크게 달라집니다.
구체적인 수치와 기한을 포함하는 것이 좋습니다. "성능 개선"보다 "API 응답 시간 200ms 이하 달성 (6월까지)"가 Claude Code에 더 유용한 맥락을 제공합니다.
주간 단위로 업데이트하는 것을 권장합니다. 목표가 바뀌었는데 North Star가 오래된 상태이면 Claude Code의 제안이 현실과 어긋나게 됩니다. 매주 금요일 "wrap up" 시점에 함께 갱신하는 루틴을 만드는 것이 효과적입니다.
3~5개 항목으로 유지합니다. 너무 많은 목표를 나열하면 Claude Code가 우선순위를 판단하기 어려워집니다.
기존 볼트 마이그레이션 방법
이미 사용 중인 Obsidian 볼트가 있다면 /vault-upgrade 커맨드로 Obsidian Mind 구조로 마이그레이션할 수 있습니다.
# 1. 최신 obsidian-mind 클론
git clone https://github.com/breferrari/obsidian-mind.git ~/new-vault
# 2. Claude Code로 열기
cd ~/new-vault && claude
# 3. 기존 볼트를 가리켜 업그레이드 실행
/vault-upgrade ~/my-old-vault⚠️ 원본 볼트는 절대 수정되지 않습니다. 먼저 --dry-run 옵션으로 어떤 파일이 어디로 분류되는지 미리 확인한 뒤 실행하는 것을 권장합니다. Obsidian Mind가 아닌 일반 볼트에서도 Claude Code가 각 노트를 의미 기반으로 읽고 적절한 폴더로 분류합니다.
설치 시 흔한 실수와 해결법
실수 1: Obsidian CLI를 활성화하지 않은 채 실행 — Claude Code가 Obsidian 기능을 활용하지 못하고 기본 파일 시스템 조작만 가능합니다. 설정 → 코어 플러그인에서 CLI를 반드시 켜세요.
실수 2: 볼트 경로에 공백이나 한글 포함 — 일부 환경에서 경로 인식 문제가 발생할 수 있습니다. ~/obsidian-mind처럼 영문 경로를 사용하는 것이 안전합니다.
실수 3: North Star를 비워둔 채 세션 시작 — Claude Code가 목표 없이 범용적인 제안만 하게 됩니다. 간단한 한 줄이라도 목표를 작성해 두면 세션 품질이 눈에 띄게 달라집니다.
Obsidian Mind의 구조와 일반 볼트의 차이가 궁금하다면 Obsidian Mind vs 일반 볼트 비교 분석도 함께 참고해 보세요.
자주 묻는 질문
Q. GitHub 템플릿으로 사용해도 되나요?
GitHub의 "Use this template" 버튼으로 새 저장소를 만들 수도 있고, git clone으로 직접 복제할 수도 있습니다. 두 방식 모두 동일한 결과를 제공합니다.
Q. 설치 후 CLAUDE.md를 직접 수정해도 되나요?
CLAUDE.md는 사용자 환경에 맞게 자유롭게 수정할 수 있습니다. 자신의 팀 규칙이나 코딩 컨벤션을 추가하면 Claude Code가 그에 맞춰 동작합니다. CLAUDE.md 작성법에 대한 자세한 안내는 별도 글에서 다루고 있습니다.
Q. QMD도 함께 설치해야 하나요?
QMD는 선택 사항입니다. 설치하면 시맨틱 검색(의미 기반 검색)이 가능해져 노트 검색 정확도가 높아지지만, 없어도 Obsidian CLI와 grep으로 기본 검색이 작동합니다.
Q. WSL에서 설치할 때 주의할 점이 있나요?
WSL 환경에서는 볼트 경로를 Linux 파일시스템(/home/username/) 내에 두는 것을 권장합니다. /mnt/c/ 경로를 사용하면 파일 I/O 성능이 저하될 수 있습니다. Obsidian Windows 앱에서 WSL 경로에 접근하려면 네트워크 경로(\\wsl$\)를 사용합니다.
Q. 여러 컴퓨터에서 같은 볼트를 사용할 수 있나요?
Git으로 관리하면 여러 컴퓨터에서 동일한 볼트를 사용할 수 있습니다. 각 컴퓨터에서 git pull로 최신 상태를 받고, 작업 후 commit·push하면 됩니다. Obsidian Sync를 사용하는 것도 대안이지만, Git 기반이 버전 이력 관리 면에서 더 유리합니다.
마무리
Obsidian Mind 설치는 git clone 한 번이면 끝나고, 실질적인 셋업은 North Star 목표 파일을 작성하는 것입니다. 한번 구조가 잡히면 Claude Code가 매 세션마다 이전 맥락을 자동으로 이어받아 반복 설명 없이 바로 업무에 들어갈 수 있게 됩니다.
💬 설치 과정에서 막히는 부분이 있었다면 댓글로 알려주세요. 해결 방법을 함께 찾아보겠습니다.
🔖 주말에 셋업할 계획이라면 이 글을 북마크해 두시면 편리합니다.
📚 다음에 읽으면 좋은 글
ℹ️ 이 블로그는 Google 애드센스를 통해 광고 수익을 얻을 수 있습니다. 자세한 내용은 개인정보처리방침을 참고하세요.
※ 이 글은 2026-04-05 기준으로 작성되었습니다. 최신 정보는 공식 사이트에서 확인하세요.
'생산성 & 옵시디안' 카테고리의 다른 글
| Obsidian Mind North Star와 세션 훅 활용법, 매일 컨텍스트를 이어가는 워크플로 (0) | 2026.04.06 |
|---|---|
| Obsidian Mind CLAUDE.md 작성법, AI가 볼트를 이해하는 운영 매뉴얼 설계 (0) | 2026.04.06 |
| 윈도우11에서 Obsidian Mind 설치하기, Claude Code 네이티브와 WSL2 셋업 완전 가이드 (0) | 2026.04.05 |
| 2026년 Obsidian Mind 핵심 기능 정리, 엔지니어를 위한 AI 볼트 템플릿 (0) | 2026.04.05 |
| 옵시디안 Sync 유료 구독? 무료 Syncthing 동기화 완전 가이드 (0) | 2026.03.01 |
