Obsidian 프로젝트 동기화

Obsidian 프로젝트 동기화은(는) 무엇을 하나요?

저장소가 스스로를 설명합니다. 프로젝트가 어디에 있는지, 완료된 프로젝트가 어디로 이동하는지, 후크가 로그를 남기는 위치, 그리고 저장소의 규칙을 선언하는 노트가 무엇인지 등 모든 정보는 저장소 루트의 .claude-vault.json에서 가져오며, scan 명령이 이를 반환합니다. 이 스킬은 폴더 이름에 대해 어떤 가정도 하지 않습니다.

저장소는 프로젝트만 있는 것이 아니며, 규칙 노트는 각 폴더가 무엇을 담고 있는지 명시합니다. 새로운 내용을 어디에 넣을지 제안할 때 이 점을 명심하세요: 여러 프로젝트에 영향을 미치는 결정이나 사실은 한 프로젝트의 노트에 넣지 않습니다.

먼저 로컬 맵 확인

이 스킬의 로컬 맵을 다른 모든 것보다 먼저 찾으세요: 사용자의 고정 명령어(Claude Code의 CLAUDE.md 파일 – 컨텍스트 내 복사본(편집 이전일 수 있음)이 아닌 디스크에서 읽은 파일; 또는 claude.ai의 프로젝트 명령어나 사용자 환경설정)에 obsidian-project-sync 로컬 맵이라는 이름의 섹션이 있습니다. 이 SKILL.md 내부에 이 설치를 위한 로컬 맵이라는 섹션(하나의 claude.ai 계정용으로 패키징될 때 추가됨)도 해당됩니다. 단, 고정 명령어가 더 우선합니다. 로컬 맵에는 해당 설정만 아는 정보가 담겨 있습니다: 저장소 경로, 저장소 규칙 위에 적용되는 사용자 자체 규칙(모든 프로젝트가 가지는 동반 노트, 콜아웃 스타일), 저장소를 가리키며 함께 변경되어야 하는 기타 파일 등입니다. 로컬 맵이 말하는 바를 따르세요; 여기의 기본값을 재정의합니다.

스크립트와 저장소

스크립트는 scripts/vault.py이며, 이 SKILL.md 옆에 있습니다: 스킬 자체 폴더에서 경로를 구성하세요(Claude Code가 스킬 로드 시 기본 디렉토리를 알려줍니다). 아래 모든 예제에서는 vault.py로 표기합니다. Python 3.8 이상이 필요합니다. python을 찾을 수 없으면 python3, 그다음 py를 시도하세요.

저장소 경로는 다음 순서로 가져옵니다: 로컬 맵에서, OBSIDIAN_VAULT 환경 변수에서, 또는 사용자에게 묻습니다. --vault 플래그로 전달하며, 서브커맨드 앞이나 뒤에 위치할 수 있습니다. 스크립트에는 의도적으로 내장 기본값이 없습니다: 저장소 없이 실행하면 멈추고 그 사실을 알립니다.

항상 먼저: 쓰기 전에 확인

python vault.py scan --vault "<vault>"

--project 없이 실행하면 저장소의 인벤토리를 반환합니다: 어떤 프로젝트가 존재하는지, 어떤 영역(zone)에 있으며, status가 무엇인지. statuses_in_use는 사용자가 이미 사용 중인 값을 나열합니다; 그중 하나를 선택하고 새 레이블을 만들지 마세요.

그런 다음 프로젝트 자체:

python vault.py scan --vault "<vault>" --project "<folder name>"

이 명령은 폴더, 주요 노트, 해당 프론트매터, 헤딩의 정확한 목록, 폴더 내 다른 파일, 세션 로그(읽은 로그 파일을 session_log_file에 표시), 그리고 sessions_since_note_changed를 반환합니다: 이는 노트가 디스크에서 마지막으로 변경된 이후의 로그된 세션입니다. 이 마지막 목록은 "노트에 아직 없는 것"의 시작점일 뿐, 그 자체로 증거는 아닙니다: 노트와 대조하여 무언가 누락되었다고 주장하기 전에 확인하세요.

--project는 저장소 내 프로젝트 폴더 이름을 받으며, 대소문자와 악센트를 무시하고 매칭합니다. 코드 저장소에서 작업할 때 폴더 이름은 보통 저장소 이름과 동일합니다. 그렇지 않은 경우, --project 없이 scan을 실행하고 주요 노트의 프론트매터(저장소가 사용하는 path 또는 url 키)로 매칭하며, 일치하는 항목이 없으면 질문하세요.

보관 영역(archive zone)에 있는 프로젝트는 완료된 것입니다. 활성 프로젝트 중에 이를 다시 만들거나 질문 없이 업데이트하지 마세요.

두 번째: 저장소의 규칙 읽기

scan은 config 블록을 반환합니다:

"config": {
  "source": ".claude-vault.json",
  "projects": "Projects",
  "archive": "Archive",
  "logs": "Toolbox/Claude Sync",
  "conventions": "/path/to/vault/Meta/Conventions.md"
}

conventions는 규칙을 정하는 노트입니다. 다른 어떤 노트에 쓰기 전에 이것을 먼저 읽으세요: 이 노트는 프론트매터 스키마, 저장소에서 노트를 작성하는 방식, 질문 없이 변경할 수 있는 것과 변경할 수 없는 것을 선언합니다. 이 스킬은 의도적으로 이 노트의 사본을 가지고 있지 않습니다: 사본은 오래되고, 이전 버전의 스킬이 더 이상 존재하지 않는 폴더를 가리키는 결과를 낳았습니다.

conventions가 null이면 저장소에 선언된 규칙이 없는 것입니다. 어떤 노트에 쓰기 전에 질문하세요.

같은 블록은 폴더 정보가 어디서 왔는지 알려줍니다. source가 defaults이면 저장소가 스스로를 설명하지 않은 것이며 가정하여 작업 중입니다: 그 사실을 말하고, .claude-vault.json(형식은 references/mechanics.md에 있음) 작성을 제안하세요. warning이 나타나면 설정이 손상된 것이므로 계속 진행하기 전에 수정이 필요합니다.

각 프로젝트 폴더는 다릅니다: 어떤 것은 노트와 캔버스만 가지고 있고, 다른 것은 느슨한 노트들을 함께 담고 있습니다. scan을 신뢰하고, 이전에 무엇이 있었는지는 절대 믿지 마세요.

노트에 쓰기

노트는 손으로 작성됩니다. 템플릿도, 숨겨진 마커도 없으며, 추가되지도 않습니다. 특정 섹션의 본문만 교체됩니다:

python vault.py section --vault "<vault>" --note "<path>" --heading "Deploy" --content "<file>" --dry-run

헤딩은 이모지 없이, 부분 일치로 매칭되므로, Deploy는 ## 🚀 Deploy를 찾습니다. 일치하는 항목이 없으면 스크립트는 임의로 헤딩을 만들지 않고 존재하는 헤딩 목록을 표시합니다.

--content는 새로운 마크다운을 담은 파일입니다. 임시 폴더(세션의 스크래치패드 또는 시스템 임시 폴더)에 작성하고, 저장소나 코드 저장소 내부에는 절대 넣지 마세요. 사용 후에는 삭제하세요.

정말 중요한 규칙:

• --dry-run을 항상 먼저 실행하고, 실제 쓰기 전에 사용자의 동의를 받으세요. 사용자에게 dry-run diff를 보여주고, 각 변경이 사실적인지 산문인지 말하고, 기다리세요. 동의한 후에만 --dry-run 없이 동일한 명령을 실행하세요; 하나의 동의는 그들이 본 diff에만 적용되며, 다른 것은 해당되지 않습니다.
• --content는 변경된 부분만이 아니라 전체 섹션을 담습니다. replace는 해당 헤딩 아래의 전체 본문을 교체합니다. 테이블만 보내면 그 아래의 산문은 사라집니다. 현재 섹션을 읽고, 변경 사항을 반영한 후 완전한 결과를 보내세요.
• 노트의 마지막 섹션은 보호됩니다. 푸터 링크는 보통 그 아래에 있으며, 어떤 섹션에도 속하지 않아 손실됩니다. 스크립트는 종료 코드 2와 함께 멈추고 그 사실을 알립니다. --mode append를 사용하여 삭제 없이 추가하세요. 이는 Recent changes와 같은 실행 로그에 거의 항상 올바른 방법입니다.
• append는 콜아웃을 존중합니다. 섹션이 펜스로 둘러싸인 콜아웃(```ad-note, Admonition 플러그인)인 경우, 새 텍스트는 펜스 안쪽, 닫는 줄 앞에 들어갑니다; 네이티브 콜아웃(> [!note])인 경우, 새 줄은 인용 처리되어 콜아웃 내부에 유지됩니다. 푸터는 어느 경우든 마지막에 유지됩니다.
• 있는 그대로 모방하세요. 언어, 어조, 산문 또는 글머리 기호, 길이: 저장소의 규칙 노드가 이를 선언하고, 수정하려는 노트가 이를 확인합니다. 초안을 작성하기 전에 읽으세요.
• 주장하기 전에 확인하세요. 노트에 기록된 개수, 버전 또는 상태는 이 세션에서 읽거나 실행한 것에서 비롯되어야 합니다. 지금 확인할 수 없으면 생략하거나 검증되지 않았다고 말하세요.

새 섹션을 추가하려면 위치를 지정해야 합니다: --heading "Testing" --after "Gotchas". 먼저 질문하세요: 새 섹션은 사용자가 작성한 문서의 구조를 변경합니다.

물어보지 않고 변경할 수 있는 것

저장소가 선언합니다. 규칙 노트에서: 사실적이고 확인 가능한 것(따라서 묻지 않고 수정 가능)과 산문(허가 없이 수정 불가)을 구분하는 부분입니다.

규칙 노트를 읽기 전까지는 모든 것을 산문으로 취급하고 질문하세요.

새 정보가 기존 섹션에 맞지 않을 때는 두 가지 방법을 모두 제시하고 사용자가 선택하게 하세요: 섹션을 확장하거나, 주요 노트에서 링크된 별도의 노트를 만드는 방법. 스스로 결정하지 마세요.

프론트매터

스키마는 각 저장소에 속하며, 규칙 노트가 선언합니다. scan은 각 노트의 실제 프론트매터를 반환하며, 이는 스키마를 확인하는 다른 방법입니다.

python vault.py frontmatter --vault "<vault>" --note "<path>" --set updated=2026-09-13 --dry-run

스칼라 키만 가능합니다. 스크립트는 의도적으로 블록 리스트를 거부합니다: 노트의 주제를 변경하는 것은 저자의 결정입니다. section --touch-updated가 이미 날짜를 설정하므로, 이 명령이 단독으로 필요한 경우는 드뭅니다.

플러그인이 소유한 필드(스티커, 아이콘 등)는 절대 건드리지 않습니다.

캔버스

.canvas 파일은 nodes와 edges(JSON Canvas 1.0)를 포함한 JSON입니다. 레이아웃은 의도적인 그룹과 연결과 함께 손으로 만들어졌습니다.

python vault.py canvas --vault "<vault>" --file "<path>.canvas" --report

이 명령은 노드, 엣지, 그룹 이름, 연결된 노트, 더 이상 존재하지 않는 파일을 가리키는 노트가 있는지 여부를 반환합니다.

그리고 state_outside_its_group, 정말 주시해야 할 필드입니다. state별로 노트를 그룹화하는 캔버스는 해당 사실을 두 번 저장합니다: 프론트매터와 노드의 위치 및 색상에. state를 변경하고 카드를 원래 위치에 두면 캔버스는 깨지지 않습니다. 여전히 존재하는 파일을 가리키고 이전 색상을 표시합니다. 아무도 경고하지 않은 채로 거짓말을 시작합니다.

따라서 state를 변경할 때마다 해당 프로젝트나 폴더에 state별로 그룹화하는 캔버스가 있는지 확인하고 리포트를 실행하세요. 반대의 경우도 마찬가지입니다: 노트를 만든 후에는 카드가 있는지 확인하세요. 보드에 없는 노트는 보드를 읽는 사람에게 존재하지 않습니다.

수정은 노드를 이동하고 색상을 다시 지정하는 것을 의미하며, 이는 수동 편집입니다: 스크립트는 리포트만 하고 재배열하지 않습니다. 그 사실을 말하고 변경을 제안하세요.

python vault.py canvas --file "<path>.canvas" --add-file "Relative/Path/Note.md" --color 6 --dry-run

새 노드는 기존 노드 아래의 빈 공간에 배치됩니다: 기존 노드는 절대 움직이지 않습니다. 그룹 내에 배치하는 것은 사용자의 수동 작업이며, 당연히 그래야 합니다. 사용자가 동의하면 --dry-run 없이 다시 실행하세요.

리포트에 끊어진 링크가 표시되면 그 사실을 말하고 중단하세요. 노드를 삭제하지 마세요.

세션 로그

SessionEnd 후크는 각 Claude Code 세션의 원시 데이터를 저장소가 선언한 로그 폴더(config.logs)에 기록합니다. 저장소당 하나의 JSON 파일이며, 날짜, 브랜치, 마지막 이후 새 커밋, 수정된 파일, 커밋되지 않은 항목이 있는지 여부를 포함합니다. 어떤 노트에도 기록하지 않습니다.

이것이 원재료입니다. 사용자가 업데이트를 요청하면 scan --project가 이미 읽은 상태로 session_log와 sessions_since_note_changed를 가져옵니다. 해당 커밋을 노트의 내용과 대조하고, 어떤 섹션이 오래되었는지 제안하세요.

후크가 아직 설치되지 않은 경우 references/hook-install.md를 읽으세요.

claude.ai 대화의 노트

claude.ai 프로젝트는 디스크에 없으므로 스크립트도 없습니다. 완전한 마크다운을 코드 블록 안에, 사용자 저장소의 스키마(모르는 경우 요청하거나 기존 노트 하나를 복사용으로 요청)를 따르는 프론트매터와 함께 작성하고, 저장 위치를 알려주세요. 프로젝트에 이미 노트가 있으면 새 파일을 만들지 말고 어느 섹션에 붙여넣을지 말하세요.

실패 시 처리

• python이 인식되지 않는 경우: python3, 그다음 py를 시도하세요. 그래도 안 되면 Python이 없는 것입니다. 그 사실을 말하고 파일 도구로 수동 편집을 제안하세요(느리고 위험합니다).
• "저장소가 지정되지 않음": 로컬 맵에 저장소 경로가 없고 OBSIDIAN_VAULT가 설정되지 않은 경우입니다. 사용자에게 경로를 묻고 로컬 맵에 추가를 제안하세요.
• 스크립트가 종료 코드 2로 중단되는 경우: 마지막 섹션 보호가 작동한 것입니다. --mode append로 전환하세요.
• diff에 예상보다 많은 삭제가 표시되는 경우: 쓰지 마세요. 거의 항상 --content가 불완전한 경우입니다.
• 프로젝트 폴더가 존재하지 않는 경우: 질문하세요. 스스로 프로젝트 영역에 새 폴더를 만들지 마세요.

참조

• references/hook-install.md: Windows, macOS, Linux에서 세션 로깅 후크 설치하기.
• references/mechanics.md: 스크립트 작동 방식과 보장 사항: 설정 파일, 헤딩 찾기, 보호 기능, 로그 형식.

작성 규칙은 여기에 없습니다. 저장소에 있으며, scan이 config.conventions에 반환하는 노트에 있습니다.