Workspace-Wiki: Projektgedächtnis für Mensch und KI-Agent
43 Projekte, über 800 Artikel, eine Konvention. Das Wiki lebt als Markdown in jedem Repo, eine CLI macht es durchsuchbar, ein Audit hält es ehrlich, und KI-Agenten müssen es benutzen, nicht nur dürfen.
August 2026
PROJEKT
Workspace-Wiki: Projektgedächtnis für Mensch und KI-Agent
TECHNOLOGIEN
Herausforderung
Mein Workspace ist auf über 40 Projekte gewachsen: Apps, Web-Services, Tools, Experimente. Seit ich KI-nativ arbeite, entstehen sie schneller, und die Arbeit verteilt sich auf viele Claude-Code-Sessions. Jede Session beginnt bei null. Der Agent kennt weder das Projekt noch die Entscheidungen der letzten Woche, also durchsucht er den Code, baut sich ein Bild und verwirft es, sobald das Kontextfenster endet. Beim nächsten Mal von vorn.
Die üblichen Antworten skalieren nicht. Eine CLAUDE.md pro Projekt ist gut für Regeln, aber zu klein für Architektur: Sie wird lang, veraltet und in jeder Session komplett geladen. README-Dateien beschreiben den Zustand von damals. Und das eigentliche Wissen, warum etwas so gebaut ist, welches Wire-Format eine Nachricht hat, welche Env-Variable der Deploy braucht, lag in Chat-Verläufen, die niemand wiederfindet.
Dazu kommt das Drift-Problem: Dokumentation, die von Hand gepflegt wird, lügt irgendwann. Ein Pfad wird umbenannt, eine Funktion verschwindet, der Artikel bleibt stehen. Für einen menschlichen Leser ärgerlich, für einen Agenten fatal, denn er nimmt den Text für bare Münze und baut darauf auf.
Vier Anforderungen standen deshalb fest:
- Das Wissen liegt beim Code: im Repo, versioniert, als Markdown, ohne Datenbank und ohne Build-Step
- Es ist für Agenten in Sekunden abfragbar, auch semantisch, ohne laufenden Dienst und ohne dass Inhalte in eine Cloud gehen
- Falsche Aussagen fallen mechanisch auf, bevor sie committed werden
- Das Schreiben ist keine Kür: Agenten lesen das Wiki, bevor sie im Code suchen, und pflegen es, bevor sie fertig sind
Lösung
Das Ergebnis ist ein System aus drei Teilen, die dieselben Dateien lesen: eine Konvention pro Projekt, eine CLI und ein Web-Frontend. Nichts davon ist exotisch, die Wirkung kommt aus der Konsequenz.
Eine Konvention statt einer Datenbank
Jedes Projekt hat einen .wiki/-Ordner im Repo-Root: eine wiki.config.md mit Projektname, Kategorien und Tech-Stack, einen articles/<kategorie>/<slug>.md-Baum und eine nutshell.md als Steckbrief mit One-Liner, Status, Stack samt Versionen, Größe in Dateien und Codezeilen und Deployment-Ziel. Ein Thema pro Datei, Frontmatter obligatorisch: Titel, Kategorie, Tags, Status, related für Querverweise und code_refs für die Stellen im Code, die der Artikel beschreibt. Die Regel klingt banal, ist aber der Grund, warum 43 Projekte mit derselben CLI lesbar sind. Deutsche Prosa, englische Identifier, Mermaid für Architekturbilder.
Eine CLI als gemeinsamer Zugang
wiki ist ein Node-Script ohne nennenswerte Abhängigkeiten, symlinked nach ~/.local/bin, und der Weg, über den Agenten das Wiki lesen. wiki ls zeigt die Projekte, wiki cat <projekt>/<kategorie>/<slug> einen Artikel, wiki search sucht Substrings, wiki stack --tag nextjs beantwortet „wo nutze ich X“. Welche Projekte eingehängt sind, steht in genau einer Registry-Datei, die CLI und Frontend gemeinsam lesen; wiki reindex und wiki doctor halten Manifest und Registry konsistent. Wiki-Dateien schreibt das Tooling nur an einer Stelle: Zwei Scaffold-Skripte erkennen Tech-Stack und Projektgröße aus Manifesten und Imports und generieren daraus Nutshell und Stack-Liste.
Semantische Suche, komplett lokal
Substring-Suche scheitert, sobald jemand „Push-Updates“ sucht und der Artikel „SSE + pg_notify“ heißt. wiki vbuild zerlegt deshalb jeden Artikel in Absatz-Chunks von rund 1.500 Zeichen, stellt den Artikeltitel jedem Chunk als Kontext-Anker voran und embedded ihn mit einem mehrsprachigen E5-Modell über transformers.js, auf der CPU, ohne API. Der Index ist eine JSONL-Datei im Cache, aktuell rund 5.000 Chunks. wiki vsearch embedded die Frage, rechnet Cosine-Similarity über alle Vektoren und dedupliziert auf Artikel-Ebene, damit die Trefferliste acht verschiedene Artikel zeigt statt achtmal denselben. Deutsch und Englisch funktionieren gemischt, und der Build erkennt selbst, ob sich seit dem letzten Lauf Artikel geändert haben.
wiki ask: RAG ohne Infrastruktur
wiki ask setzt auf die Vektorsuche einen Q&A-Bot: die Top-15-Treffer plus alle Nutshells als Kontext, dann ein claude -p-Subprozess über die vorhandene Claude-Code-Anmeldung. Kein API-Key, kein Hosting. Der System-Prompt trennt die Wahrheit sauber: Für „welche Projekte nutzen X“, Versionen und Deploy-Ziele sind die Nutshells autoritativ, Snippets nur für „wie funktioniert Y“. Jede Aussage zitiert genau einen Artikel als [projekt/kategorie/slug], und die Antwort bleibt bewusst kurz, denn vertiefen soll man an der Quelle. Ein NDJSON-Modus streamt dieselbe Pipeline ins Web-Frontend.
Drift-Audit: Doku, die gegen den Code geprüft wird
Der für mich wichtigste Teil. wiki audit läuft über alle Artikel und verifiziert jede Behauptung, die sich mechanisch prüfen lässt: code_refs und related im Frontmatter, datei:zeile-Referenzen im Text, Pfade in Backticks und aufgerufene Symbole wie obj.method(...), die im Quellbaum oder in einer Stdlib-Allowlist vorkommen müssen. Pfade werden dreistufig aufgelöst (exakt, Suffix, eindeutiger Basename), Multi-Repo-Projekte bekommen mehrere Source-Roots. Eine Negations-Heuristik verhindert Fehlalarme: Steht vor dem Symbol „kein“, „geplant“ oder „ehemals“, ist der Verweis auf etwas Nicht-Existierendes korrekt. Was das Audit bewusst nicht prüft: Signaturen, Verhalten und Zahlen in Prosa, dafür braucht es ein semantisches Review. Über den ganzen Workspace verifiziert es aktuell über 11.000 Referenzen in rund zwölf Sekunden, deterministisch, ohne Netzwerk, mit Exit-Code 1 bei Fehlern. Damit taugt es als Pre-Commit-Check.
Ein Frontend zum Lesen
Für Menschen gibt es ein Next.js-Frontend, das die .wiki/-Ordner direkt vom Dateisystem liest: Projekt-Übersicht in Plattform-Buckets (App, Web, Tool), gerenderte Artikel mit Status-Badge, Verwandt-Liste und Code-Referenzen, ein Technologies-Tab über alle Projekte und ein Ask-Widget per ⌘K, das wiki ask streamt. Neue Artikel sind nach dem Refresh da, ohne Build.
Umsetzung
Ein Wiki, das niemand liest, ist Ballast, und ein Wiki, das niemand pflegt, wird zur Falle. Deshalb ist die Nutzung in die Regeln eingebaut, die jeder Agent in jeder Session bekommt, auf drei Ebenen.
Global: erst das Wiki, dann der Code
Meine globale CLAUDE.md beschreibt die wiki-CLI mit allen Kommandos. Wer Cross-Projekt-Kontext oder Architektur-Hintergrund braucht, sucht zuerst dort: vsearch bei unklaren Begriffen, search bei bekannten Identifiern, ask für Fragen über mehrere Projekte. Die Kommandos sind in den Projekt-Settings vorab erlaubt, damit kein Permission-Prompt im Weg steht und der Griff zum Wiki billiger ist als der Griff zum Code.
Pro Projekt: Lesen und Schreiben als Teil des Feature-Workflows
Die CLAUDE.md jedes Projekts enthält denselben Regelblock. Das Wiki ist die primäre Wissensquelle: Bei jeder Frage zu Features oder Architektur werden zuerst Index und Artikel gelesen, bevor im Code gesucht wird. Nach jeder Feature-Implementierung prüft der Agent, welche Artikel betroffen sind, und aktualisiert sie samt updated-Datum, bevor er die Arbeit als fertig meldet. Neue Features bekommen einen Artikel, entfernte wandern nach _archive/. Und die härteste Regel: Das Wiki dokumentiert nur existierenden Code. Geplante Features gehören in eine Planungs-Ablage, nicht in Artikel, weil ein Agent den Unterschied zwischen „ist so“ und „soll so werden“ sonst nicht mehr sehen kann.
Automatisiert: Skills, Hooks und der Release-Flow
Ein /create-wiki-Skill legt für ein Projekt das komplette Wiki an. Er startet einen Master-Agenten mit maximaler Analysetiefe, der parallele Explore-Agenten über den Code fächert und Artikel erst schreibt, wenn der referenzierte Code wirklich gelesen wurde. Mein Scaffolding-Skill für neue Projekte initialisiert das Wiki ab dem ersten Commit, zusammen mit Release-Notes und einem /wrap-Command. Dieser /wrap-Flow schließt jede Version ab: Git-Log auswerten, Version bestimmen, Release-Notes schreiben und als eigener Schritt die Wiki-Pflege, also für jedes neue Feature einen Artikel, für jedes geänderte den Artikel aktualisieren, Index regenerieren, wiki audit vor dem Commit. Ein PostToolUse-Hook erinnert zusätzlich, wenn Artikel neuer sind als der Index. Release-Notes beantworten „was hat sich geändert“, das Wiki „wie funktioniert es“, und diese Trennung steht explizit in den Regeln.
Code-Beispiele
Ergebnisse
Das System deckt heute meinen gesamten Workspace ab:
- 43 Projekte und über 800 Artikel im selben Format, vom iOS-Spiel bis zum Web-Service, alle über eine CLI lesbar
- Semantische Suche über rund 5.000 Chunks, lokal auf der CPU, Deutsch und Englisch gemischt, ohne dass ein Byte den Rechner verlässt
- Drift-Audit über mehr als 11.000 Code-Referenzen in rund zwölf Sekunden; die meisten Projekte stehen bei null Fehlern, und wo Drift auftritt, nennt das Audit Artikel, Pfad und Grund
- Ein Q&A-Bot mit Zitaten, ohne API-Key und ohne Server, über die vorhandene Claude-Code-Anmeldung
- Ein Web-Frontend, das die Markdown-Dateien ohne Build-Step rendert
- Wiki-Pflicht auf drei Ebenen: globale Regeln, Projekt-Regeln und automatisierte Skills, Hooks und Release-Flow
Der spürbare Effekt liegt in den Sessions. Ein Agent, der mit wiki vsearch einsteigt, hat nach einer Minute das Bild, für das er vorher zehn Minuten Code lesen musste, und zwar dasselbe Bild, das ich habe. Verlorene Entscheidungen sind seltener geworden, weil der Ort für sie feststeht. Und weil Agenten schreiben müssen, bevor sie fertig sind, wächst das Wiki mit dem Code, statt ihm hinterherzuhinken.
Die Erkenntnis: Dokumentation für KI-Agenten braucht andere Eigenschaften als Dokumentation für Menschen. Sie muss maschinell auffindbar sein, sie muss mechanisch prüfbar sein, und sie muss verpflichtend sein. Eine Konvention aus Markdown und Frontmatter, eine CLI und ein Audit reichen dafür aus. Entscheidend ist nicht das Tool, sondern dass es an jedem Punkt des Workflows steht: beim Projektstart, in jeder Session, in jedem Release.
Das System ist auf meinen Workspace zugeschnitten und nicht als Paket veröffentlicht. Die Ideen dahinter, Konvention statt Datenbank, lokale Vektorsuche, Drift-Audit gegen den Code und Wiki-Pflicht im Workflow, lassen sich aber in jedem Team-Setup nachbauen.
Visuelle Eindrücke
Projektliste, semantische Suche mit Scores und das Audit mit verifizierten Referenzen: die drei Kommandos, mit denen eine Agenten-Session beginnt und endet.