Obsidian プロジェクト同期

Obsidian プロジェクト同期 は何をしますか？

ボールトは自分自身を記述します。 プロジェクトがある場所、完了したプロジェクトの行き先、フックがログを残す場所、ボールトの規約を宣言するノート — これらはすべてボールトのルートにある .claude-vault.json から取得され、scan がそれを返します。このスキルはフォルダ名を前提としません。

ボールトはプロジェクトだけではありません。 規約ノートは各フォルダが何を保持しているかを示します。新しいものをどこに置くかを提案する際には、それを考慮してください。複数のプロジェクトに影響する決定や事実は、1つのプロジェクトノートには記載しません。

最初にローカルマップ

このスキルのローカルマップを最初に探してください。ユーザーの固定指示（Claude Code の CLAUDE.md ファイル。コンテキスト内のコピーではなくディスクから読み取ります。編集より前に作成された可能性があります。claude.ai のプロジェクト指示またはユーザー設定）内の obsidian-project-sync local map というセクションです。この SKILL.md 内部の Local map for this install というセクション（スキルが1つの claude.ai アカウント用にパッケージ化されたときに追加されます）も対象です。ただし、固定指示が優先されます。これにはそのセットアップだけが知っている情報（ボールトのパス、ボールトの規約に加えたユーザー独自の規約（各プロジェクトが持つ補足ノート、コールアウトスタイル）、ボールトを参照し変更に伴い更新する必要があるその他のファイル）が格納されています。これに従ってください。ここでのデフォルトを上書きします。

スクリプトとボールト

スクリプトは scripts/vault.py で、この SKILL.md の隣にあります。この SKILL.md のフォルダからパスを構築してください（Claude Code はスキル読み込み時にベースディレクトリを指定します）。以下の例ではすべて vault.py と記述します。Python 3.8 以降が必要です。python が見つからない場合は python3、次に py を試してください。

ボールトのパスは、ローカルマップ、OBSIDIAN_VAULT 環境変数、またはユーザーへの質問の順で取得されます。サブコマンドの前後に --vault を付けて指定します。スクリプトには意図的に組み込みのデフォルトはありません。ボールトがない場合は停止してその旨を伝えます。

常に最初に：書き込む前に確認

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

--project なしで実行すると、ボールトのインベントリ（存在するプロジェクト、そのゾーン、ステータス）を返します。statuses_in_use はユーザーが既に使用している値をリストします。それらのいずれかを選択し、ラベルを新たに作成しないでください。

次にプロジェクト自体を確認します。

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

これにより、フォルダ、メインノート、そのフロントマター、正確な見出しリスト、フォルダ内の他のファイル、セッションログ（および読み取ったログファイル session_log_file）、sessions_since_note_changed（ノートの最終変更日時より新しいログセッション）が返されます。この最後のリストは「ノートにまだ反映されていないもの」の出発点ですが、証明ではありません。何かが欠落していると主張する前に、ノートと照合してください。

--project はボールト内のプロジェクトフォルダの名前を受け取ります。大文字小文字やアクセントを区別せずにマッチングします。コードリポジトリから作業する場合、フォルダは通常リポジトリ名と同じです。そうでない場合は、--project なしで scan を実行し、メインノートのフロントマター（ボールトが使用している場合、path または url キー）でマッチングし、何もマッチしない場合はユーザーに質問します。

アーカイブゾーンにあるプロジェクトは完了しています。それをアクティブなプロジェクトとして再作成したり、許可なく更新したりしないでください。

次に：ボールトの規約を読む

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 の差分を表示し、各変更が事実に基づくものか散文かを伝え、待機します。ユーザーが同意した場合のみ、--dry-run なしで同じコマンドを実行します。1回の同意は、ユーザーが確認した差分のみをカバーし、それ以外はカバーしません。
• --content は変更部分だけでなく、セクション全体を保持します。 replace はその見出し以下の本文全体を交換します。テーブルだけを送信すると、その下の散文は失われます。現在のセクションを読み、変更を組み込み、完全な結果を送信します。
• ノートの最後のセクションは保護されています。 フッターリンクは通常その下にあり、どのセクションにも属さず、失われます。スクリプトは終了コード 2 で停止し、その旨を伝えます。--mode append を使用して削除せずに追加します。これは「最近の変更」のような実行ログにはほとんどの場合適切です。
• append はコールアウトを尊重します。 セクションが囲みコールアウト（```ad-note、Admonition プラグイン由来）の場合、新しいテキストは囲みの内側、終了行の前に配置されます。ネイティブコールアウト（> [!note]）の場合、新しい行は引用符で囲まれ、その内部に留まります。フッターはどちらの場合も最後に残ります。
• 既存のスタイルを模倣します。 言語、トーン、散文か箇条書きか、長さ：ボールトの規約ノートがそれを宣言し、これから触れようとしているノートがそれを確認します。下書きする前に読んでください。
• 主張する前に確認します。 ノートに書き込むカウント、バージョン、ステータスは、このセッションで読み取ったものか実行したものから取得する必要があります。今確認できない場合は、省略するか、未検証であると明記します。

新しいセクションの追加には、どこに配置するかを指定する必要があります。 --heading "Testing" --after "Gotchas" のように指定します。まず質問してください。新しいセクションは、ユーザーが書いたドキュメントの構造を変更します。

許可なく変更してよいもの

ボールトがそれを宣言します。 規約ノート内で、何が事実で確認可能（したがって許可なく修正される）であり、何が散文で許可なく触れられないかが示されています。

それを読むまでは、すべてを散文として扱い、質問します。

新しい情報が既存のセクションに適合しない場合、両方の選択肢を提示し、ユーザーに選ばせます：セクションを拡張するか、メインノートからリンクされた別のノートを作成するかです。自分で決定しないでください。

フロントマター

スキーマは各ボールトに属し、その規約ノートが宣言します。scan は各ノートの実際のフロントマターを返します。これも確認方法の1つです。

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

スカラーキーのみです。スクリプトは意図的にブロックリストを拒否します。ノートのトピックを変更するのは著者の決定です。section --touch-updated ですでに日付が設定されているため、これ単体で使用されることはほとんどありません。

プラグインが所有するフィールド（ステッカー、アイコンなど）には決して触れません。

キャンバス

.canvas ファイルは nodes と edges を持つ JSON（JSON Canvas 1.0）です。レイアウトは手作業で、意図的なグループと接続で構成されています。

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

ノード、エッジ、グループ名、リンクされているノート、存在しなくなったファイルを指しているかどうかがわかります。

そして state_outside_its_group — 本当に注意が必要なフィールドです。 ノートを state でグループ化するキャンバスは、その情報をフロントマターとノードの位置・色の2か所に保持します。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）に記録します。リポジトリごとに1つのJSONで、日付、ブランチ、前回からの新しいコミット、触れたファイル、コミットされていないものがあるかどうかが含まれます。ノートには書き込みません。

それが生データです。ユーザーが更新を要求した場合、scan --project はそれを既に読み取って、session_log と sessions_since_note_changed に含めて返します。それらのコミットをノートの内容と照合し、どのセクションが古くなっているかを提案します。

フックがまだインストールされていない場合は、references/hook-install.md を読んでください。

claude.ai の会話からのノート

claude.ai プロジェクトはディスク上にないため、そこにはスクリプトがありません。完全なマークダウンをコードブロックに記述し、ユーザーのボールトのスキーマに従ったフロントマターを付け（知らない場合は、スキーマを尋ねるか、コピー元の既存ノートを1つ尋ねます）、保存場所を指示します。プロジェクトに既にノートがある場合は、新しいファイルを作成するのではなく、どのセクションに貼り付けるかを指示します。

何かが失敗した場合

• python が認識されない：python3、次に py を試してください。どれも動作しない場合、Python がありません。その旨を伝え、ファイルツールを使って手動で編集することを提案します（遅く、リスクが高いです）。
• 「ボールトが指定されていません」：ローカルマップにボールトパスがなく、OBSIDIAN_VAULT も設定されていません。ユーザーにパスを尋ね、ローカルマップに追加することを提案します。
• スクリプトが終了コード 2 で停止する：それは最後のセクション保護が機能しているためです。--mode append に切り替えてください。
• 差分が予想以上に多く削除されている：書き込まないでください。ほとんどの場合、--content が不完全です。
• プロジェクトのフォルダが存在しない：質問してください。自分だけでプロジェクトゾーンに新しいフォルダを作成しないでください。

参考資料

• references/hook-install.md：セッションログフックのインストール（Windows、macOS、Linux）
• references/mechanics.md：スクリプトの仕組みと保証内容：設定ファイル、見出しの検索方法、保護、ログ形式

書き方の規約はここにはありません。 それらはボールト内、scan が config.conventions で返すノートにあります。