ratchet: Ein PostToolUse-Hook, der misst, ob der Agent seine Regeln eingehalten hat

Der offene Regelkreis, den ratchet schließen will

Die Beschreibung des Projekts bringt es auf zwei Sätze: Der Agent liest die Regeln, und ratchet prüft, ob er sich daran gehalten hat. Genau diese Trennung ist der Ausgangspunkt.

Ein Regelwerk für einen Coding-Agenten ist meist kurz, etwa der Wunsch, die Standardbibliothek zu bevorzugen, keine neuen Abhängigkeiten einzuführen und den Diff klein zu halten. Solche Anweisungen landen im Prompt, das Modell liest sie, und danach passiert nichts mehr, was ihre Einhaltung messen würde. Die README beschreibt das als offenen Regelkreis und hält fest, dass niemand bemerkt, wenn ein Modell in einer langen Sitzung abdriftet, bis später jemand den Code durchsieht.

Als Alternative zu diesem nachgelagerten Schritt setzt ratchet auf eine Messstelle im laufenden Betrieb. Der Unterschied ist mehr als Timing: Ein Review am Ende bewertet ein Ergebnis, zu dem der Kontext der Sitzung fehlt, während ein Hook jede einzelne Operation sieht, während sie entsteht.

Der PostToolUse-Hook als Messstelle

Die im README beschriebene Antwort ist ein PostToolUse-Hook. Er liest jede Edit-, MultiEdit- und Write-Operation des Agenten, misst sie und meldet das Ergebnis in derselben Sitzung zurück, während der Agent weiterarbeitet.

Damit verschiebt sich die Rückmeldung an die Stelle, an der sie noch etwas bewirken kann. Ein Agent, der gerade eine Wrapper-Komponente geschrieben hat, kann sie im nächsten Schritt zurücknehmen. Ein Agent, der am nächsten Tag darauf angesprochen wird, hat den Kontext verloren.

Der Hook ist damit kein Linter im üblichen Sinn. Er läuft nicht auf Zuruf und nicht gegen den gesamten Baum, sondern anlassbezogen auf genau der Operation, die der Agent ausgeführt hat. Diese Auswahl ist auch eine Beschränkung: Was der Agent nicht über Edit, MultiEdit oder Write erzeugt, bleibt unbeobachtet.

Das Beispiel aus der README: flatpickr gegen input type date

Das README führt ein Szenario durch. Ein Nutzer bittet den Agenten, der Einstellungsseite einen Datumsauswähler hinzuzufügen. Der Agent installiert flatpickr, schreibt eine Wrapper-Komponente und ergänzt ein Stylesheet.

Der Hook meldet daraufhin eine Zeilenzahl, eine Dateizahl, eine Abhängigkeitszahl sowie drei eingestufte Befunde: eine neue, in package.json erfasste Abhängigkeit, eine native Alternative, die bereits als input-Element mit dem Typ date zur Verfügung steht, und eine Wrapper-Komponente, deren Rumpf den Aufruf nur an Flatpickr weiterreicht. Der README zufolge macht der Agent die Änderung daraufhin rückgängig und liefert das native input-Element.

Wie oft eine reale Sitzung tatsächlich so endet, bleibt offen. Das Dokument stellt es als anschauliches Beispiel dar und nicht als belegte Häufigkeit. Für die Beurteilung des Ansatzes ist trotzdem interessant, was der Hook hier leistet: Er erkennt nicht, dass flatpickr schlecht wäre, sondern dass eine plattformseitige Alternative existiert.

Vier Modi mit Zahlen statt Adjektiven

Die README definiert die Modi als Tabelle von Schwellenwerten, nicht als Umschreibungen. advise erlaubt bis zu 8 neue Dateien, 3 neue Abhängigkeiten und 400 netto hinzugefügte Zeilen und gibt danach nur Befunde aus. Der Standard guard senkt das auf 3 neue Dateien, 1 neue Abhängigkeit und 150 netto hinzugefügte Zeilen und ergänzt die Befunde um Budgetwarnungen.

Der Modus strict schränkt weiter ein, auf 1 neue Datei, 0 neue Abhängigkeiten und 60 netto hinzugefügte Zeilen, und blockiert die Änderung bei Überschreitung. off führt nichts aus.

Umschalten lässt sich mitten in der Sitzung mit einem Befehl wie /ratchet strict. Dauerhaft festlegen lässt sich ein Modus mit /ratchet default advise, alternativ über die Umgebungsvariable RATCHET_MODE. Dass die Modi über Zahlen definiert sind, ist der brauchbarste Teil der Dokumentation, weil man die Werte gegen die eigene Praxis abgleichen kann, statt eine abstrakte Strenge zu interpretieren.

Acht getaggte Detektoren und drei Sicherheitsstufen

Jede Operation durchläuft laut README acht Detektoren. dep erkennt einen Namen, der neu in einer Manifestdatei wie package.json oder requirements.txt auftaucht. exists erkennt ein neues Symbol, dessen normalisierter Name bereits an anderer Stelle im Repository vorkommt. stdlib findet handgeschriebenen Code, der Funktionen der Standardbibliothek nachbildet, und native findet Abhängigkeiten oder Code, die etwas nachbauen, was die Plattform schon bietet.

wrapper erkennt eine Funktion, deren Rumpf einen Aufruf mit denselben Argumenten nur an eine andere Funktion weiterreicht. yagni richtet sich gegen ein Interface, eine abstrakte Klasse oder ein Protokoll mit nur einer Implementierung. validation richtet sich gegen selbstgeschriebene Muster für Eingaben wie E-Mail-Adressen, die das README pauschal als fehlerhaft bezeichnet. budget führt die laufenden Summen über neue Dateien, neue Abhängigkeiten und netto hinzugefügte Zeilen.

Jeder Befund trägt eine Einstufung: certain, likely oder heuristic. Diese Abstufung trägt die ganze Konstruktion, denn der strict-Modus blockiert laut README ausschließlich bei certain. Befunde der beiden anderen Stufen werden getrennt gruppiert und der Bewertung durch Agent oder Nutzer überlassen.

git clone, npm install -g . und die Rolle von git im PATH

Die Einrichtung läuft laut README über drei Befehle. Zunächst wird das Repository geholt, dann wird global installiert:

git clone https://github.com/0xwilliamortiz/ratchet.git cd ratchet npm install -g .

Danach wechselt man in das zu überwachende Verzeichnis und ruft ratchet auf. Ein einziger Aufruf registriert die Hooks, startet die Messung, akzeptiert alles bereits vorhandene im Code als Baseline und öffnet ein Statusfenster. Der Agent muss neu gestartet werden, damit er die Hooks übernimmt.

Als Voraussetzungen nennt das README Node 20 oder neuer sowie git im PATH für die Messhälfte der Funktionen. Ohne git laufen Regelwerk und Detektoren weiter, nicht aber Mark, Ledger und Audit. Als eigenständige Befehle für die beiden Schritte existieren ratchet init und ratchet baseline. Auf Windows wird die mitgelieferte Datei hooks/ratchetui.exe bei der Einrichtung automatisch geöffnet.

ratchet-ignore, ratchet baseline, mark.json und ledger.jsonl

Zwei Mechanismen lassen einen Befund passieren, und das README unterscheidet sie nach Absicht. Ein einzeiliger Kommentar wie ratchet-ignore, gefolgt von einem Doppelpunkt und einer Begründung, lässt einen einzelnen Befund durch. Der Befehl ratchet baseline akzeptiert dagegen alles, was zu diesem Zeitpunkt im Repository vorhanden ist, auf einmal, sodass danach nur neu hinzukommende Schuld Befunde auslöst.

Befunde werden anhand von Tag, Pfad und Form gefingerprintet und nicht anhand der Zeilennummer. Dadurch bleibt eine Baseline laut README auch nach einer Neuformatierung oder einer Verschiebung des Codes innerhalb der Datei bestehen. Das ist der Unterschied zu einer reinen Zeilenliste, die bei jedem Reformat zerfällt.

Getrennt davon hält eine Datei mark.json eine akzeptierte Repository-Größe in Zeilen und Dateien fest, zusammen mit einem geschriebenen Grund. Am Ende jeder Sitzung wird eine Zeile mit Modus, hinzugefügten und entfernten Zeilen, Abhängigkeitszahl, Befunden und Repository-Größe an ledger.jsonl angehängt, lesbar über ratchet report. Das Anheben des Mark verlangt einen Aufruf von accept-mark.js mit einer in Anführungszeichen gesetzten Begründung.

Reguläre Ausdrücke statt Typprüfer, und was daraus folgt

Das README ist unumwunden zur Methode: Die Detektoren arbeiten mit regulären Ausdrücken und git grep, nicht mit einem Typprüfer. Daraus folgen Fehlalarme, und genau deshalb berichtet der Standardmodus nur, während strict optional bleibt.

Der Detektor exists zeigt die Grenze deutlich. Er vergleicht normalisierte Namen und kann damit sowohl einen wirklich duplizierten Helfer finden als auch zwei unabhängige Funktionen, die zufällig gleich heißen. Namen unter fünf Zeichen werden ausgeschlossen, und die Einstufung certain wird hier nie vergeben. Testdateien und Fixtures mit Pfaden nach Mustern wie tests/, __tests__/, spec/ oder *.test.* werden standardmäßig komplett übersprungen, sofern scanTests in der Konfiguration nicht auf true gesetzt wird.

Ob eine Überschreitung tatsächlich blockiert, hängt nach README davon ab, ob der Host-Agent das decision-Feld von PostToolUse respektiert. Ein Benchmark, der belegt, dass der Einsatz Code besser macht, wird ausdrücklich nicht beansprucht; real seien nur die berichteten Zahlen. Die im Abschnitt Development erwähnten 115 Tests werden dort nur beschrieben, ihre Abdeckung bleibt selbst zu prüfen. Das Repository steht unter der MIT-Lizenz, die Nutzung, Kopie, Veränderung und Weiterverbreitung einschließlich kommerzieller Zwecke erlaubt, solange Urheberrechtsvermerk und Lizenztext erhalten bleiben; zu Support oder Gewährleistung steht dort nichts.

Redaktionelles Fazit

ratchet passt für Entwickler, die einem Coding-Agenten ein kleines Regelwerk mitgeben und dessen Einhaltung noch in derselben Sitzung gemessen haben wollen, statt erst bei einem späteren Review. Weniger geeignet ist es für Projekte, die eine echte statische Analyse oder einen Typprüfer erwarten, und für Host-Agenten, die das decision-Feld von PostToolUse nicht respektieren, weil dann auch der strict-Modus nicht blockiert. Vor dem Einsatz gehören drei Dinge geprüft: ob Node 20 und git im PATH verfügbar sind, ob die Standardausnahme für Testdateien über scanTests zur eigenen Struktur passt, und was ratchet doctor auf dem eigenen Repository ausgibt, statt sich auf das Beispiel mit flatpickr aus der README zu verlassen. Die MIT-Lizenz erlaubt auch kommerzielle Nutzung und sagt nichts über Wartung oder Gewährleistung.

Offizielle Quellen

1. Project repository