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

> **TL;DR:** Andrej Karpathy hat im Frühjahr 2025 einen simplen Punkt gemacht: LLM-Agenten arbeiten schlechter mit README-Dateien als mit verlinkten Wikis. Nach einem Jahr Produktionseinsatz in unserer BGA-Monitoring-Pipeline bestätigt sich das. Ein Obsidian-Vault mit sauberen `[[Wikilinks]]` liefert Claude, Cursor und GPT-Agenten deutlich bessere Kontexte als monolithische Markdown-Dateien oder Confluence-Exporte.

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](https://stromfee.ai) 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](https://stromfee.me) 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](https://stromfee.ai) 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]