Lernleitfaden: Teil 17. Qwen Code Hooks: Automatisierung des Arbeitsablaufs

Thema: Teil 17. Qwen Code Hooks: Automatisierung des Arbeitsablaufs

Schwierigkeitsgrad: Mittelstufe

Geschätzte Studienzeit: 4-6 Stunden (Theorie: 1,5 Stunden, Praxis: 2,5-4,5 Stunden)

Voraussetzungen: Grundlegendes Verständnis der Qwen Code-Architektur und der Sitzungsverwaltung

Kenntnis des JSON-Formats und Fähigkeit zur Bearbeitung von Konfigurationsdateien

Python-Programmierkenntnisse (Skriptniveau)

Verständnis des SDD-Konzepts (Specification-Driven Development) aus vorherigen Kursteilen

Erfahrung mit der Kommandozeile und grundlegenden Shell-Befehlen

Vertrautheit mit den Dateien QWEN.md, specs/mission.md, specs/tech-stack.md, specs/roadmap.md

Lernziele: Einen minimalen Satz von Hooks (PreToolUse, PostToolUse, SessionStart, UserPromptSubmit) in einem Übungsprojekt gemäß den Kursbeispielen konfigurieren und verbinden

Situationen unterscheiden, in denen ein Hook angebracht ist, und solche, in denen eine Regel in QWEN.md oder validation.md ausreicht

Einen Schutz-Hook zur Blockierung gefährlicher Befehle mit verständlicher Erklärung des Anhaltegrunds implementieren

Ereignisprotokollierung von Instrumenten im JSONL-Format mit asynchronem Betriebsmodus organisieren

Sicherheitsregeln bei der Arbeit mit Hooks anwenden: Code-Review, Timeouts, Geheimnis-Isolation, Überprüfung vertrauenswürdiger Verzeichnisse

Überblick: Qwen Code Hooks sind ein Mechanismus zur Automatisierung des Arbeitsablaufs, der es ermöglicht, Skripte in Schlüsselmomenten einer Sitzung auszuführen: beim Start, nach einer Benutzeranfrage, vor und nach der Verwendung eines Instruments, bei einem Fehler oder vor Beendigung der Antwort. Im SDD-Kontext ersetzen Hooks keine Spezifikationen, sondern machen den Prozess weniger abhängig vom menschlichen Gedächtnis: Sie erinnern an Regeln, protokollieren Ereignisse, blockieren gefährliche Aktionen, fügen kurzen Kontext hinzu und sammeln Spuren für Retrospektiven. Der Schlüsselprinzip: Ein Hook muss klein, verständlich und auf eine Aufgabe ausgerichtet sein. Wenn sein Zweck nicht in einem Satz erklärt werden kann – tut er zu viel. Der Kurs behandelt drei Haupttypen von Hooks (command, http, function), sechs Schlüsselereignisse, die Praxis des Anschließens von Beispielen und kritisch wichtige Sicherheitsregeln.

Schlüsselkonzepte: Ereignis (event): Auslöser, der einen Hook aktiviert. Schlüsselereignisse: SessionStart (Sitzungsstart), UserPromptSubmit (nach Benutzeranfrage), PreToolUse (vor Instrumentennutzung), PostToolUse (nach erfolgreicher Nutzung), PostToolUseFailure (nach Instrumentenfehler), Stop (vor Antwortbeendigung), PreCompact (vor Kontextkomprimierung). Jedes Ereignis hat seine eigene Semantik im SDD-Prozess.

Filter matcher: Komponente, die bestimmt, ob ein Hook für ein bestimmtes Ereignis ausgelöst werden soll. Ermöglicht gezielte Hook-Konfiguration: z.B. PreToolUse nur für das Bash-Instrument, nicht für alle Instrumente.

Hook-Ausführer (command/http/function): Typ des ausgeführten Szenarios. Command – lokaler Befehl (Python-Skript, Shell-Skript), Hauptvariante für Projekte. HTTP – Sendung an eine externe Adresse für zentralisierte Protokollierung. Function – interne JS-Funktion der Sitzung, selten in normalen Projekten benötigt.

Hook-Eingabe-JSON: Daten, die dem Hook über stdin übergeben werden: Sitzungskennung, aktuelles Verzeichnis, Ereignisname, Zeitstempel, für Instrumente – Instrumentenname, Eingabedaten, Ergebnis oder Fehler.

Hook-Ausgabe-JSON: Ergebnis der Hook-Arbeit über stdout. Drei Schlüsselvarianten: leere Antwort (ändert nichts), additionalContext (fügt kurze Nachricht zum Kontext hinzu), Aktionsblockierung mit Erklärung des Grundes.

Hook-Exit-Code: 0 – erfolgreiche Ausführung, 2 – blockierender Fehler (hält Aktion an), andere Codes – nicht-blockierender Fehler (sichtbar in der Fehlersuche, aber Prozess wird fortgesetzt).

Asynchroner Modus: Modus, in dem der Hook den Hauptablauf von Qwen Code nicht blockiert. Kritisch wichtig für Protokollierung und Hintergrundprüfungen, damit die Sitzung nicht auf Abschluss einer Nebenaufgabe wartet.

Schutz-Hook (pretooluse guard): Hook, der gefährliche Aktionen vor ihrer Ausführung blockiert. Beispiele gefährlicher Muster: rm -rf / oder ~, git reset --hard, git clean -fd, Ausführung heruntergeladener Skripte über sh. Ersetzt keine Sandbox, dient aber als letzte Prüfung.

Instrumentenprotokollierung (posttooluse/posttoolusefailure): Dokumentation von Instrumentennutzung für spätere Retrospektive: Absturzhäufigkeit, geänderte Dateien, manuelle Prüfungen, Kandidaten für Übertragung in validation.md oder QWEN.md.

SDD-Kontext-Injektion: Hinzufügen einer kurzen Projekterinnerung über SessionStart und UserPromptSubmit, besonders nach /clear. Hook prüft Vorhandensein Schlüsseldateien (QWEN.md, specs/mission.md u.a.) und lenkt den Agenten zur Wahrheitsquelle, ohne deren Inhalt zu duplizieren.

Hook-Timeout: Maximale Ausführungszeit eines Hooks, die Blockierung der Sitzung durch ein hängendes Skript verhindert.

Sicherheitsregeln für Hooks: Hooks werden mit Benutzerrechten in seiner Umgebung ausgeführt. Anforderungen: Code-Review der Hooks, Timeouts, asynchroner Modus für Hintergrundaufgaben, Geheimnis-Isolation, explizite Liste erlaubter Variablen für HTTP, Verbot stummer Dateiänderungen, verständliche Nachrichten bei Blockierung, Überprüfung der Verzeichnisvertrauenswürdigkeit vor Autostart.

Praxisübungen: Titel: Installation und grundlegendes Anschließen von Hooks

Problem: Kopieren Sie die Hook-Beispiele aus dem Kurs-Repository in das Übungsprojekt, konfigurieren Sie Ausführungsrechte und schließen Sie settings-hooks.example.json an, ohne bestehende Einstellungen für Modell, Autorisierung und MCP-Server zu überschreiben.

Lösung: 1. Verzeichnis erstellen: mkdir -p .qwen/hooks

1. Drei Hooks kopieren: cp sdd-qwen-code-ru/examples/hooks/pre_tool_guard.py .qwen/hooks/; cp sdd-qwen-code-ru/examples/hooks/log_tool_result.py .qwen/hooks/; cp sdd-qwen-code-ru/examples/hooks/inject_sdd_context.py .qwen/hooks/
2. Ausführungsrechte setzen: chmod +x .qwen/hooks/*.py
3. Beispieleinstellungen separat kopieren: cp sdd-qwen-code-ru/examples/hooks/settings-workflow.example.json .qwen/settings-hooks.example.json
4. Inhalt von settings-hooks.example.json manuell mit bestehendem .qwen/settings.json zusammenführen, Abschnitte model, auth, mcp beibehalten
5. JSON-Gültigkeit prüfen: python -m json.tool .qwen/settings.json

Schwierigkeitsgrad: Anfänger

Titel: Konfiguration des Schutz-Hooks für Bash

Problem: Schließen Sie pre_tool_guard.py nur an das Ereignis PreToolUse für das Bash-Instrument an. Testen Sie die Funktion an einem sicheren Testbefehl mit gefährlichem Muster (z.B. git reset --hard in einem Test-Repository). Stellen Sie sicher, dass der Hook den Blockierungsgrund erklärt und nicht einfach nur verbietet.

Lösung: 1. In .qwen/settings.json einen Eintrag im Abschnitt hooks mit matcher: {"event": "PreToolUse", "tool": "Bash"}, Ausführer: {"type": "command", "command": ".qwen/hooks/pre_tool_guard.py"} hinzufügen

1. Test-Git-Repository erstellen: mkdir /tmp/test-guard && cd /tmp/test-guard && git init && echo 'test' > file.txt && git add . && git commit -m 'init'
2. In Qwen Code versuchen, über Bash auszuführen: git reset --hard HEAD~
3. Prüfen, dass Hook Exit-Code 2 zurückgab, Qwen Code Anhaltegrund mit Erklärung des konkreten gefährlichen Musters anzeigte
4. Sichere Alternative versuchen: git log --oneline -5 und sicherstellen, dass sie durchläuft
5. Prüfen, dass andere Instrumente (Read, Edit) vom Hook nicht betroffen sind

Schwierigkeitsgrad: Mittelstufe

Titel: Protokollierung im asynchronen Modus

Problem: Schließen Sie log_tool_result.py an die Ereignisse PostToolUse und PostToolUseFailure an. Konfigurieren Sie den asynchronen Modus, damit die Protokollierung die Sitzung nicht verlangsamt. Führen Sie mehrere Instrumentenoperationen aus und analysieren Sie das entstandene Protokoll.

Lösung: 1. Zwei Hooks in settings.json mit gleichem Ausführer, aber verschiedenen Ereignissen hinzufügen: PostToolUse und PostToolUseFailure, command: .qwen/hooks/log_tool_result.py

1. "async": true für beide Hooks setzen
2. Qwen Code starten, /clear ausführen, Agenten bitten, roadmap zu lesen und nächstes Feature vorzuschlagen
3. Protokollerstellung prüfen: ls -la .qwen/hooks/logs/tool-events.jsonl
4. Einträge analysieren: jq . .qwen/hooks/logs/tool-events.jsonl | head -20
5. Sicherstellen, dass Einträge kompakt sind: enthalten event_type, tool_name, timestamp, success/failure, aber keine vollständigen Umgebungsdumps und keine Geheimnisse
6. Prüfen, dass bei Instrumentenfehler (z.B. Lesen nicht existierender Datei) Eintrag sich von erfolgreichem unterscheidet

Schwierigkeitsgrad: Mittelstufe

Titel: Kontext-Injektion nach /clear

Problem: Schließen Sie inject_sdd_context.py an SessionStart und UserPromptSubmit an. Prüfen Sie, dass der Agent nach dem Befehl /clear eine kurze Erinnerung an Schlüsselprojektdateien erhält, aber nicht die vollständigen Spezifikationstexte.

Lösung: 1. Hooks in settings.json für SessionStart und UserPromptSubmit mit Befehl .qwen/hooks/inject_sdd_context.py hinzufügen

1. Sicherstellen, dass im Projekt mindestens QWEN.md und specs/mission.md vorhanden sind
2. Sitzung starten, /clear ausführen
3. In nächster Anfrage fragen: „Welche Spezifikationen gibt es im Projekt?"
4. Prüfen, dass Agent Dateivorhandensein erwähnt, aber Inhalt nicht vollständig zitiert
5. Hook-Logs oder additionalContext-Ausgabe im Qwen Code-Debugmodus prüfen
6. Sicherstellen, dass bei fehlendem specs/roadmap.md Hook Situation korrekt behandelt, nicht abstürzt und nichts Überflüssiges hinzufügt

Schwierigkeitsgrad: Mittelstufe

Titel: Analyse und Refactoring der Hooks nach der Praxis

Problem: Beantworten Sie nach Abschluss der Übungen 1-4 schriftlich vier Fragen: Welcher Hook hat dem Prozess wirklich geholfen; welcher war lästig; was sollte besser in QWEN.md übertragen werden; was sollte besser als manueller Schritt in validation.md bleiben. Passen Sie die Konfiguration basierend auf den Antworten an.

Lösung: 1. Notizen während der Übungen führen: Momente festhalten, wenn Hook nützlich auslöste, und wenn er störte

1. Beispiel nützlicher Auslösung: pre_tool_guard verhinderte git reset --hard – beibehalten
2. Beispiel Lästigkeit: inject_sdd_context löst bei jedem UserPromptSubmit aus und dupliziert Information aus QWEN.md – Übertragung der Regel „zuerst QWEN.md lesen" in QWEN.md selbst in Betracht ziehen, Hook nur für SessionStart beibehalten
3. Beispiel für QWEN.md: „Nach /clear auf specs/roadmap.md achten" – Verhaltensregel, keine Automatisierung erforderlich
4. Beispiel für validation.md: „npm test vor Commit ausführen" – schwere Prüfung, ungeeignet für Hook
5. settings.json anpassen, Hooks basierend auf Analyse löschen oder ändern, Entscheidung in Commit-Kommentar dokumentieren

Schwierigkeitsgrad: Fortgeschritten

Fallstudien: Titel: Schutz von Produktionsdatenbanken vor versehentlicher Löschung

Szenario: Ein Team von fünf Entwicklern nutzt Qwen Code für Arbeit mit einer mikroservicebasierten Node.js-Architektur. Das Projekt enthält Docker-Container mit produktionsähnlichen Daten für lokales Testen. Ein Entwickler bat den Agenten versehentlich, docker volume prune während der Fehlersuche auszuführen, was zur Löschung von Volumes mit Testdaten geführt hätte, deren Wiederherstellung 2-3 Stunden dauerte.

Herausforderung: Regeln in QWEN.md verhinderten gefährliche Befehle nicht im Moment: Der Entwickler im Flow-Zustand konnte die Warnung übersehen. Manuelle Prüfung jedes Bash-Befehls durch den Agenten war unzuverlässig. Eine automatische, aber erklärbare Barriere gegen zerstörerische Operationen ohne Verlangsamung der normalen Arbeit war erforderlich.

Lösung: Das Team implementierte den Schutz-Hook pre_tool_guard.py und erweiterte dessen Muster: docker volume prune, docker system prune -a, rm in Verzeichnissen mit .env-Dateien, alle Befehle mit DROP DATABASE hinzugefügt. Hook nur auf PreToolUse + Bash konfiguriert. Bei Blockierung gibt Hook JSON mit Erklärung zurück: „Der Befehl docker volume prune löscht alle ungenutzten Docker-Volumes, einschließlich Volumes mit Testdaten des Projekts X. Für sichere Bereinigung verwenden Sie docker volume rm mit konkretem Volume-Namen oder bestätigen Sie über validation.md Schritt 'Manuelle Docker-Ressourcen-Bereinigung'." Der Entwickler sieht den Grund und kann den sicheren Weg wählen.

Ergebnis: In drei Monaten blockierte der Hook 12 potenziell zerstörerische Befehle. In 10 Fällen wählten die Entwickler sichere Alternativen. In 2 Fällen gingen sie bewusst durch validation.md. Wiederherstellungszeit für Testdaten sank von 2-3 Stunden auf null. Hook wurde Teil des Onboarding-Checklists neuer Entwickler.

Gelernte Lektionen: Blockierung ohne Erklärung provoziert Umgehungsversuche; konkreter Grund leitet zu sicherer Lösung

Hook muss spezialisiert sein: Docker-Befehlsschutz stört normale Arbeit mit git und Dateien nicht

Hook-Integration mit validation.md schafft Verbindung zwischen automatischer und manueller Prüfung, ohne Prozess zu brechen

Verwandte Konzepte: Schutz-Hook (PreToolUse guard)

Hook-Exit-Code

Hook-Ausgabe-JSON mit Erklärungsgrund

Verbindung von Hooks mit validation.md

Titel: Übermaß an Hooks und Rückkehr zur Einfachheit

Szenario: Ein Team von drei Personen enthusiastisch Hooks in alle verfügbaren Ereignisse implementiert: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, PreCompact. Jeder Hook erledigte 3-4 Aufgaben: Protokollierung, Prüfung, Kontexthinzufügung, Formatierung. Qwen Code-Sitzungen dauerten 2,5-mal länger, Agent begann, Teil des Kontexts aufgrund von Überlastung zu ignorieren, Entwickler verstanden nicht mehr, woher eine bestimmte Systemreaktion kam.

Herausforderung: Klassische Automatisierungsfalle: Hooks waren nicht mehr transparente Werkzeuge und verwandelten sich in versteckte Logik. Das Team konnte Sitzungsverhalten nicht in einem Satz erklären. Fehlersuche erforderte Nachverfolgung von 7 Hooks, von denen viele konfliktierten: einer fügte Kontext hinzu, ein anderer modifizierte ihn, ein dritter protokollierte bereits geänderte Version.

Lösung: Das Team führte eine Prüfung nach dem Prinzip „ein Satz – ein Hook" durch. Für jeden Hook wurde gefragt: „Was macht er in einem Satz?" Hooks, die die Prüfung nicht bestanden, wurden getrennt oder gelöscht. Endergebnis der Konfiguration: SessionStart + inject_sdd_context (an Projekt nach /clear erinnern), PreToolUse + pre_tool_guard nur für Bash (Gefährliches stoppen), PostToolUseFailure + log_tool_result async (Fehler für Retrospektive speichern). Alles andere in QWEN.md oder validation.md übertragen.

Ergebnis: Sitzungszeit kehrte zum Ursprünglichen zurück. Transparenz wiederhergestellt: Jeder Entwickler konnte Verhalten in 30 Sekunden erklären. Fehlerprotokoll wurde sauber und nützlich für wöchentliche Retrospektive. Regel „nicht mehr als drei Hooks pro Projekt" wurde in Team-Richtlinien aufgenommen.

Gelernte Lektionen: Hook muss eine Aufgabe lösen und in einem Satz erklärbar sein; sonst wird er zu technischer Schuld

Mit einem bis zwei Hooks beginnen, nicht alles sofort anschließen – sonst ist Prozess intransparent

Protokollierung, Prüfung, Formatierung und Sicherheit dürfen nicht in einem Skript gemischt werden

Verwandte Konzepte: Regel „ein Satz – ein Hook"

Asynchroner Modus

Was nicht automatisiert werden sollte

Verbindung von Hooks mit QWEN.md und validation.md

Studientipps: Beginnen Sie die Praxis streng mit einem Hook – am besten PreToolUse guard, da sein Nutzen anschaulich und Risiken verständlich sind. Fügen Sie weitere nur nach reflektierter Analyse des ersten hinzu.

Führen Sie ein „Hook-Tagebuch" während der Praxis: Jeden Auslösung, Reaktionszeit, Nutzen oder Lästigkeit festhalten. Dies erleichtert die finale Refactoring-Übung.

Verwenden Sie jq oder python -m json.tool zum Lesen des tool-events.jsonl-Protokolls – das JSONL-Format ist speziell für zeilenweise Verarbeitung gewählt, versuchen Sie nicht, es als normales JSON-Array zu lesen.

Erstellen Sie eine Test-„Sandbox" für Prüfung des Schutz-Hooks: separates Git-Repository, Docker-Volumes mit unnötigen Daten, temporäre Dateien. Testen Sie niemals die Blockierung von rm -rf / auf einem echten System.

Vergleichen Sie Hook-Verhalten im synchronen und asynchronen Modus: Starten Sie log_tool_result.py zuerst ohne async, messen Sie Verzögerung zwischen Instrumenten, dann aktivieren Sie async und vergleichen. Dies visualisiert den kritischen Unterschied.

Für visuellen Lerntyp: Zeichnen Sie das Schema aus dem Kurs auf Papier (Ereignis → matcher → Hook → Entscheidung → Fortsetzung/Anhalt/Kontext) und markieren Sie, welche Pfade Ihre konfigurierten Hooks durchlaufen.

Für auditiven Typ: Sprechen Sie laut den Zweck jedes Hooks in einem Satz aus, bevor Sie ihn zu settings.json hinzufügen. Wenn der Satz lang wird oder Konjunktionen „und" enthält, teilen Sie den Hook.

Lesen Sie regelmäßig den Abschnitt „Was nicht automatisiert werden sollte" neu – dies ist eine Selbstprüfungs-Checkliste vor jedem neuen Hook.

Üben Sie manuelles Zusammenführen von settings.json: Dies ist eine Fähigkeit, die bei Kursaktualisierungen und bei Arbeit mit fremden Repositories nützlich ist, wo Hooks eine versteckte Bedrohung sein können.

Diskutieren Sie mit Kollegen oder in der Lerngruppe: Welche Befehle in Ihrem Stack gelten als „gefährlich"? Die Liste unterscheidet sich für Python (pip install unbekanntes Paket), Node.js (npm audit fix --force), Go (go get mit Modul-Ersetzung), DevOps (kubectl delete, terraform destroy).

Zusätzliche Ressourcen: Kursbeispiel-Repository (sdd-qwen-code-ru/examples/hooks/): Quelldateien pre_tool_guard.py, log_tool_result.py, inject_sdd_context.py, settings-workflow.example.json und README.md – Basis aller praktischen Übungen

Offizielle Qwen Code-Dokumentation zu Hooks: Erweiterte Beschreibung von Ereignissen, Ausführertypen, JSON-Formaten (Versionsaktualität prüfen)

Jq – JSON-Kommandozeilenprozessor: https://jqlang.github.io/jq/ – Werkzeug für Analyse von JSONL-Protokollen im Terminal

Python json.tool: Integriertes Modul für JSON-Validierung und -Formatierung: python -m json.tool datei.json

Artikel „The Twelve-Factor App" (Abschnitt config): Prinzipien der Konfigurations- und Geheimnisspeicherung, anwendbar auf HTTP-Hook-Konfiguration und Umgebungsvariablen

OWASP Cheat Sheet: Injection Prevention: Empfehlungen zur Injektionsverhinderung, relevant für Hook-Eingabedatenverarbeitung und sicheren Befehlsaufbau

Vorherige Kursteile (qwen.md, specs/, validation.md): SDD-Kontext, notwendig für korrekte Abgrenzung von Hooks und Spezifikationen

Zusammenfassung: Qwen Code Hooks sind ein mächtiges, aber Disziplin erforderndes Werkzeug zur Automatisierung des SDD-Prozesses. Ihr Ziel ist es, die Abhängigkeit vom menschlichen Gedächtnis zu reduzieren, nicht Spezifikationen zu ersetzen. Schlüsselprinzipien: Mit 1-2 Hooks beginnen, jeder Hook löst eine Aufgabe und ist in einem Satz erklärbar, Schutz-Hooks erklären Blockierungsgrund, Protokollierung arbeitet asynchron, Prüfungen werden nach Gewicht aufgeteilt (leichte – automatisch, schwere – über validation.md). Hook-Sicherheit ist kritisch: Sie werden mit Benutzerrechten ausgeführt, erfordern Review, Timeouts, Geheimnis-Isolation und Vorsicht bei Arbeit mit fremden Repositories. Nach Beherrschung der Hooks ist der Student bereit für das Studium von Hook-Sicherheit und SQLite-Speicher in den nächsten Kursteilen.