Das erste echte Handbuch

Das ist die volle Schleife auf einem echten Repository. Sie ist zum Befolgen in Reihenfolge geschrieben und stellt die kostenlosen Prüfungen mit Absicht vor die teuren.

alias handbook="node $(pwd)/packages/cli/dist/main.js"
export REPO=~/code/myrepo
export WORK=work/myrepo

Schritt 1 — Erst schauen, dann springen

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

{
  "language": "multi",
  "files": 412,
  "functions": 3187,
  "edgesKept": 9042,
  "edgesDropped": 611,
  "filesUnparsed": 3
}

Das kostet nichts und ist der Smoke-Test. Kein LLM, kein Schlüssel, keine Tokens.

Diese Punkte jetzt beheben. Jedes Problem hier wird später ein teureres Problem.

Schritt 2 — Das Handbuch generieren

Dieser Schritt kostet Tokens. Bei einem mittelgroßen Repository sind Minuten zu erwarten.

Günstig anfangen:

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

Das entspricht --detail brief und --synth-mode oneshot: eine kurze Karte pro Datei und ein Skelett in einem Durchgang. So zeigt sich am schnellsten, ob die Form des Handbuchs stimmt.

Einen Blick in $WORK/phase2/skeleton.yaml werfen. Sieht die Etappenliste nach dem eigenen System aus? Falls ja, aufrüsten:

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

--phase 2a --resume vertieft nur die Karten und überspringt Dateien, die bereits eine vollständige haben. Das bereits geprüfte Skelett bleibt erhalten.

Ist das Skelett falsch, stattdessen 2b mit der Actor-Critic-Schleife erneut ausführen:

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

Schritt 3 — Rendern

handbook render --work $WORK --title "MyRepo Handbook" \
    --html --html-single --agent-site --llms-txt

Kein LLM. Beliebig oft ausführen — in CI, bei jedem Commit.

Mit --source-base-url https://github.com/me/myrepo/blob/main wird jeder Dateipfad im Handbuch zu einem Link auf die echte Datei. Ohne dieses Flag enthält die Ausgabe überhaupt keine externen URLs — was bei einer privaten Codebasis zählt.

$WORK/handbook/html/overview.html öffnen und lesen. Das ist der Moment, um zu beurteilen, ob das Handbuch etwas taugt.

Schritt 4 — Für den Agenten paketieren

handbook skill --handbook $WORK/handbook --out skills/myrepo \
    --name myrepo --project "MyRepo" \
    --work $WORK --source $REPO \
    --agent-dir $WORK/handbook/agent

--work + --source zusammen erzeugen coverage.json: einen Content-Hash pro Datei. Genau das macht Handbuch-Drift erkennbar, statt später stillschweigend falsch zu sein.

--agent-dir liefert den Agenten-Index und seine Faktentabellen mit und gibt dem Routing-Protokoll des SKILLs seine grep-Rezepte — der Agent macht aus einem Symbolnamen so mit einem Befehl ein path:startLine-endLine, statt Prosa zu lesen und zu raten.

Schritt 5 — Validieren

handbook validate --skill skills/myrepo --source $REPO

Prüft die Struktur, den Frontmatter-Vertrag, die Konsistenz zwischen Index und Etappenseiten und re-hasht die Quellen, um zurückgefallene Seiten zu melden. Beendet sich bei Fehlschlag mit 2 — das ist also der Befehl für die CI.

Schritt 6 — Eine echte Änderung planen

handbook plan --source $REPO --handbook skills/myrepo/references \
    --request "Retry failed uploads three times before giving up" \
    --out plan.md

Eine rein lesende Agentenschleife: Sie listet, liest und greppt — ein Schreibwerkzeug hat sie gar nicht —, routet mit dem Handbuch, verifiziert gegen den echten Quelltext und schreibt plan.md.

Den Plan lesen. Wirklich lesen. Er endet mit einem maschinenlesbaren Deklarationsblock:

### EDIT 1

- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper

```old
    response = self._client.put(url, data)
```

```new
    response = self._retry(lambda: self._client.put(url, data), attempts=3)
```

```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```

Schritt 7 — Anwenden, mit Rückweg

handbook apply --source $REPO --plan plan.md --dry-run   # verify only, never writes
handbook apply --source $REPO --plan plan.md             # for real

Der Probelauf ist dem Geiste nach nicht optional. Er löst jeden Anker gegen den aktuellen Dateiinhalt auf und sagt genau, welche Änderungen landen würden.

Beim Anwenden wird das Backup-Verzeichnis ausgegeben. Am besten gleich beiseitekopieren, bevor es gebraucht wird:

handbook rollback --backup $REPO/.handbook-patches/2026-08-08T14-05-11-204Z

Rollback verweigert jede Datei, die sich nach dem Patch geändert hat, außer mit --force — denn ihre Wiederherstellung würde diese Arbeit stillschweigend zerstören. Alle vier Sicherheitsregeln stehen in Änderungen anwenden.

Schritt 8 — Das Handbuch nachziehen

Der Code hat sich bewegt. Nicht neu generieren — resyncen.

Ein Case ist ein selbst zusammengestelltes Verzeichnis:

cases/upload-retry/
  edited/       copy of the repo after the change   (required)
  plan.md       the plan from step 6                (optional — sharpens scope)
  change.diff   unified diff of the change          (optional — widens scope)

mkdir -p cases/upload-retry
cp -R $REPO cases/upload-retry/edited
cp plan.md cases/upload-retry/
handbook resync --case cases/upload-retry --work $WORK

Resync analysiert den editierten Baum neu, vergleicht alten und neuen Graphen und regeneriert nur, was sich geändert hat. Bereits gerenderte Ausgaben unter $WORK/handbook werden automatisch aufgefrischt.

Kein Endpunkt zur Hand? --no-llm frischt die strukturellen Fakten auf und markiert die Prosa als veraltet, statt so zu tun, als wäre sie aktuell.

Wenn das Repository sehr groß ist

Mehr dazu in Kosten und Performance.

Weiter