Ein Handbook generieren

handbook generate --source <repo> --work <workdir> [options]

Dies ist der einzige teure Befehl. Auf dieser Seite geht es ausschließlich darum, weniger dafür auszugeben und mehr daraus herauszuholen.

Günstig starten, dann aufrüsten

handbook analyze --source $REPO --work $WORK

handbook generate --source $REPO --work $WORK

handbook generate --source $REPO --work $WORK --phase 2a --detail deep --resume

handbook generate --source $REPO --work $WORK --phase 2b,2c,3 --synth-mode doctor

In dieser Reihenfolge bezahlen Sie nie für tiefe Karten auf einem Skelett, das Sie gleich wieder verwerfen.

--detail brief vs. deep

Deep lohnt sich, wenn ein Agent das Handbook nutzen wird, denn erst die Notizen pro Funktion machen aus einer Etappenseite ein Adressbuch. Brief ist richtig für einen ersten Durchlauf, für ein sehr großes Repository oder wenn es Ihnen vor allem um die Struktur geht.

Beides lässt sich mischen: Generieren Sie überall brief, und führen Sie danach --phase 2a --detail deep --resume erneut aus, nachdem Sie --source auf das Unterverzeichnis gerichtet haben, das Ihnen am wichtigsten ist.

--synth-mode oneshot vs. doctor

oneshot synthetisiert ein Skelett in einem Durchgang. Schnell, günstig, meist brauchbar.

doctor führt eine Actor-Critic-Reparaturschleife aus: höchstens drei Strukturänderungen vorschlagen, sie von drei Kritikern (Ingenieur, Architekt, Leser) prüfen lassen, die Überlebenden mechanisch gegen den echten Graphen validieren, anwenden, neu zuweisen, wiederholen.

--strategy file vs. member

file (Standard) — das LLM synthetisiert das Skelett; eine Quelldatei ist die Blatteinheit. Skaliert auf große Repositories. Verwenden Sie dies, sofern nichts dagegen spricht.

member — Sie verfassen skeleton.yaml; einzelne Funktionen und Methoden werden in Ihre Etappen klassifiziert, und die Artefakte auf Dateiebene werden daraus abgeleitet.

metadata:
  version: 1
  archetype: HTTP API server
stages:
  - id: stage-1
    title: Request intake
    description: Accepting connections, parsing requests, and routing them.
    parent: null
    children: []
    crosscut: false
  - id: stage-2
    title: Business logic
    description: What the service actually does with a validated request.
    parent: null
    children: []
    crosscut: false
  - id: crosscut-1
    title: Configuration and logging
    description: Cross-cutting infrastructure used by every stage.
    parent: null
    children: []
    crosscut: true

handbook generate --source $REPO --work $WORK --strategy member --skeleton skeleton.yaml

Member kostet mehr — jede Funktion wird klassifiziert —, liefert aber straffere Prosa, und Phase 2c wird kostenlos, weil die Organisation deterministisch abgeleitet wird.

Phasen einzeln ausführen

--phase 1        # just the graph (same as `handbook analyze`)
--phase 2a       # just the cards
--phase 2b       # just skeleton + assignment
--phase 2c       # just the grouping
--phase 3        # just narration + registers
--phase 2        # 2a + 2b + 2c
--phase 2c,3     # a comma list

Jede Phase liest nur die Artefakte ihrer Vorstufen, daher ist das immer sicher. Die häufigsten Fälle:

Fortsetzen und Caching

• --resume überspringt Dateien, die bereits eine vollständige Karte in der angeforderten Tiefe haben. Karten werden geschrieben, sobald sie fertig sind, daher ist Ctrl-C immer sicher.
• --llm-cache cacht rohe Antworten unter <work>/phase3/cache, geschlüsselt nach Modell, Prompt und Optionen. Wiederholte Läufe beim Iterieren werden nahezu kostenlos.
• --refresh ignoriert die Caches von Phase 3. Verwenden Sie es, wenn Sie die Prompt-Eingaben geändert haben, der Cache-Schlüssel das aber nicht bemerkt hat — zum Beispiel nach dem manuellen Bearbeiten von skeleton.yaml.

--refresh deaktiviert --llm-cache für diesen Lauf — mit Absicht.

Bei der Arbeit zusehen

handbook generate --source $REPO --work $WORK -v

[scan] auto root=/Users/me/code/api
[scan] typescript: 284 files
[2a] batch 12/36 · 96 cards
[2b] 9 stages; 0 files unassigned
[3] narrating stage-4 (2 children)

Der Token-Verbrauch landet in run-manifest.json, sobald der Lauf abgeschlossen ist.

Wenn das Ergebnis falsch ist

Mehr dazu unter Fehlerbehebung.