Pascal MichelandClaude Opus 5
c064c729ed
Erster Stand des öffentlichen Ausschnitts aus dem Vault. Die .gitignore arbeitet als Positivliste: ausgeschlossen ist alles, eingeschlossen nur, was ausdrücklich wieder aufgenommen wird. Notizen, Projekte, Finanzen, das Sitzungsgedächtnis und settings.local.json bleiben damit außen vor. Der Kundenname in AI/Regelwerk/seo.md ist durch eine neutrale Bezeichnung ersetzt; die Regeln selbst sind unverändert. Co-Authored-By: Claude Opus 5 <[email protected]>
129 lines
4.6 KiB
Markdown
129 lines
4.6 KiB
Markdown
# Die Referenzschicht
|
||
|
||
## Warum überhaupt ein Index
|
||
|
||
Ein Agent, der eine Frage an einen Vault mit 500 Notizen stellt, hat drei
|
||
Möglichkeiten: alles lesen (sprengt den Kontext), grep (findet Wortformen, aber
|
||
nicht Bedeutung, und liefert Treffer ohne Einordnung), oder eine
|
||
Zwischenschicht, die pro Notiz genau so viel weiß, dass sich entscheiden lässt,
|
||
ob man sie aufmacht. Die dritte Variante ist der Index.
|
||
|
||
Größenordnung: 500 Notizen à 800 Wörter sind rund 500.000 Token. Der Index
|
||
derselben 500 Notizen liegt bei etwa 25.000 Token — und eine typische Abfrage
|
||
gibt davon 10–40 Zeilen aus, also ein paar hundert Token. Deshalb: nie den Index
|
||
komplett lesen, immer `vault_query.py` fragen.
|
||
|
||
## Erzeugte Dateien
|
||
|
||
### `_index/vault-index.json`
|
||
Kompaktes JSON ohne Einrückung, Kurzschlüssel zur Platzersparnis:
|
||
|
||
| Schlüssel | Bedeutung |
|
||
|---|---|
|
||
| `p` | Pfad relativ zum Vault |
|
||
| `u` | uid |
|
||
| `t` | type |
|
||
| `s` | status |
|
||
| `n` | Titel |
|
||
| `m` | summary |
|
||
| `g` | tags |
|
||
| `r` | Projekt-Slug |
|
||
| `c` / `d` | created / updated |
|
||
| `h` | Überschriften (max. 12) |
|
||
| `l` | ausgehende Links |
|
||
| `w` | Wortzahl (bei Assets: Dateigröße) |
|
||
|
||
Leere Felder fehlen ganz. Der `meta`-Block enthält Zählungen, Typverteilung,
|
||
Statusverteilung, Top-Tags und die Zahl toter Links.
|
||
|
||
Das Feld `h` ist der zweite Hebel nach `m`: Bei einer langen Notiz zeigen die
|
||
Überschriften, welcher Abschnitt gebraucht wird — statt 3.000 Wörter zu lesen,
|
||
liest man 300.
|
||
|
||
### `_index/INDEX.md`
|
||
Menschenlesbare Übersicht, nach Typ gruppiert, jede Zeile ein Wikilink plus
|
||
Zusammenfassung. In Obsidian direkt navigierbar. Bei über 200 Notizen enthält
|
||
die Datei selbst den Hinweis, sie nicht komplett zu lesen.
|
||
|
||
### `_index/backlinks.json`
|
||
`{ "pfad/zur/notiz.md": ["pfad/quelle1.md", …] }`. Basis für `--links-to` und
|
||
die Waisen-Erkennung.
|
||
|
||
## Wann neu bauen
|
||
|
||
- nach dem Anlegen, Verschieben, Umbenennen oder Löschen von Notizen
|
||
- nach Frontmatter-Änderungen
|
||
- vor einer Arbeitssitzung, wenn zwischendurch in Obsidian gearbeitet wurde
|
||
|
||
`vault_query.py` vergleicht die Änderungszeiten und warnt auf stderr, wenn
|
||
Notizen neuer sind als der Index. Der Lauf über einige tausend Dateien dauert
|
||
Sekunden, also im Zweifel neu bauen.
|
||
|
||
Automatisieren geht per Git-Hook (`.git/hooks/pre-commit`) oder Cron:
|
||
|
||
```bash
|
||
python3 .claude/skills/obsidian-vault-navigator/scripts/build_index.py --vault . --quiet
|
||
```
|
||
|
||
## Abfrage-Rezepte
|
||
|
||
```bash
|
||
Q=".claude/skills/obsidian-vault-navigator/scripts/vault_query.py"
|
||
|
||
# Womit habe ich mich zu Thema X beschäftigt?
|
||
python3 $Q --text x
|
||
|
||
# Laufende Code-Projekte, als fertige Wikilink-Liste für eine Antwort
|
||
python3 $Q --type project-code --status active --format md
|
||
|
||
# Alles zu einem Projekt, inklusive Unternotizen und Anhängen
|
||
python3 $Q --project auth-service
|
||
|
||
# Passendes Template-Projekt finden, ohne eines zu öffnen
|
||
python3 $Q --type template-project
|
||
|
||
# Was hat sich diese Woche getan?
|
||
python3 $Q --since 7 --sort updated
|
||
|
||
# Kandidaten fürs Archiv
|
||
python3 $Q --status active --stale 180
|
||
|
||
# Wer verweist auf diese Notiz?
|
||
python3 $Q --links-to 30_Research/rate-limiting.md
|
||
|
||
# Pflegeliste: Notizen ohne summary
|
||
python3 $Q --no-summary --limit 100 --format paths
|
||
|
||
# Struktur einer langen Notiz sehen, bevor man sie liest
|
||
python3 $Q --text "kubernetes netzwerk" --format headings
|
||
```
|
||
|
||
Mehrere `--text` werden UND-verknüpft, mehrere `--type`/`--tag`/`--status`
|
||
ODER-verknüpft (bei `--tag` müssen alle angegebenen Tags vorhanden sein).
|
||
|
||
## Wenn der Index nichts findet
|
||
|
||
1. Filter lockern — oft ist `--type` zu eng gesetzt.
|
||
2. Anderes Wort probieren; der Index kennt nur Titel, Summary, Tags,
|
||
Überschriften und Pfad, keinen Fließtext.
|
||
3. Erst dann Volltext: `grep -ril "begriff" --include="*.md" .`
|
||
4. Findet grep etwas, das der Index nicht hatte, ist das ein Befund: Der Notiz
|
||
fehlt ein Tag oder eine bessere `summary`. Gleich nachziehen — der Index wird
|
||
dadurch mit jedem Miss besser.
|
||
|
||
## Grenzen
|
||
|
||
Der Index ist Metadaten, keine Semantik. Er findet nichts, was nirgends benannt
|
||
ist, und er versteht keine Synonyme. Für semantische Suche im großen Vault gibt
|
||
es lokale Werkzeuge (z. B. Obsidians eigene Suche mit Operatoren oder externe
|
||
Embedding-Indizes) — die ersetzen diese Schicht nicht, sondern ergänzen sie: Der
|
||
Index bleibt die billige erste Stufe.
|
||
|
||
## Verhältnis zu Obsidian Bases
|
||
|
||
Obsidian Bases (`.base`-Dateien) erzeugen Tabellen- und Kartenansichten aus
|
||
Properties — dieselben Felder, die auch der Index nutzt. Wer im Obsidian-UI
|
||
dieselben Übersichten will, legt Bases an; für den Agenten bleibt der
|
||
JSON-Index der billigere Weg. Für die korrekte `.base`-Syntax den offiziellen
|
||
Skill `obsidian-bases` verwenden.
|