Selbstgebauter x86_64-Kernel – warum moderne KI-Dokumentation versagt

Vor sechs Monaten startete ich ein ambitioniertes Projekt: die Entwicklung von TaterTOS64, einem x86_64-Kernel. Was als technisches Experiment begann, wurde schnell zu einer Herausforderung für meine Dokumentationsstrategie. Mit über 10.000 Zeilen Code in C, Assembler und Linker-Skripten wurde klar, dass ich mehr brauchte als klassische Kommentare im Quelltext. Ich benötigte ein System, das die architektonischen Entscheidungen erklärt – wie Interrupt-Vektoren an den Scheduler übergeben werden oder wie die Paging-Logik mit der physischen Speicherzuweisung verknüpft ist.

Um diese Lücke zu schließen, griff ich auf moderne KI-Tools zurück – und scheiterte kläglich. Drei zentrale Probleme wurden offensichtlich:

• Kontextverlust: Die Tools verstanden einzelne .c-Dateien perfekt, ignorierten aber die #include-Ketten. Sie konnten nicht nachvollziehen, wo Konstanten wie aus paging.h tatsächlich definiert waren.

• Halluzinationen: Die KI erklärte komplexe Abläufe im Scheduler, verwies dabei aber auf nicht existente Funktionen oder deutete reine Assembler-Einstiegspunkte als hochsprachliche C-Signaturen.

• Abonnement-Falle: Als Kerneldesigner wollte ich keine monatlichen Gebühren für ein Cloud-Tool zahlen, das mir Zugang zu meinen eigenen Dokumentationsdaten gewährt.

Nach zwei Wochen des Frusts beschloss ich, die Kernentwicklung zu pausieren – und stattdessen ein Dokumentationstool zu bauen, das meine Anforderungen erfüllt. Das Ergebnis: TaterBookBuilder, ein lokaler Dokumentationscompiler, der ohne Cloud-Dienste auskommt.

Wie TaterBookBuilder die Dokumentationskrise löst

Anstatt herkömmliche KI-Tools als Blackbox zu nutzen, setzte ich auf eine deterministische Analyse-Engine als Fundament. Diese Engine durchläuft den Quellcode bevor die KI überhaupt ins Spiel kommt – und schafft damit eine verlässliche Basis für die spätere Dokumentationserstellung.

1. Abbildung der Include-Strukturen

Die Engine kartiert alle #include-Anweisungen (C) und %include-Direktiven (Assembler) und verknüpft sie mit ihren ursprünglichen Definitionsorten im Repository. Statt zu raten, woher ein Typ oder eine Konstante stammt, zeigt das Tool eine klare Hierarchie an.

2. AST-basierte Systemanalyse

Mithilfe von Roslyn (für C#) und angepassten Regex-Parsern analysiert die Engine die abstrakte Syntaxbaum-Struktur (AST) des Codes. Sie identifiziert dabei kritische Systemgrenzen:

• Kernel-Bereiche: Verzeichnisse oder Dateien, die Systemaufrufe oder Scheduler-Logik enthalten.

• Benutzerbereich: Komponenten, die in isolierten Modulen laufen.

• Syscall-Einstiegspunkte: Automatische Erkennung von Übergängen zwischen Benutzer- und Kernelmodus.

Diese Analyse bildet die Grundlage für eine logische Architektur-Dokumentation, die weit über einfache Quelltextkommentare hinausgeht.

3. Das „Evidence-Map“-Prinzip: Beweise statt Vermutungen

Der entscheidende Durchbruch war die Einführung eines Evidence-Map-Systems. Jede Aussage in der generierten Dokumentation wird mit einer eindeutigen Referenz belegt – einer Datei und einem Zeilenbereich im Quellcode.

Beispiel: Wenn die Dokumentation behauptet „Der Scheduler verwendet ein Round-Robin-Verfahren“, dann verweist eine Fußnote direkt auf:

src/kernel/sched.c:L45-L120

Dieses System eliminiert Spekulationen und gibt Entwicklern die Gewissheit, dass jede Aussage durch den Code selbst untermauert ist. Keine vagen KI-Antworten mehr – nur noch nachweisbare Architektur.

Philosophie: Lokale Kontrolle über Dokumentation

Dokumentation ist ein dauerhaftes Asset, kein veränderliches Cloud-Produkt. Deshalb setzt TaterBookBuilder auf:

• Keine Abhängigkeiten: Das Tool wird als 77 MB großes Linux AppImage ausgeliefert, inklusive statisch eingebundener Pandoc-Binärdatei. Keine Installation, keine externen Bibliotheken.

• Einmaliger Kauf, ewiger Zugang: Das Preismodell orientiert sich an JetBrains: Nach dem Kauf gehört die Version für immer dem Nutzer. Ein Jahr Wartung und Updates sind inklusive, doch selbst nach Ablauf der Wartung bleibt die Dokumentationspipeline funktionsfähig.

• Keine Cloud-Gebühren: Alle Analysen und Dokumentationen laufen lokal ab. Die Daten verlassen nie das eigene System.

Dieser Ansatz passt perfekt zum Geist von Kernels und Systemsoftware: Rock-solid, reproduzierbar und unabhängig von externen Diensten.

Ein Aufruf an Systementwickler: Wie dokumentiert ihr eure Architektur?

TaterBookBuilder ist kein fertiges Produkt, sondern eine Einladung zum Dialog. Ich lade alle Systemprogrammierer ein, die ähnliche Probleme mit KI-Dokumentationstools kennen:

• Wie geht ihr mit dem „Vertrauensproblem“ bei generativer KI um?

• Nutzt ihr lokale Lösungen für Architektur-Dokumentation?

• Welche Tools oder Methoden haben euch bei großen Codebasen geholfen?

Kernels sind komplexe Systeme, und ihre Dokumentation darf nicht weniger präzise sein als ihr Code. Vielleicht ist TaterBookBuilder ein Schritt in die richtige Richtung – oder zumindest ein Denkanstoß.

Die Zukunft der Systemdokumentation liegt nicht in der Cloud, sondern in lokaler Intelligenz und nachweisbarer Architektur. Und sie beginnt mit dem ersten Schritt: dem Code selbst.