Plaintext gewinnt: Bauen Sie ein Git-gestütztes Wiki, dem Ihre KI-Agenten und Ingenieur:innen vertrauen

Sie haben kein Halluzinationsproblem. Sie haben ein Dokumentationsproblem. Wenn Ihr operatives Wissen sich über Notion, Confluence, Slack-Threads, Google Docs und fünf Anbieter-Wikis verteilt, spielen Ihre Agenten (und Ihre neuen Mitarbeitenden) stille Post. Das Ergebnis: langsame Incident-Reaktion, fragile Automatisierungen und ein schleichendes Misstrauen gegenüber KI im Engineering.

Es gibt eine Lösung, die langweilig, schnell und wirksam ist: ein Git-gestütztes Plaintext-Wiki, das Menschen und Agenten gleichermaßen lesen und schreiben. Inspiriert von jüngsten Community-Diskussionen über Karpathy-Style LLM-Wikis und der Erinnerung daran, dass Klartext Bestand hat, ist das keine Nostalgie. Es ist eine Entscheidung zugunsten von Prüfbarkeit, Latenz und Kosten – genau das, was ein produktionsreifer KI-Stack braucht.

Warum Plaintext + Git Ihren aktuellen Wildwuchs schlägt

• Nachvollziehbarkeit, die Sie bereits beherrschen: PRs, Diffs, CODEOWNERS und Reviews sind Muskelgedächtnis Ihres Teams. „Docs as Code“ gibt Ihnen Herkunft und Änderungskontrolle, ohne ein weiteres Tool zu kaufen.
• LLM-freundlich von Haus aus: Markdown ist token-sparsam, gut in Chunks teilbar und komprimiert sich gut. Sie können es an RAG füttern, ohne gegen proprietäre Formate oder brüchige Konnektoren zu kämpfen.
• Günstig und schnell: Ein Vektorindex mit 100k Chunks (768-dim float32) umfasst ~300 MB Vektoren plus Index-Overhead – nennen wir es unter 500 MB. Moderne Vektorspeicher liefern Top-k in unter 50 ms in dieser Größenordnung.
• Offline-first-Dauerhaftigkeit: Wenn Ihre Anbieter APIs drosseln oder Formate ändern, bleibt Ihr Wissen lauffähig. Git-Mirrors und S3-Snapshots überdauern Tools und Organigramme.

Ein Entscheidungsrahmen für CTOs für ein Git-gestütztes, agentenlesbares Wiki

1) Scope: Was dazugehört (und was nicht)

• In: Architekturüberblicke, Runbooks, Playbooks, Serviceverträge, API-Spezifikationen, Produkt-FAQs, Onboarding-Checklisten, CI/CD-Dokumentation, Shadow-IT-Inventare, Anbieterlimits und SLAs.
• Out: Secrets, Zugangsdaten, Kunden-PII und ungeschwärzte Logs. Diskutieren Sie das nicht. Ihr Wiki dient als Referenz und zum Schlussfolgern, nicht für Schlüssel oder Rohdaten.
• Klassifizierung: Wenden Sie ein einfaches Triage-Tag in der Frontmatter an – grün (intern-öffentlich), gelb (intern eingeschränkt), rot (gehört woanders). Agenten sehen nie rot. Gelb wird per Verzeichnis abgeschottet.

2) Repo-Topologie und Metadaten

• Ein kb-Repo pro Business Unit (oder ein einzelnes Mono-KB, wenn Sie unter 100 Engineers sind). Zu starkes Sharding killt die Auffindbarkeit; zu wenig Sharding überlastet die Owner.
• Ordnerlayout nach Domäne: platform/, app/, data/, sec/, ops/, product/. Innerhalb jedes Bereichs Service-Ordner mit einem Standardskelett: overview.md, runbook.md, metrics.md, limits.md, faq.md.
• Frontmatter: Title, tags, owners (Git-Handles), last_verified_at, TTL_days, sensitivity. Ihre CI kann Vorhandensein und Frische dieser Felder erzwingen.

3) Contribution und Review

• Nur PRs: Menschen und Agenten schlagen Änderungen per PR vor. Keine direkten Commits auf main. Für Änderungen an Runbooks oder Limits ist mindestens eine menschliche Genehmigung erforderlich.
• CI-Schranken: Markdown linten, Rechtschreibprüfung, Link-Check, grundlegender PII-Regex-Scan und ein „Doc-Frische“-Job, der veraltetes last_verified_at markiert. Bei roten Flags den Build fehlschlagen lassen.
• SLA nach Tier: Tier 0 (Incidents, Security) PRs mit 4-Stunden-Review-Ziel; Tier 1 (produktkritisch) 24 Stunden; Tier 2 wöchentlich.

4) Storage und Indexierung: Hybrid schlägt reinen Vektor

• Primary: GitHub oder GitLab mit geschützten Branches, jede Nacht nach S3 gespiegelt. Halten Sie das Wiki-Repo von Ihren Code-Repos entkoppelt.
• Search: Verwenden Sie einen Hybridindex: einen invertierten Index (OpenSearch, Meilisearch) für exakte Suchen plus einen Vektorspeicher (Qdrant, Weaviate) für Semantik. Mischen Sie Scores zur Abfragezeit für das Beste aus beiden Welten.
• Ingestion: Git-Diffs beobachten; geändertes Markdown in 300–500 Token-Spannen mit 10–15 % Overlap chunken; einbetten und upserten. Dadurch vermeiden Sie, bei jedem Commit die gesamte Welt neu zu indexieren.

5) Agentenschnittstelle: lesen, zitieren und schreiben wie ein Engineer

• Abrufrichtlinie: Top-k=8 Hybrid-Kandidaten, dann per Cross-Encoder auf 3–5 Auszüge neu ranken. Zwingen Sie Agenten, in Antworten Dateipfade und Zeilenbereiche zu zitieren. Zitierungen protokollieren.
• Updates via PRs: Erkennt ein Agent Drift (z. B. ein 429 von einer Anbieter-API widerspricht dokumentierten Limits), eröffnet er einen PR mit minimalem Diff und verweist auf Belege. Menschen reviewen; CI erzwingt Frische.
• Memory-Hygiene: Geben Sie Agenten ein Kurzzeit-Scratchpad (Redis mit 24–72 Stunden TTL) für flüchtigen Kontext. Dauerhaftes Gedächtnis lebt nach Review in Git.

6) Identity, Berechtigungen und Blast Radius

• AuthN/AuthZ: OIDC-SSO zu Ihrem Git-Provider; CODEOWNERS als Domain-Gates; geschützte Branches für main; Bots nur auf kb-Repos scoped.
• Zugriff auf Verzeichnisebene, nicht auf Dateiebene, um die Komplexität erträglich zu halten. Wenn Sie Doc-ACLs auf Datei-Ebene brauchen, ist Ihr Problem die Klassifizierung, nicht das Tooling.
• Agent-RBAC: Separate Service-Accounts je Agent mit Schreibrechten nur auf Draft-Branches. Jeder Agent-PR labelt sich mit dem aufrufenden Workflow und der Run-ID.

7) Toolchain für Menschen und Maschinen

• Markdown (GFM) mit Überschriften, Tabellen und Mermaid-Diagrammen. Vermeiden Sie proprietäre Embeds. Halten Sie Bilder neben den Docs mit beschreibendem Alt-Text, um OCR/LLM-Pipelines zu helfen.
• Statische Site für Menschen: Docusaurus oder MkDocs-Material auf eine interne Domain veröffentlicht. Schnell, durchsuchbar und versioniert.
• Disziplin bei Diagrammen: Bevorzugen Sie textbasierte Diagramme, die in Git eingecheckt sind, statt PNG-Exporte. Agenten können Text diffen und aktualisieren; Ihren Screenshot können sie nicht bearbeiten.

8) Qualität, Drifterkennung und Telemetrie

• Coverage-Metrik: Verfolgen Sie „Knowledge Coverage“ als (# der Tier 0/1-Services mit aktuellen Runbooks und Limits) geteilt durch die Gesamtzahl der Tier 0/1-Services. Ziel: 90 % in 60 Tagen.
• Automatisierte Drift-Probes: Leichtgewichtige Jobs, die kritische Anbieter-APIs zu Limits/Endpoints abfragen und mit den Docs vergleichen. Öffnen Sie einen PR, wenn sie über eine Schwelle (z. B. 10 %) abweichen.
• Search Analytics: Protokollieren Sie fehlgeschlagene Abfragen und Zero-Result-Suchen auf der statischen Site und der Agentenebene; machen Sie pro Sprint die Top 20 zu Docs.

9) Kosten und Performance: belastbare Zahlen

• Skalenbeispiel: 5.000 Markdown-Seiten mit durchschnittlich 800 Tokens, in 400-Token-Spannen gechunkt ≈ 10.000 Chunks.
• Storage: 10.000 Vektoren × 3 KB ≈ 30 MB Vektoren; mit HNSW-Index und Metadaten 100–150 MB einplanen.
• Latenz: Hybridsuche bei 10–100k Chunks liefert typischerweise in 30–70 ms auf Commodity-Hardware. Reranking fügt 10–25 ms CPU-Zeit hinzu. End-to-End-RAG unter 200 ms ist on-prem erreichbar.
• Embedding-Kosten: Wenn Sie ein kleines Embedding-Modell selbst hosten, kann eine GPU der T4-Klasse 10–20k Chunks in Minuten einbetten; nur CPU ist langsamer, aber für nächtliche Jobs günstig. Managed Embeddings kosten Cent- bis Dollarbeträge pro Reindex – bei dieser Größenordnung weiterhin vernachlässigbar.

Eine pragmatische Referenzarchitektur

• Erstellung: GitHub/GitLab-Repo (kb) → PRs (Menschen + Agenten) → CI (Lint, PII-Scan, Frische, Broken Links) → geschütztes main.
• Veröffentlichen: Statischen Site-Build auf interne Domain mit eingebauter Stichwortsuche.
• Index: Ingestion-Service beobachtet Repo-Diffs → chunken/normalisieren → einbetten → Upsert nach Qdrant (semantisch) und OpenSearch (lexikalisch).
• Bereitstellen: Retrieval-API mischt Lexikalisches + Vektor → optionales Reranking → liefert sortierte Auszüge + Zitate → Agenten-/Mensch-Clients.
• Governance: Drift-Sonden + Suchanalysen → PRs, um Lücken zu schließen → Dashboards für Coverage/Frische.

Sicherheit und Compliance: absichtlich langweilig

• Keine Secrets im Wiki. Behandeln Sie rot klassifiziertes Wissen als Nicht-Wiki und verweisen Sie auf Ihren Vault oder Ihr Ticketsystem.
• PII-Schutzgeländer: CI-Regexe fangen offensichtliche Leckage ab; periodische DLP-Scans den Rest. Builds bei Treffern fehlschlagen lassen.
• Backups: Nächtlicher S3-Mirror mit unveränderlicher Aufbewahrung und regionsübergreifender Replikation. Wiederherstellungen vierteljährlich testen.
• Legal Holds: Commits, die mit Ermittlungen zusammenhängen, taggen; Garbage Collection der zugehörigen Branches verhindern.

Häufige Fehlermodi (und wie man sie vermeidet)

• Agenten auf main committen lassen: Jede Agentenänderung muss per PR mit menschlichem Review erfolgen. Das erhält Vertrauen.
• Versuch, Berechtigungen auf Datei-Ebene zu modellieren: Eine Falle. Verwenden Sie Scoping auf Verzeichnisebene und klassifizieren Sie besser.
• „Wir syncen später aus Notion“: Konnektoren verrotten und werden rate-limitiert. Migrieren Sie kritische Docs jetzt in Markdown; lassen Sie einen Deprecation-Banner zurück.
• Nur binäre Diagramme und PDFs: Wenn ein LLM es nicht diffen kann, kann es es nicht warten. Bevorzugen Sie text-first Assets. Führen Sie OCR auf Legacy-PDFs aus und versehen Sie sie mit Alt-Text.
• Jeden Commit global indexieren: Diffs beobachten; nur geänderte Chunks neu einbetten. So bleiben Kosten und Latenz vorhersagbar.

Ein 30-60-90-Tage-Rollout, der die Lieferung nicht entgleisen lässt

Tage 0–30: Das Rückgrat aufbauen

• KB-Repo(s) erstellen, statischen Site-Generator wählen, CI-Schutz (Lint, PII-Scan, Frische) durchsetzen und Frontmatter sowie Ordnerskelett definieren.
• Hybridsuche (OpenSearch + Qdrant) und eine einfache Retrieval-API instrumentieren. Ranking noch nicht überoptimieren.
• Tier-0-Runbooks und Limits für Ihre Top-10-Services migrieren. Owner benennen und SLAs festlegen.

Tage 31–60: Agenten und Drifterkennung verdrahten

• „Agent PRs“ mit einem scoped Bot-Account aktivieren. Zitate für jede Agenten-Änderung verlangen.
• Drift-Sonden für zwei externe Abhängigkeiten hinzufügen (z. B. Rate Limits des Auth-Providers, Pagination der Billing-API). Sonden so verdrahten, dass sie bei Divergenzen automatisch PRs öffnen.
• Nutzungs-Dashboards veröffentlichen: Coverage %, Frische %, Top-Fehlsuchen.

Tage 61–90: Skalieren und härten

• Auf Tier-1-Services und Plattformdokumente ausweiten. 90 % Coverage auf Tier 0/1 anpeilen.
• Reranking hinzufügen und Mischgewichte tunen. Ziel: unter 200 ms End-to-End-Retrieval.
• Red-Team-Übung durchführen: Versuchen, PII ins Wiki zu schmuggeln und die CI zu umgehen. Findings beheben.

Wo Nearshore-Teams helfen (und wo nicht)

Wenn Ihnen Kapazität fehlt, kann ein diszipliniertes Nearshore-Team dies bootstrappen, ohne Ihre Roadmap zu kapern. In Brazil bekommen Sie 6–8 Stunden Überlappung mit US-Zeitzonen, Git-native Workflows und Engineers, die in CI leben. Sie sind nützlich für die unglamouröse Arbeit: Doc-Migration, CI-Plumbing, Drift-Sonden und Indexing-Pipelines. Behalten Sie Ownership und Review bei Ihren Domain Leads; outsourcen Sie nicht die Stimme Ihrer Runbooks.

Wann Sie das nicht tun sollten

• Wenn 90 % Ihres Wissens aus Screenshots und Anbieter-PDFs bestehen und Sie sich nicht verpflichten können, künftig text-first zu arbeiten, schwimmen Sie gegen den Strom. Erst das beheben.
• Wenn Sie keine Review-Kultur haben, wird ein Git-Wiki genauso schnell zum Friedhof wie Ihr Notion. Owner ernennen und SLAs durchsetzen.
• Wenn Ihre Hauptrestriktion compliancegetriebener Dokumentzugriff auf Nutzer- und Datei-Ebene ist, akzeptieren Sie ein schwereres CMS mit Doc-Level-ACLs und integrieren Sie Agenten vorsichtig.

Der strategische Punkt: menschliche Wahrheit und Agenten-Wahrheit vereinen

Die meisten Teams bauen aus Versehen zwei Wissensgraphen: einen für Menschen (hübsche Seiten) und einen für Maschinen (Indizes und Prompts). Dort entstehen Halluzinationen und Drift. Ein Git-gestütztes Plaintext-Wiki verkürzt die Distanz. Menschen schlagen vor und reviewen; Agenten zitieren und stellen PRs. Alle sehen dieselbe Wahrheit, mit denselben Leitplanken, in demselben Workflow, dem Sie für Code bereits vertrauen.

Wichtigste Erkenntnisse

• Plaintext + Git liefert Nachvollziehbarkeit, Geschwindigkeit und LLM-Freundlichkeit, ohne eine weitere Plattform zu kaufen.
• Halten Sie Secrets und PII draußen; klassifizieren Sie Docs und schotten Sie per Verzeichnis mit CODEOWNERS und geschützten Branches ab.
• Nutzen Sie einen Hybrid-Search-Stack (lexikalisch + Vektor), gespeist von einer diff-bewussten Ingestion-Pipeline; zielen Sie auf Retrieval unter 200 ms.
• Zwingen Sie Agenten, Quellen zu zitieren und PRs einzureichen; lassen Sie sie niemals auf main committen.
• Messen Sie Coverage und Frische, fügen Sie Drift-Sonden hinzu und machen Sie pro Sprint aus Fehlsuchen Docs.
• Starten Sie mit Tier-0-Runbooks und -Limits; erreichen Sie 90 % Coverage in 60–90 Tagen, ohne die Lieferung zu entgleisen.