Obsidian-Projekt-Synchronisation

Obsidian-Projektsynchronisation

Das Vault beschreibt sich selbst. Wo die Projekte liegen, wohin abgeschlossene gehen, wo der Hook seine Protokolle hinterlässt und welche Notiz die Konventionen des Vaults deklariert – all das stammt aus .claude-vault.json im Stammverzeichnis des Vaults, und scan gibt es zurück. Dieses Skill nimmt keine Ordnernamen an.

Ein Vault besteht nicht nur aus Projekten, und seine Konventionsnotiz sagt, was jeder Ordner enthält. Behalte das im Hinterkopf, wenn du anbietest, wo etwas Neues abgelegt werden soll: Eine Entscheidung oder Tatsache, die mehrere Projekte betrifft, gehört nicht in die Notiz eines einzelnen Projekts.

Zuerst die lokale Karte

Suche zuerst nach der lokalen Karte dieses Skills: einem Abschnitt namens obsidian-project-sync local map in den ständigen Anweisungen des Benutzers (den CLAUDE.md-Dateien in Claude Code, die von der Festplatte gelesen werden und nicht aus der Kopie im Kontext, die älter als eine Bearbeitung sein kann; Projektanweisungen oder die Benutzereinstellungen in claude.ai). Ein Abschnitt namens Local map for this install innerhalb dieser SKILL.md, der hinzugefügt wurde, als das Skill für ein claude.ai-Konto gepackt wurde, zählt ebenfalls; ständige Anweisungen, die etwas anderes sagen, haben Vorrang. Er enthält, was nur dieses Setup weiß: den Pfad zum Vault, die eigenen Konventionen des Benutzers zusätzlich zu denen des Vaults (Begleitnotizen, die jedes Projekt mitführt, Callout-Stile), andere Dateien, die auf das Vault verweisen und mit ihm geändert werden müssen. Folge ihm, wo er spricht; er überschreibt die Standardeinstellungen hier.

Das Skript und das Vault

Das Skript ist scripts/vault.py, neben dieser SKILL.md: Baue seinen Pfad aus dem eigenen Ordner des Skills (Claude Code gibt das Basisverzeichnis an, wenn das Skill geladen wird). Jedes Beispiel unten schreibt es als vault.py. Es benötigt Python 3.8 oder höher; falls python nicht gefunden wird, versuche python3, dann py.

Der Pfad zum Vault kommt in dieser Reihenfolge von der lokalen Karte, von der Umgebungsvariablen OBSIDIAN_VAULT oder durch Nachfragen beim Benutzer. Gib ihn mit --vault vor oder nach dem Unterbefehl an. Das Skript hat absichtlich keinen eingebauten Standard: Ohne ein Vault stoppt es und sagt das.

Immer zuerst: Schauen, bevor du schreibst

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

Ohne --project gibt es das Inventar des Vaults zurück: welche Projekte existieren, in welcher Zone und mit welchem status. statuses_in_use listet die Werte auf, die der Benutzer bereits verwendet; wähle einen davon und erfinde keine Bezeichnungen.

Dann das Projekt selbst:

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

Es gibt den Ordner zurück, die Hauptnotiz, deren Frontmatter, die genaue Liste ihrer Überschriften, die anderen Dateien im Ordner, das Sitzungsprotokoll (und welche Protokolldatei es gelesen hat, in session_log_file) und sessions_since_note_changed: die protokollierten Sitzungen, die neuer sind als die letzte Änderung der Notiz auf der Festplatte. Diese letzte Liste ist der Ausgangspunkt für „was noch nicht in der Notiz steht", kein Beweis dafür: Überprüfe es anhand der Notiz, bevor du behauptest, dass etwas fehlt.

--project akzeptiert den Namen des Projektordners im Vault, ohne Berücksichtigung von Groß-/Kleinschreibung und Akzenten. Wenn du von einem Code-Repository aus arbeitest, hat der Ordner normalerweise den Namen des Repositorys; falls nicht, führe scan ohne --project aus und gleiche anhand des Frontmatters der Hauptnotiz ab (ein path- oder url-Schlüssel, falls das Vault einen verwendet), und frage nach, wenn nichts übereinstimmt.

Ein Projekt in der Archivzone ist abgeschlossen. Erstelle es nicht erneut unter den aktiven Projekten oder aktualisiere es ohne Nachfrage.

Zweitens: Die Konventionen des Vaults lesen

scan gibt einen config-Block zurück:

"config": {
  "source": ".claude-vault.json",
  "projects": "Projekte",
  "archive": "Archiv",
  "logs": "Werkzeuge/Claude Sync",
  "conventions": "/pfad/zum/vault/Meta/Konventionen.md"
}

conventions ist die Notiz, die regiert. Lese sie, bevor du in eine andere schreibst: Sie deklariert das Frontmatter-Schema, wie Notizen in diesem Vault geschrieben werden, was ohne Nachfrage geändert werden darf und was nicht. Dieses Skill führt absichtlich keine Kopie davon mit: Eine Kopie altert, und eine frühere Version dieses Skills zeigte auf einen Ordner, der nicht mehr existierte.

Wenn conventions null ist, deklariert das Vault keine. Frage, bevor du in irgendeine Notiz schreibst.

Derselbe Block sagt, woher die Ordner kamen. Wenn source defaults ist, hat das Vault sich nicht selbst beschrieben, und du arbeitest mit Annahmen: Sage das und biete an, .claude-vault.json zu schreiben (Format in references/mechanics.md). Wenn eine warning erscheint, ist die Konfiguration defekt und muss behoben werden, bevor es weitergeht.

Jeder Projektordner ist anders: Einige enthalten nur die Notiz und ein Canvas, andere tragen lose Notizen. Vertraue scan, niemals dem, was beim letzten Mal da war.

In eine Notiz schreiben

Notizen werden von Hand geschrieben. Es gibt keine Vorlage und keine versteckten Markierungen, und es werden keine hinzugefügt. Der Hauptteil eines bestimmten Abschnitts wird ersetzt:

python vault.py section --vault "<vault>" --note "<pfad>" --heading "Bereitstellen" --content "<datei>" --dry-run

Die Überschrift wird ohne Emoji und durch partielle Übereinstimmung gefunden, sodass Bereitstellen ## 🚀 Bereitstellen findet. Wenn keine Übereinstimmung vorliegt, listet das Skript die vorhandenen Überschriften auf, anstatt eine zu erfinden.

--content ist eine Datei, die das neue Markdown enthält. Schreibe es in einen temporären Ordner (den Scratchpad der Sitzung oder den System-Temp-Ordner), niemals innerhalb des Vaults oder eines Code-Repositorys, und lösche es danach.

Regeln, die wirklich wichtig sind:

• --dry-run zuerst, immer, und das Ja des Benutzers vor dem eigentlichen Schreiben. Zeige dem Benutzer den Dry-Run-Diff, sage, ob jede Änderung sachlich oder formulierend ist, und warte. Führe denselben Befehl ohne --dry-run erst aus, nachdem er zugestimmt hat; ein Ja deckt die Diffs ab, die er gesehen hat, nichts anderes.
• --content trägt den gesamten Abschnitt, nicht nur das, was sich ändert. replace tauscht den gesamten Hauptteil unter dieser Überschrift aus. Sende nur eine Tabelle und der darunter liegende Text verschwindet. Lese den aktuellen Abschnitt, arbeite die Änderung ein und sende das vollständige Ergebnis.
• Der letzte Abschnitt der Notiz ist geschützt. Die Fußzeilen-Links befinden sich normalerweise darunter, gehören zu keinem Abschnitt und würden verloren gehen. Das Skript stoppt mit Exit-Code 2 und sagt das. Verwende --mode append, um hinzuzufügen ohne zu löschen, was für ein laufendes Protokoll wie Letzte Änderungen fast immer richtig ist.
• append respektiert Callouts. Wenn ein Abschnitt ein umschlossener Callout ist (```ad-note, vom Admonition-Plugin), geht der neue Text innerhalb der Umschließung, vor der schließenden Zeile; wenn es ein nativer Callout ist (> [!note]), werden die neuen Zeilen zitiert, sodass sie darin bleiben. Die Fußzeile bleibt in beiden Fällen zuletzt.
• Ahme nach, was da ist. Sprache, Ton, Prosa oder Aufzählungspunkte, Länge: Die Konventionsnotiz des Vaults erklärt es, und die Notiz, die du gleich bearbeiten wirst, bestätigt es. Lese sie, bevor du einen Entwurf erstellst.
• Überprüfe, bevor du behauptest. Eine Anzahl, eine Version oder ein Status, die in eine Notiz geschrieben werden, müssen von etwas stammen, das du in dieser Sitzung gelesen oder ausgeführt hast. Wenn es jetzt nicht überprüft werden kann, lasse es weg oder sage, dass es unbestätigt ist.

Das Hinzufügen eines neuen Abschnitts erfordert die Angabe, wo er hinkommt: --heading "Testen" --after "Fallstricke". Frage zuerst: Ein neuer Abschnitt ändert die Struktur eines Dokuments, das der Benutzer geschrieben hat.

Was du ohne Nachfrage ändern darfst

Das Vault erklärt es, in seiner Konventionsnotiz: der Teil, der sagt, was sachlich und überprüfbar ist (und daher ohne Nachfrage korrigiert wird) und was Prosa ist, die ohne Erlaubnis nicht berührt wird.

Bis du es gelesen hast, behandle alles als Prosa und frage nach.

Wenn neue Informationen in keinen vorhandenen Abschnitt passen, biete beide Auswege an und lass den Benutzer wählen: einen Abschnitt erweitern oder eine separate Notiz, die von der Hauptnotiz verlinkt wird. Entscheide nicht selbst.

Frontmatter

Das Schema gehört zu jedem Vault, und seine Konventionsnotiz erklärt es. scan gibt das tatsächliche Frontmatter jeder Notiz zurück, was die andere Möglichkeit ist, es zu sehen.

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

Nur skalare Schlüssel. Das Skript verweigert block lists absichtlich: Das Ändern der Themen einer Notiz ist die Entscheidung des Autors. section --touch-updated setzt bereits das Datum, daher wird dies selten allein benötigt.

Ein Feld, das einem Plugin gehört (ein Sticker, ein Symbol), wird nie berührt.

Canvas

.canvas-Dateien sind JSON mit nodes und edges (JSON Canvas 1.0). Das Layout wurde von Hand erstellt, mit absichtlichen Gruppen und Verbindungen.

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

Es gibt Knoten, Kanten, Gruppennamen, welche Notizen verlinkt sind und ob eine auf eine Datei zeigt, die nicht mehr existiert.

Und state_outside_its_group, das Feld, das wirklich beobachtet werden muss. Ein Canvas, das Notizen nach ihrem state gruppiert, speichert diese Tatsache zweifach: im Frontmatter und in der Position und Farbe des Knotens. Ändere den state, lasse die Karte, wo sie war, und das Canvas bricht nicht; es zeigt immer noch auf eine existierende Datei und zeigt immer noch die alte Farbe. Es beginnt zu lügen, ohne jemanden zu warnen.

Also überprüfe immer, wenn du einen state änderst, ob dieses Projekt oder dieser Ordner ein Canvas hat, das nach Zustand gruppiert, und führe den Bericht aus. Das Gegenteil gilt auch: Überprüfe nach dem Erstellen einer Notiz, ob sie eine Karte hat. Eine Notiz, die nicht auf dem Board ist, existiert nicht für denjenigen, der das Board liest.

Es zu beheben bedeutet, den Knoten zu verschieben und neu einzufärben, was manuelle Bearbeitung ist: Das Skript berichtet, es ordnet nicht neu. Sage das und schlage die Änderung vor.

python vault.py canvas --file "<pfad>.canvas" --add-file "Relativer/Pfad/Note.md" --color 6 --dry-run

Neue Knoten landen in einer Lücke unter allem, was existiert: nichts, was bereits da ist, bewegt sich. Sie innerhalb einer Gruppe zu platzieren, ist die manuelle Arbeit des Benutzers, und das zu Recht. Führe es erneut ohne --dry-run aus, sobald der Benutzer zustimmt.

Wenn der Bericht defekte Links zeigt, sage das und stoppe. Lösche keine Knoten.

Das Sitzungsprotokoll

Ein SessionEnd-Hook zeichnet die Rohdaten jeder Claude Code-Sitzung im Protokollordner auf, den das Vault angibt (config.logs), eine JSON-Datei pro Repository: Datum, Branch, neue Commits seit dem letzten Mal, berührte Dateien und ob etwas nicht committet wurde. Es schreibt in keine Notiz.

Das ist das Rohmaterial. Wenn der Benutzer nach einem Update fragt, bringt scan --project es bereits gelesen mit, in session_log und sessions_since_note_changed. Überprüfe diese Commits mit dem, was die Notiz sagt, und schlage vor, welche Abschnitte veraltet sind.

Wenn der Hook noch nicht installiert ist, lies references/hook-install.md.

Notizen aus einer claude.ai-Unterhaltung

claude.ai-Projekte befinden sich nicht auf der Festplatte, daher gibt es dort kein Skript. Schreibe das vollständige Markdown in einem Code-Block, mit Frontmatter, das dem Schema des Benutzervaults folgt (frage danach oder nach einer vorhandenen Notiz zum Kopieren, falls du es nicht kennst), und sage, wo es gespeichert werden soll. Wenn das Projekt bereits eine Notiz hat, sage, in welchen Abschnitt es eingefügt werden soll, anstatt eine lose Datei zu erstellen.

Wenn etwas fehlschlägt

• python wird nicht erkannt: versuche python3, dann py. Wenn keins funktioniert, gibt es kein Python; sage das und biete an, die Bearbeitung von Hand mit den Dateiwerkzeugen durchzuführen, was langsamer und riskanter ist.
• „Kein Vault angegeben”: Die lokale Karte hat keinen Vault-Pfad und OBSIDIAN_VAULT ist nicht gesetzt. Frage den Benutzer nach dem Pfad und biete an, ihn zur lokalen Karte hinzuzufügen.
• Das Skript stoppt mit Exit-Code 2: Das ist der Schutz des letzten Abschnitts, der seine Arbeit tut. Wechsle zu --mode append.
• Der Diff zeigt mehr gelöscht als erwartet: Schreibe nicht. Fast immer war --content unvollständig.
• Der Ordner des Projekts existiert nicht: Frage nach. Erstelle keine neuen Ordner in der Projektzone eigenmächtig.

Verweise

• references/hook-install.md: Installieren des Sitzungsprotokollierungs-Hooks unter Windows, macOS und Linux.
• references/mechanics.md: Wie das Skript funktioniert und was es garantiert: die Konfigurationsdatei, wie eine Überschrift gefunden wird, die Schutzmechanismen, das Protokollformat.

Die Schreibkonventionen befinden sich nicht hier. Sie leben im Vault, in der Notiz, die scan in config.conventions zurückgibt.