KI-Agenten-Dokumentation: Warum Wikis die beste Wissensbasis sind (Karpathy-Pattern)

Wenn man KI-Agenten ernsthaft in Produktion betreibt – nicht als Chat-Spielerei, sondern als Co-Entwickler für Causal Engines, ETL-Pipelines und Redispatch-Logik – stellt sich schnell die unbequeme Frage: Wie dokumentiert man ein System so, dass sowohl Menschen als auch LLMs damit arbeiten können? Die ehrliche Antwort: Die meisten Teams machen es falsch. Sie schreiben entweder zu viel (1.000-Zeilen-READMEs) oder zu wenig (drei Sätze pro Repo). Karpathy hat auf einen dritten Weg hingewiesen: Wiki-strukturierte Dokumentation.

Das Problem: Warum README.md für KI-Agenten nicht ausreicht

Ein typisches Repo hat eine `README.md`, vielleicht eine `CONTRIBUTING.md` und ein `/docs`-Verzeichnis. Das funktioniert solange, wie ein Mensch das liest. Sobald ein LLM-Agent mit dem Code arbeiten soll – etwa Claude Code oder Cursor beim Refactoring unserer `electricity_price_forecast`-Pipeline – bricht dieses Modell zusammen.

Drei konkrete Failure-Modes

1. Kontext-Verdünnung. Eine README mit 2.000 Zeilen enthält viel irrelevante Information für eine spezifische Aufgabe. Wenn der Agent einen Bug in der Prophet-ML-Preisprognose fixen soll, interessieren ihn die Deployment-Anweisungen nicht. Trotzdem verbrauchen sie Tokens im Kontextfenster.

2. Fehlende semantische Navigation. LLMs können zwar grep-ähnlich suchen, aber sie folgen keinen impliziten Referenzen. Wenn in der README steht „siehe Abschnitt Datenmodell", muss das Modell raten, wo das steht. Bei expliziten `[[Wikilinks]]` ist die Referenz maschinenlesbar.

3. Kein Update-Pfad. Monolithische READMEs werden selten aktualisiert, weil jeder Commit Merge-Konflikte riskiert. Kleine Wiki-Seiten pro Konzept lassen sich unabhängig pflegen.

Karpathys Beobachtung: LLMs lieben Wikis

Karpathy hat im März 2025 auf X beiläufig angemerkt, dass LLMs mit Wikipedia-artigen Strukturen besser umgehen als mit langen Fliesstexten. Der Grund ist nicht mysteriös: Diese Modelle wurden auf Wikipedia-Dumps trainiert. Das Pattern „kurzer Artikel, viele Links, klare Überschriften" ist in ihren Gewichten tief verankert.

Was ein gutes LLM-Wiki auszeichnet

• Eine Seite = ein Konzept. Kein Mischen von „Was ist X?" und „Wie deploye ich X?" auf derselben Seite.

• Atomare Dateien. 100-500 Zeilen Markdown, nicht mehr.
• Explizite Verlinkung. `[[Causal Engine]]`, nicht „die Engine (siehe oben)".
• Konsistente Templates. Jede Seite hat dieselbe Struktur: Definition → Kontext → Implementierung → Referenzen.
• Keine versteckten Abhängigkeiten. Wenn Seite A nur im Kontext von Seite B Sinn ergibt, muss A das explizit verlinken.

Obsidian als Produktions-Setup

Wir haben nach einigen Monaten Experimentieren auf Obsidian als Wiki-Tool standardisiert. Die Entscheidung war pragmatisch, nicht ideologisch.

Warum Obsidian, nicht Confluence oder Notion

Confluence-Exporte nach Markdown sind qualitativ schlecht (kaputte Tabellen, verlorene Verlinkungen). Notion hat eine API, aber keine flache Datei-Struktur – LLM-Agenten können nicht nativ mit Notion-Blöcken umgehen. Obsidian hingegen ist plain Markdown im Filesystem. Das bedeutet:

• Der Vault liegt in einem Git-Repo.
• Claude Code kann direkt in den `.md`-Dateien lesen und schreiben.
• `[[Wikilinks]]` sind eine Standard-Konvention, die LLMs aus dem Trainingskorpus kennen.
• Keine Vendor-Lock-ins, kein API-Throttling.

Unsere Struktur

Der Vault für das BESS Live-Dashboard hat etwa 340 Markdown-Dateien, organisiert in:

```

/vault

/concepts # "Was ist X?" (Causal Chain, Redispatch, §14a EnWG)

/systems # Komponenten (ClickHouse, Prophet-Pipeline, UMG 96-EL)

/runbooks # Operative Prozesse (Deployment, On-Call)

/decisions # ADRs (Architecture Decision Records)

/regulatory # BNetzA-Festlegungen, EEG-Paragraphen

```

Jede Seite beginnt mit einem YAML-Frontmatter, einer Ein-Satz-Definition und einem `## Related`-Abschnitt mit Wikilinks.

Konkretes Beispiel: Causal Engine dokumentieren

Unsere Causal Engine mit ihren 15 Kausalketten nach dem LEAP-71-Pattern wäre als README unlesbar. Als Wiki funktioniert es.

Die Aufteilung

• `[[Causal Engine]]` – Definition in ~80 Zeilen, verlinkt auf alle 15 Ketten
• `[[Kausalkette BGA-Gasertrag]]` – eigene Seite mit Input/Output, verlinkt auf `[[Substrat-Mix]]` und `[[Fermenter-Temperatur]]`
• `[[LEAP-71 Pattern]]` – referenziert die Originalarbeit, erklärt das Computational-Engineering-Prinzip
• `[[ClickHouse Schema Kausalketten]]` – Tabellendefinitionen

Wenn ein KI-Agent jetzt den Auftrag bekommt „Füge eine Kausalkette für Wärmeauskopplung hinzu", kann er über die Wikilinks genau die drei bis vier Seiten laden, die er braucht – nicht die ganze Codebasis.

Messbarer Effekt

Nach der Migration von einer 1.800-Zeilen-README auf den Vault haben wir bei vergleichbaren Refactoring-Tasks in Cursor ungefähr 40 Prozent weniger Token-Verbrauch pro Task gemessen. Das ist kein wissenschaftlicher Benchmark, aber ein konsistenter Trend über mehrere Wochen. Wichtiger als die Kosten: Die Agents machten weniger halluzinierte Annahmen, weil sie auf verlinkte Seiten zurückgreifen konnten, statt aus lückenhaftem Kontext zu raten.

Das Wiki-First-Prinzip für KI-Agenten-Dokumentation

Aus unserer Erfahrung hat sich ein einfaches Prinzip destilliert: Wiki-First, README-Second.

Die Regel

Jedes Konzept, jede Komponente, jede Entscheidung bekommt eine eigene Wiki-Seite. Die README des Repos ist nur noch ein Index – sie enthält Wikilinks zu den eigentlichen Inhalten und maximal 200 Zeilen Quickstart.

Templates, die funktionieren

Für Systeme (z.B. eine Messhardware-Integration):

```markdown

Janitza UMG 96-EL

Ein-Satz-Definition.

Funktion

Schnittstellen (Modbus, MQTT)

Konfiguration

Fehlerbilder

Related

[[Modbus TCP]] · [[MQTT Broker Setup]] · [[Messkonzept §14a]]

```

Für Entscheidungen (ADRs):

```markdown

ADR-023: ClickHouse statt TimescaleDB

Kontext

Entscheidung

Konsequenzen

Related

```

Diese Templates sind auch maschinenlesbar. Ein Agent, der eine neue Hardware-Integration dokumentieren soll, kann das Template befüllen, statt Struktur zu erfinden.

Grenzen und ehrliche Einschränkungen

Wikis sind kein Allheilmittel. Drei Punkte, an denen wir uns die Zähne ausgebissen haben:

1. Pflegeaufwand ist real. Wenn niemand im Team bereit ist, Seiten zu schreiben und Wikilinks zu setzen, verrottet das Wiki schneller als eine README. Wir haben eine Regel: Kein PR ohne Wiki-Update bei neuen Konzepten.

2. Semantic Search ist nicht gratis. Damit ein KI-Agent relevante Seiten findet, braucht er entweder gute Dateinamen (plus grep) oder eine Embedding-basierte Retrieval-Schicht. Wir nutzen derzeit eine simple `fd`+`ripgrep`-Kombination, die in 95 Prozent der Fälle reicht.

3. Regulatorische Dokumente passen nicht immer ins Wiki-Pattern. BNetzA-Festlegungen wie die zu §14a EnWG sind lange, juristische Texte. Die bleiben als PDF im Vault und werden in Konzept-Seiten referenziert, nicht umgeschrieben.

Fazit: Dokumentation als Engineering-Disziplin

Die Wahl des Dokumentationsformats ist kein Nebenschauplatz, sobald KI-Agenten Teil des Entwicklungs-Workflows werden. Ein gut gepflegtes Obsidian-Wiki reduziert Token-Kosten, verbessert Agent-Qualität und bleibt gleichzeitig für Menschen lesbar. Karpathys Beobachtung ist keine theoretische Spielerei – sie ist ein konkreter Produktivitäts-Hebel für Teams, die mit LLMs arbeiten.

Wer heute noch monolithische READMEs schreibt, optimiert für ein Arbeitsmodell, das in zwei Jahren unüblich sein wird. Die Umstellung auf ein Wiki-First-Setup kostet ein bis zwei Wochen. Der Nutzen zeigt sich ab der ersten nicht-trivialen Agent-Session.

FAQ

Welches Wiki-Tool ist für KI-Agenten-Dokumentation am besten?

Obsidian, weil es plain Markdown im Filesystem nutzt und LLM-Agenten nativ damit arbeiten können. Alternativen wie Logseq oder Foam funktionieren ähnlich. Confluence und Notion sind ungeeignet, weil ihre Block-Strukturen nicht direkt maschinenlesbar sind.

Wie gross sollte eine einzelne Wiki-Seite sein?

Als Faustregel 100 bis 500 Zeilen Markdown, also etwa 2.000 bis 10.000 Tokens. Längere Seiten sollten in Unterseiten aufgeteilt werden, die über Wikilinks verbunden sind.

Funktionieren Wikilinks mit allen LLMs?

Claude, GPT-4+, Gemini und die grossen Open-Source-Modelle (Llama, Mistral) kennen das `[[Wikilink]]`-Pattern aus Wikipedia-Trainingsdaten und behandeln es als Referenz. Bei kleineren Modellen (<7B Parameter) kann die Erkennung unzuverlässig sein.

Wie integriere ich ein Obsidian-Vault in CI/CD?

Der Vault ist ein Git-Repo. Ein Linter (z.B. `markdownlint` plus ein Custom-Script für Wikilink-Konsistenz) prüft bei jedem PR, ob Links auf existierende Seiten zeigen. Broken Links sind ein Build-Fehler.

Ersetzt ein Wiki technische API-Dokumentation wie OpenAPI-Specs?

Nein. OpenAPI, Protobuf-Schemata und andere maschinengenerierte Specs sollten weiterhin in ihren Standardformaten gepflegt werden. Das Wiki verweist auf sie und liefert Kontext, ersetzt sie aber nicht.

Wie messe ich den ROI einer Wiki-Migration?

Zwei pragmatische Metriken: Token-Verbrauch pro vergleichbarer Agent-Task (vorher/nachher) und Anzahl der „unklaren Kontext"-Rückfragen des Agents. Beides lässt sich in einer einfachen Log-Auswertung über ein bis zwei Wochen messen.

Sollten Kunden oder externe Partner Zugriff auf das Wiki haben?

Nur über

[gekürzt]

Aktuelle Beiträge

Kommentare