GateGuard — Fakten-erzwingendes Pre-Action-Tor
Ein PreToolUse-Hook, der Claude zwingt, vor dem Editieren zu untersuchen. Statt Selbstbewertung ("Bist du sicher?") verlangt es konkrete Fakten. Der Akt der Untersuchung schafft ein Bewusstsein, das Selbstbewertung nie erreicht hat.
Wann aktivieren
- Bei Arbeiten an Codebasen, in denen Dateiänderungen mehrere Module betreffen
- Bei Projekten mit Datendateien, die bestimmte Schemata oder Datumsformate haben
- In Teams, in denen KI-generierter Code zu bestehenden Mustern passen muss
- In jedem Workflow, in dem Claude dazu neigt, zu raten statt zu untersuchen
Kernkonzept
LLM-Selbstbewertung funktioniert nicht. Frage "Hast du irgendwelche Richtlinien verletzt?" und die Antwort ist immer "Nein." Das ist experimentell belegt.
Aber die Frage "Liste jede Datei auf, die dieses Modul importiert" zwingt das LLM, Grep und Read auszuführen. Die Untersuchung selbst schafft Kontext, der die Ausgabe verändert.
Dreistufiges Tor:
1. VERWEIGERN — den ersten Edit/Write/Bash-Versuch blockieren
2. ERZWINGEN — dem Modell genau sagen, welche Fakten zu sammeln sind
3. ERLAUBEN — Wiederholung erlauben, nachdem Fakten präsentiert wurden
Kein Wettbewerber macht alle drei. Die meisten hören beim Verweigern auf.
Belege
Zwei unabhängige A/B-Tests, identische Agenten, gleiche Aufgabe:
| Aufgabe | Mit Tor | Ohne Tor | Abstand |
|---|---|---|---|
| Analysemodul | 8,0/10 | 6,5/10 | +1,5 |
| Webhook-Validator | 10,0/10 | 7,0/10 | +3,0 |
| Durchschnitt | 9,0 | 6,75 | +2,25 |
Beide Agenten produzieren Code, der läuft und Tests besteht. Der Unterschied liegt in der Designtiefe.
Tortypen
Edit-/MultiEdit-Tor (erster Edit pro Datei)
MultiEdit wird identisch behandelt – jede Datei im Batch wird einzeln abgesichert.
Vor dem Editieren von {dateipfad}, präsentiere diese Fakten:
1. Liste ALLE Dateien auf, die diese Datei importieren/benötigen (durchsuche den Baum – Glob/Grep oder find/grep via Bash)
2. Liste die öffentlichen Funktionen/Klassen auf, die von dieser Änderung betroffen sind
3. Wenn diese Datei Datendateien liest/schreibt, zeige Feldnamen, Struktur
und Datumsformat (verwende geschwärzte oder synthetische Werte, keine rohen Produktionsdaten)
4. Zitiere die aktuelle Anweisung des Benutzers wörtlich
Write-Tor (erste Erstellung einer neuen Datei)
Vor dem Erstellen von {dateipfad}, präsentiere diese Fakten:
1. Nenne die Datei(en) und Zeile(n), die diese neue Datei aufrufen werden
2. Bestätige, dass keine vorhandene Datei denselben Zweck erfüllt (durchsuche den Baum – Glob/Grep oder find/grep via Bash)
3. Wenn diese Datei Datendateien liest/schreibt, zeige Feldnamen, Struktur
und Datumsformat (verwende geschwärzte oder synthetische Werte, keine rohen Produktionsdaten)
4. Zitiere die aktuelle Anweisung des Benutzers wörtlich
Destruktives Bash-Tor (jeder destruktive Befehl)
Wird ausgelöst bei: rm -rf, git reset --hard, git push --force, drop table, usw.
1. Liste alle Dateien/Daten auf, die dieser Befehl ändern oder löschen wird
2. Schreibe eine einzeilige Rollback-Prozedur
3. Zitiere die aktuelle Anweisung des Benutzers wörtlich
Routinemäßiges Bash-Tor (einmal pro Sitzung)
1. Die aktuelle Benutzeranfrage in einem Satz
2. Was dieser spezifische Befehl überprüft oder erzeugt
Parallele Batches und teilweise Anwendung
Das First-Touch-Tor wertet jeden Tool-Aufruf unabhängig aus. Wenn mehrere Bearbeitungen einer Datei, die noch nicht berührt wurde, in einem parallelen Batch gesendet werden, wird der erste Aufruf verweigert und die Verweigerung markiert die Datei als geprüft, sodass die Geschwisterbearbeitungen in diesem Batch angewendet werden. Nichts wird zurückgesetzt: Die Datei kann die Geschwisterbearbeitungen enthalten, ohne die verweigerte.
Die Verweigerungsnachricht nennt die Datei und warnt, dass Batch-Geschwister bereits angewendet worden sein könnten. Behandle es wörtlich:
- Sende abhängige Bearbeitungen einer noch nicht berührten Datei sequenziell, nicht in einem parallelen Batch. Eine Definition und ihre erste Verwendung oder ein Import und seine Aufrufstelle dürfen nicht im selben Batch reisen.
- Präsentiere nach einer First-Touch-Verweigerung die Fakten, wiederhole die verweigerte Bearbeitung und lies die Datei erneut, bevor du auf etwas anderem aus dem Batch aufbaust.
Eine batchweite Sperre ist nicht möglich: Hooks sehen Tool-Aufrufe einzeln, daher kann das Tor nicht wissen, welche Aufrufe zusammen angekommen sind.
Schnellstart
Option A: Den ECC-Hook verwenden (keine Installation)
Der Hook unter scripts/hooks/gateguard-fact-force.js ist in diesem Plugin enthalten. Aktiviere ihn über hooks.json.
Wenn GateGuard Setup- oder Reparaturarbeiten blockiert, starte die Sitzung mit
ECC_GATEGUARD=off. Für Hook-Ebene-Steuerung verwende weiterhin
ECC_DISABLED_HOOKS mit der GateGuard-Hook-ID.
In langen Sitzungen geben nur die ersten GATEGUARD_FACT_FORCE_FULL_DENIALS
Fakten-erzwingende Verweigerungen (Standard 3) den vollständigen Vier-Fakten-Block aus; spätere
Verweigerungen werden auf eine einzelne Zeile mit der Verweigerungsnummer reduziert, sodass
sich fast identische Blöcke nicht im Kontextfenster ansammeln und Modellwiederholungsschleifen verstärken können (#2142). Das erneute Versuchen derselben Datei oder
desselben Befehls nach Präsentation der Fakten löst das Tor nie erneut aus.
Abgestufte Steuerung
ECC_GATEGUARD=off (oder GATEGUARD_DISABLED=1) schaltet das Tor vollständig aus.
Die Variablen in dieser Tabelle tun dies nicht – jede schränkt ein Verhalten ein, während
die tragenden destruktiven Bash-Prüfungen weiterlaufen:
| Variable | Standard | Wirkung |
|---|---|---|
GATEGUARD_BASH_ROUTINE_DISABLED | nicht gesetzt (Tor an) | Deaktiviert nur das routine-Bash-Tor. Das destruktive Bash-Tor (rm -rf, git reset --hard, drop table, dd if=, …) bleibt unbeeinflusst. |
GATEGUARD_EXEMPT_GLOBS | nicht gesetzt (keine Ausnahmen) | Kommaseparierte Glob-Muster; ein passendes Edit/Write/MultiEdit-Ziel überspringt die First-Touch-Fakten-erzwingung. Gedacht für Bäume mit niedrigem Importwert (Tests, generierte Artefakte, Scratch-Verzeichnisse), bei denen "wer importiert dies / welches Schema" kein Signal liefert. |
GATEGUARD_FACT_FORCE_FULL_DENIALS | 3 | Wie viele Verweigerungen den vollständigen Vier-Fakten-Block ausgeben, bevor spätere auf eine einzelne Zeile reduziert werden. 0 reduziert ab der allerersten Verweigerung. |
GATEGUARD_BASH_EXTRA_DESTRUCTIVE | nicht gesetzt | Zusätzliche destruktive Befehlsmuster als Regex-Quelle, die zum integrierten Satz hinzugefügt werden. Ein fehlerhafter Regex wird als nicht gesetzt behandelt (integrierte Muster gelten weiterhin) und einmalig auf stderr protokolliert. |
GATEGUARD_STATE_DIR | ~/.gateguard | Wo der sitzungsbezogene Torzustand gespeichert wird. Wenn der Zustand nicht persistent gespeichert werden kann, erlaubt das Tor den Vorgang, anstatt eine Schleife zu bilden, und nennt diese Variable in der Warnung. |
GATEGUARD_BASH_ROUTINE_DISABLED akzeptiert 1, true, on, enabled,
enable oder yes (Groß-/Kleinschreibung und Leerzeichen werden ignoriert); jeder andere Wert
lässt das Tor an.
Das Tor vollständig ausschalten
| Variable | Wirkung |
|---|---|
ECC_GATEGUARD=off | Deaktiviert GateGuard für die Sitzung. Akzeptiert 0, false, off, disabled oder disable. |
GATEGUARD_DISABLED=1 | Gleicher Effekt. Erkennt nur 1 – die obigen Schreibweisen gelten hier nicht. |
Für Hook-Ebene-Steuerung verwende weiterhin ECC_DISABLED_HOOKS mit der GateGuard-Hook-ID.
Glob-Semantik für GATEGUARD_EXEMPT_GLOBS
Muster passen auf den gesamten projektrelevanten Zielpfad. Das Projektstammverzeichnis ist
CLAUDE_PROJECT_DIR, fallback auf das Hook-Payload-cwd, dann das Hook-Prozess-Arbeitsverzeichnis. Relative Glob-Muster befreien niemals Ziele außerhalb dieses
Stammverzeichnisses. Explizite absolute Glob-Muster passen auf den gesamten absoluten Zielpfad und können
absichtlich Pfade außerhalb des Projekts befreien.
Sowohl Muster als auch Pfade verwenden /-Trennzeichen und Kleinschreibung bei der Übereinstimmung. * passt
innerhalb eines Segments, ** über Segmente hinweg und ? auf ein Nicht-Trennzeichen-Zeichen.
**/ umfasst null Verzeichnisse, daher passt **/tests/** auch auf tests/foo.js.
Fehlerhafte Muster werden verworfen, ohne eine Ausnahme zu gewähren.
Seit 2.2.1 deckt services/** nur den Services-Baum des Projektstammverzeichnisses ab und
*.md nur dessen Markdown-Dateien im Stammverzeichnis. Verwende **/*.md für alle Markdown-Dateien
innerhalb des Projekts. Vorhandene unverankerte Ausnahmen müssen möglicherweise angepasst werden:
{
"env": {
"GATEGUARD_BASH_ROUTINE_DISABLED": "1",
"GATEGUARD_EXEMPT_GLOBS": "**/tests/**,tests/**,**/*.test.*,**/docs/**,**/dist/**"
}
}
Option B: Vollständiges Paket mit Konfiguration
pip install gateguard-ai
gateguard init
Dies fügt .gateguard.yml für projektspezifische Konfiguration hinzu (benutzerdefinierte Nachrichten, Ignorierpfade, Tor-Umschalter).
Anti-Patterns
- Verwende stattdessen keine Selbstbewertung. "Bist du sicher?" bekommt immer "Ja." Das ist experimentell belegt.
- Überspringe die Datenschema-Prüfung nicht. Beide A/B-Test-Agenten nahmen ISO-8601-Daten an, als echte Daten
%Y/%m/%d %H:%Mverwendeten. Die Überprüfung der Datenstruktur (mit geschwärzten Werten) verhindert diese gesamte Klasse von Fehlern. - Sperre nicht jeden einzelnen Bash-Befehl. Routinemäßige Bash-Sperren einmal pro Sitzung. Destruktive Bash-Sperren jedes Mal. Diese Balance vermeidet Verlangsamung und fängt gleichzeitig echte Risiken ab.
Best Practices
- Lass das Tor natürlich auslösen. Versuche nicht, die Tor-Fragen vorab zu beantworten – die Untersuchung selbst ist es, die die Qualität verbessert.
- Passe die Tor-Nachrichten an deine Domäne an. Wenn dein Projekt spezifische Konventionen hat, füge sie den Tor-Aufforderungen hinzu.
- Verwende
.gateguard.yml, um Pfade wie.venv/,node_modules/,.git/zu ignorieren.
Verwandte Skills
safety-guard— Laufzeit-Sicherheitsprüfungen (komplementär, nicht überlappend)code-reviewer— Post-Edit-Review (GateGuard ist Pre-Edit-Untersuchung)