Was ist Handbooks?

Eine Codebasis rein. Zwei Handbücher raus.

Handbooks schreibt dieselbe Karte deines Codes zweimal auf, denn es hat zwei sehr unterschiedliche Leser:

Darunter liegen dieselben Fakten — ein vom Parser gebauter Aufrufgraph — die beiden können sich also nie widersprechen. Eines ist auf Erzählung und Navigation optimiert, das andere auf Routing und Veraltungs-Erkennung.

Das Problem, klar benannt

Da ist ein Repository. Es ist zu groß, um es im Kopf zu behalten, und zu groß für ein Kontextfenster.

Wer einen Coding-Agenten bittet, „fehlgeschlagene Uploads dreimal zu wiederholen“, bekommt selbstbewusst die eine gefundene Upload-Funktion gepatcht — und verpasst die Konstante mit der Retry-Policy, die gespiegelte Implementierung im Batch-Worker, die Metrik, die die Versuche zählt, und den Test, der das alte Verhalten festschreibt.

Das ist kein Denkfehler. Es ist ein Routing-Fehler. Der Agent hat nie eine Karte gesehen.

Erst ausprobieren, dann weiterlesen

Alles Weitere ist bedeutungslos, wenn es nicht läuft. Das hier dauert etwa dreißig Sekunden, verbraucht null Tokens und braucht keinen API-Schlüssel:

git clone <this repo> && cd handbooks
pnpm install && pnpm build
pnpm demo

pnpm demo lässt die gesamte Toolchain gegen ein mitgeliefertes Beispielprojekt laufen, mit einem mitgelieferten Mock-LLM-Server. Am Ende liegen ein gerendertes Handbuch, eine HTML-Site, ein Agenten-Locator-Index und ein validiertes SKILL-Paket auf der Platte.

Die drei Ideen dahinter

1. Fakten kommen aus einem Parser, nicht aus einem Modell

Handbooks parst jede Quelldatei mit tree-sitter und baut einen typisierten Aufrufgraphen: Funktionen, Methoden, über self/Attribute/Parameter/Imports aufgelöste Aufrufkanten, Aufrufe, die den eigenen Code verlassen, und Aufrufe, die nicht aufgelöst werden konnten — in eine eigene Datei in Quarantäne gestellt, niemals geraten.

Dateien, die es gar nicht lesen oder parsen konnte, landen genauso in Quarantäne — eine Lücke, die sich aufzählen lässt, statt einer, die stillschweigend verschwindet.

Diese Schicht berührt nie ein LLM. Zweimal ausführen, zweimal denselben Graphen bekommen.

2. Prosa liegt über den Fakten — und ist als solche gekennzeichnet

Ein LLM schreibt den menschenlesbaren Teil: wozu eine Datei da ist, wie ein Subsystem zusammenhängt, welcher Zustand über welche Etappen fließt. Die Prosa ist immer im Graphen verankert, und wo sie scheitert, wird die Struktur trotzdem ausgeliefert — mit leerer Beschreibung.

Ein fehlender Satz ist besser als ein erfundener.

3. Die Karte ist zum Routen gebaut, nicht zum Lesen

Die Ausgabe ist keine Zusammenfassung des Codes. Sie ist ein Index, der die Frage beantwortet: „Welche Dateien, Funktionen und Zustände muss diese Änderung anfassen?“ — einschließlich der verstreuten, nicht offensichtlichen. Der Planner nutzt anschließend diesen Index, liest an jeder gefundenen Adresse den echten Quelltext und erzeugt einen Änderungsplan, der byte-genau genug ist, um mechanisch angewendet zu werden.

Was ein Lauf liefert

Für wen das ist

Was es kostet

• Node.js ≥ 20.11 und pnpm. Das ist die ganze Installation. Keine native Kompilierung, kein Python, kein node-gyp — die Parser sind WebAssembly.
• Ein OpenAI-kompatibler Endpunkt für die LLM-Phasen. Gehostetes OpenAI, Azure, vLLM, Ollama, LiteLLM, ein interner Proxy — alles, was /v1/chat/completions spricht. Auch ein Modell auf der eigenen Maschine.
• Gar nichts für handbook analyze — der Befehl, der zuerst laufen sollte.

Wohin als Nächstes