Teil 17. Qwen Code Hooks: Automatisierung des Arbeitsablaufs

Qwen Code Hooks sind Skripte, die zu vordefinierten Zeitpunkten einer Sitzung ausgeführt werden: beim Start, nach einer Benutzeranfrage, vor der Verwendung eines Tools, nach der Verwendung eines Tools, bei einem Tool-Fehler oder vor Beendigung der Antwort.

In SDD sind Hooks nicht dazu gedacht, Spezifikationen zu ersetzen. Sie dienen dazu, den Prozess weniger abhängig vom menschlichen Gedächtnis zu machen: dem Agenten Regeln in Erinnerung zu rufen, wichtige Ereignisse zu protokollieren, gefährliche Befehle zu stoppen, kurzen Kontext hinzuzufügen oder Spuren für spätere Prüfung zu sammeln.

Grundschema:

flowchart TD
  A["Qwen Code Ereignis"] --> B["Matcher-Filter"]
  B --> C["Hook<br/>command oder http"]
  C --> D{"Fortsetzen möglich?"}
  D -- "ja" --> E["Qwen Code setzt Arbeit fort"]
  D -- "nein" --> F["Qwen Code zeigt Stoppgrund an"]
  C --> G["Zusätzlicher Kontext"]
  G --> E

Wann Hooks angebracht sind

Ein Hook ist angebracht, wenn eine Aktion regelmäßig und gleichartig erfolgen soll:

• den Fakt der Tool-Verwendung protokollieren;
• eine kurze SDD-Merkhilfe nach /clear hinzufügen;
• eine potenziell gefährliche Kommando vor Ausführung prüfen;

• einen Tool-Fehler für die Retrospektive speichern;
• ein Ereignis an ein internes Journal senden;
• einen Link auf eine aktuelle Spezifikation in den Kontext einfügen;
• eine leichte Hintergrundprüfung nach Dateiänderung starten.

Ein Hook ist nicht nötig, wenn eine Regel ausreicht, die man in QWEN.md schreibt. Zum Beispiel ist „lies zuerst die Spezifikationen“ besser als Verhaltensregel zu belassen. Hingegen eignet sich „jeder Aufruf von Bash mit gefährlichem Befehl muss gestoppt werden" bereits für einen Hook.

Häufig benötigte Ereignisse

Für den Lehrprozess genügt es, einige Ereignisse zu verstehen.

| PreCompact | vor Kontextkomprimierung | wichtige Erkenntnisse vor Detailverlust sichern |

Man sollte nicht alles auf einmal anschließen. Beginnen Sie mit einem oder zwei Ereignissen, sonst wird der Prozess intransparent.

Hook-Typen

Qwen Code unterstützt mehrere Ausführungstypen.

command startet einen lokalen Befehl. Dies ist die Hauptvariante für Projekthooks: Python-Skript, Shell-Skript oder kleines Dienstprogramm.

http sendet ein Ereignis an eine HTTP-Adresse. Dies ist praktisch für zentrale Journale oder interne Audit-Systeme, erfordert aber sorgfältige Konfiguration von Secrets und erlaubten Adressen.

function ist für interne JavaScript-Funktionen auf Sitzungsebene gedacht. Für gewöhnliche Projekte reichen fast immer command oder http.

Was ein Hook erhält

Ein Kommando-Hook erhält JSON über die Standardeingabe. Darin enthalten sind allgemeine Felder: Sitzungskennung, aktuelles Verzeichnis, Ereignisname, Ereigniszeit. Für Tool-Ereignisse kommen Tool-Name, Tooleingaben, Ergebnis oder Fehler hinzu.

Ein Hook kann JSON über die Standardausgabe zurückgeben. Meist tut er eines von drei Dingen:

• ändert nichts und beendet sich einfach;

• fügt additionalContext hinzu, damit Qwen Code eine kurze Nachricht im nächsten Schritt sieht;
• verbietet eine Aktion vor Tool-Verwendung und erklärt den Grund.

Der Exit-Code ist ebenfalls wichtig. 0 bedeutet erfolgreiche Hook-Ausführung. 2 wird für blockierende Fehler verwendet. Andere Codes gelten als nicht-blockierender Fehler: der Hauptablauf von Qwen Code setzt sich fort, Details sind in der Fehlersuche sichtbar.

Minimale Dateiausstattung

Beispiele wurden aus der Lektion in separate Dateien ausgelagert:

• examples/hooks/settings-workflow.example.json — Beispiel für Hook-Anbindung;
• examples/hooks/pre_tool_guard.py — Schutz-Hook vor gefährlichen Befehlen;
• examples/hooks/log_tool_result.py — Protokollierung erfolgreicher und fehlgeschlagener Tool-Aufrufe;
• examples/hooks/inject_sdd_context.py — Hinzufügen kurzen SDD-Kontexts;
• examples/hooks/README.md — Kurzbeschreibung der Beispiele.

Anbindung im Lehrprojekt:

mkdir -p .qwen/hooks
cp sdd-qwen-code-ru/examples/hooks/pre_tool_guard.py .qwen/hooks/pre_tool_guard.py

cp sdd-qwen-code-ru/examples/hooks/log_tool_result.py .qwen/hooks/log_tool_result.py
cp sdd-qwen-code-ru/examples/hooks/inject_sdd_context.py .qwen/hooks/inject_sdd_context.py
chmod +x .qwen/hooks/*.py

Kopieren Sie die Beispieleinstellungen separat und führen Sie sie manuell mit der bestehenden .qwen/settings.json zusammen:

cp sdd-qwen-code-ru/examples/hooks/settings-workflow.example.json .qwen/settings-hooks.example.json

Überschreiben Sie keine laufenden Einstellungen für Modell, Autorisierung und MCP-Server.

Schutz-Hook vor Tool

PreToolUse eignet sich für Aktionen, die vor Ausführung geprüft werden müssen. Das verständlichste Beispiel sind Shell-Befehle.

Die Datei examples/hooks/pre_tool_guard.py prüft Bash-Eingaben auf mehrere gefährliche Muster: Löschen des Root- oder Home-Verzeichnisses, git reset --hard, git clean -fd, Ausführen heruntergeladener Skripte über die Shell. Dies ist keine vollwertige Sandbox. Es ist die letzte Prüfung vor offensichtlich riskanter Aktion.

Wichtig: Ein Schutz-Hook muss den Stoppgrund erklären. Wenn der Agent nur „Befehl verboten" sieht, beginnt er, Umwege zu erraten. Wenn er den konkreten Grund sieht, kann er eine sichere Alternative vorschlagen.

Tool-Protokollierung

PostToolUse und PostToolUseFailure eignen sich für Ereignisjournale. In SDD ist ein solches Journal nicht für sich selbst nützlich, sondern als Quelle für die Retrospektive:

• welche Befehle häufig fehlgeschlagen sind;
• welche Dateien der Agent vor dem Fehler geändert hat;
• welche Prüfungen manuell gestartet wurden;
• welche Aktionen in validation.md überführt werden sollten;
• welche Regeln in QWEN.md festgehalten werden sollten.

Die Datei examples/hooks/log_tool_result.py schreibt kompakte Einträge in .qwen/hooks/logs/tool-events.jsonl. Dies ist ein lokales technisches Journal. Speichern Sie darin keine Secrets, große Modellantworten und vollständige Umgebungsdumps.

Für die Protokollierung schaltet man üblicherweise den asynchronen Modus ein, damit der Hauptablauf nicht auf die Journal-Schreibung wartet.

SDD-Kontext hinzufügen

SessionStart und UserPromptSubmit eignen sich für kurze Kontextergänzungen. Dies ist besonders nach /clear nützlich: Der Chat-Verlauf ist gelöscht, aber der Projektprozess soll sichtbar bleiben.

Die Datei examples/hooks/inject_sdd_context.py liest nicht das gesamte Projekt. Sie prüft die Existenz von QWEN.md, specs/mission.md, specs/tech-stack.md und specs/roadmap.md, dann fügt sie eine kurze Merkhilfe hinzu. Ein solcher Hook darf nicht zur versteckten Spezifikation werden. Er leitet den Agenten nur zu den Dateien, in denen die Quelle der Wahrheit lebt.

Hooks und Prüfungen

Es ist verlockend, npm test nach jeder Dateiänderung zu starten. Normalerweise ist das eine schlechte Idee: Der Agent wird langsam, und Fehler kommen im unpassenden Moment. Prüfungen besser aufteilen:

• leichte Prüfungen können automatisch und asynchron gestartet werden;
• schwere Prüfungen werden durch expliziten Schritt aus validation.md ausgelöst;
• blockierende Hooks nur für gefährliche Aktionen verwenden;
• Ergebnisse automatischer Prüfungen sollen in Bericht oder Journal gelangen, nicht im Rauschen verloren gehen.

Wenn ein Hook eine Prüfung startet, sollte er eine einzige Frage beantworten. Zum Beispiel: „Ist nach Änderung einer TypeScript-Datei die schnelle Typprüfung gefallen?" Einen Hook nicht in einen vollständigen Branch-Merge-Prozess verwandeln.

Sicherheitsregeln

Hooks werden in Ihrer Umgebung und mit Ihren Rechten ausgeführt. Behandeln Sie sie daher wie gewöhnlichen Automatisierungscode.

Minimale Regeln:

• Projekthooks im Repository speichern und wie Code reviewen;
• timeout setzen, damit hängende Hooks die Sitzung nicht blockieren;
• asynchronen Modus für Journale und Hintergrundprüfungen nutzen;
• keine Secrets in die Kommandozeile übergeben;
• für HTTP-Hooks eine Liste erlaubter Umgebungsvariablen festlegen;
• keine Quellen und Prompts ohne explizite Teamentscheidung an externe Dienste senden;
• keine Hooks schreiben, die heimlich Projektdateien ändern;
• verständliche Nachricht bei Aktionsblockierung hinzufügen.

Projekthooks sollten nur in vertrauenswürdigen Verzeichnissen aktiviert werden. Wenn Sie ein fremdes Repository öffnen, lesen Sie zuerst .qwen/settings.json und .qwen/hooks/, bevor Sie die automatische Ausführung erlauben.

Was nicht automatisiert werden sollte

Schlechte Ideen:

• Code nach jedem Tool-Fehler automatisch korrigieren;
• alle Befehle blockieren, die nicht in eine vorgefertigte Liste passen;
• große Spezifikationsfragmente bei jeder Anfrage in den Kontext einfügen;
• vollständige Modellantworten in ein dauerhaftes Journal schreiben;
• Speicher, Prüfung, Formatierung und Sicherheit in einem Skript vermischen;

• Hooks als versteckten Ersatz für requirements.md, plan.md und validation.md verwenden.

Ein Hook sollte klein und verständlich sein. Wenn Sie seinen Zweck nicht in einem Satz erklären können, macht er wahrscheinlich zu viel.

Praktische Übung

1. Kopieren Sie die Hook-Beispiele in das Lehrprojekt.
2. Binden Sie pre_tool_guard.py nur an PreToolUse für Bash an.
3. Binden Sie log_tool_result.py an PostToolUse und PostToolUseFailure.
4. Binden Sie inject_sdd_context.py an SessionStart und UserPromptSubmit.
5. Starten Sie Qwen Code im Projekt und führen Sie /clear aus.
6. Bitten Sie den Agenten, die Roadmap zu lesen und das nächste Feature ohne Dateiänderungen vorzuschlagen.
7. Prüfen Sie, dass das Journal in .qwen/hooks/logs/tool-events.jsonl erschienen ist.
8. Probieren Sie einen gefährlichen Befehl in sicherer Testform aus und vergewissern Sie sich, dass der Schutz-Hook die Blockierung erklärt.

Beantworten Sie nach der Übung schriftlich:

• welcher Hook dem Prozess wirklich geholfen hat;
• welcher Hook lästig war;
• was besser in QWEN.md überführt wird;
• was besser als manueller Schritt in validation.md bleibt.

Verbindung zu folgenden Teilen

Im nächsten Teil werden Hooks aus Sicherheitssicht betrachtet: Sie können den Prozess schützen, erfordern aber selbst ein Review. Danach wird im Teil über SQLite-Speicher derselbe Mechanismus zum Sammeln von Ereignissen, Hintergrundzusammenfassung und Hinzufügen kurzer Erinnerung in neue Sitzungen genutzt.