Tools - KnowHowToAI
Das Dilemma klassischer Dokumentation im KI-Zeitalter
Wenn KI-Agenten (wie Cursor, Claude Code oder Antigravity) komplexe Entwicklungsaufgaben in gewachsenen Systemen lösen sollen, benötigen sie fundiertes Fach- und Architekturwissen. Herkömmliche Dokumentationsansätze scheitern dabei meist an zwei Extremen:
- Das Datei- und Kontext-Chaos: Hunderte unstrukturierte Markdown- oder Textdateien blind in den Prompt zu laden, sprengt das Token-Budget, erzeugt hohe Kosten und führt dazu, dass Sprachmodelle entscheidende Details im Rauschen übersehen (Lost in the Middle).
- Die Vektor-RAG-Überkomplexität: Vektordatenbanken (Embedding-basiertes RAG) sind für hierarchische Fachdokumentationen oft unzuverlässig: Sie liefern isolierte Textfragmente („Chunks“) ohne den logischen Gesamtzusammenhang der Dokumentenstruktur oder übersehen exakte Schlagworte und Querverweise.
KnowHowToAI wählt einen pragmatischen, architektonisch sauberen Mittelweg: Die strikte Trennung von Autorenumgebung (wo Mensch und KI schreiben) und Leseumgebung (wo der Agent strukturiert sucht).
1. Das Konzept: Trennung von Schreiben und Lesen
- Schreiben im Dateisystem (Markdown + YAML Frontmatter): Die Dokumentation wird in übersichtlichen Ordnerstrukturen als Standard-Markdown gepflegt. Jedes Dokument enthält strukturierte Metadaten (
title,tags,synonyms). Markdown ist git-versionierbar, lesbar und lässt sich sowohl von Entwicklern als auch von KI-Agenten nahtlos erstellen und editieren. - Lesen über MS SQL Server (via MCP): Zur Laufzeit synchronisiert ein CLI-Befehl die Dokumente in einen relationalen MS SQL Server Cache. Hierarchien, Pfad-Slugs, Schlagworte und Synonyme werden strukturiert indiziert, sodass der MCP-Server Anfragen deterministisch und in Millisekunden beantwortet.
2. Der Doku-Loop: Validierung als digitaler Türsteher
Damit die Wissensdatenbank dauerhaft konsistent bleibt und KI-Agenten keine strukturellen Fehler beim Verfassen von Dokumentation hinterlassen, setzt KnowHowToAI auf einen geschlossenen Workflow:
- Strikte Vorab-Validierung (
validate): Ein CLI-Validator prüft YAML-Header, Slug-Konventionen, Dateipfade und Verlinkungen auf syntaktische Korrektheit, bevor Daten in die Datenbank gelangen. Schlägt die Prüfung fehl, erhält der Agent präzises Feedback und korrigiert die Dateien eigenständig. - Deterministischer Sync (
import/export): Das Datenbankschema verwaltet sich über selbst-idempotente SQL-Skripte ohne ORM-Overhead. Sicherheitsmarker (.marker) schützen bestehende Verzeichnisse zuverlässig vor versehentlichem Überschreiben.
3. Zielsichere MCP-Navigation: Bis zu 90 % Token-Ersparnis
Statt vollständige Handbücher in das Kontextfenster zu laden, nutzt der KI-Agent drei spezialisierte MCP-Tools, um sich schrittweise und bedarfsgerecht durch die Wissensbasis zu bewegen:
list_children(Strukturüberblick): Liefert die Inhaltsstruktur eines Verzeichnisknotens. Der Agent erhält eine schlanke Landkarte relevanter Themengebiete, ohne den Dokumententext selbst zu laden.search_docs(Gezielte Suche): Durchsucht Titel, Tags, Synonyme und Volltexte per SQL-Matching. Dank hinterlegter Synonyme (z. B. „Zuschuss“ für „Förderantrag“) findet die KI auch dannTreffer, wenn im Prompt andere Fachbegriffe verwendet werden als im Originaldokument.get_doc(Punktgenauer Abruf): Erst wenn das exakte Zieldokument identifiziert ist, ruft der Agent den vollständigen Inhalt ab.
Dieser dreistufige Abruf schont das Kontextbudget massiv und eliminiert Halluzinationen durch irrelevante Textmengen.
4. Multi-Bibliothek & Flexibilität
KnowHowToAI ist vollständig generisch aufgebaut. Über separate Konfigurationen (appsettings.json) lassen sich beliebig viele thematisch getrennte Wissensbibliotheken (z. B. ERP-Architektur, API-Referenzen, Unternehmensrichtlinien) als eigene Tabellen parallel betreiben – jede mit eigenem MCP-Endpunkt.
Fazit
KnowHowToAI verbindet die Einfachheit und Versionierbarkeit von Markdown mit der Abfragegeschwindigkeit und Struktur relationaler Datenbanken. Es gibt KI-Agenten genau die Orientierung, die sie für präzise, faktenbasierte Entscheidungen in komplexen Wissensdomänen benötigen.
Vollständig Open Source unter MIT-Lizenz auf GitHub.