Ratchet vérifie si un agent de codage suit réellement les règles qu'on lui donne

Une règle lue n'est pas une règle respectée

Le README part d'un constat simple : un jeu de règles minimal remis à un agent de codage, par exemple préférer la bibliothèque standard, ne pas ajouter de dépendances, garder un diff réduit, forme une boucle ouverte. Les instructions sont placées dans le prompt, le modèle les parcourt, et rien ne vient vérifier qu'elles ont été suivies. Quand le modèle dérive au fil d'une longue session, ce que le document présente comme un cas fréquent, personne ne s'en aperçoit avant une relecture humaine, donc après coup.

La réponse du projet tient dans un hook PostToolUse : chaque opération Edit, MultiEdit et Write déclenchée par l'agent est lue, mesurée, puis le résultat est renvoyé dans la session même, pendant que l'agent travaille encore. La vérification se produit au moment de l'écriture, pas dans une étape de revue séparée.

Le scénario flatpickr, seule démonstration du README

L'exemple détaillé est unique et présenté comme tel. Un utilisateur demande un sélecteur de date sur la page des paramètres ; l'agent installe le paquet flatpickr, écrit un composant enveloppant et ajoute une feuille de style. Le hook rapporte alors des comptes (lignes, fichiers, dépendances) et trois constats classés : une dépendance nouvelle inscrite dans package.json, une alternative déjà disponible dans la plateforme sous la forme d'un élément input de type date, et un composant dont le corps se contente de transmettre l'appel à Flatpickr.

Selon le README, l'agent annule sa modification et livre l'élément natif. Le document qualifie ce déroulé d'illustratif : aucun benchmark, aucun rapport indépendant, et aucune indication sur la fréquence à laquelle une session réelle se termine de cette manière.

Trois commandes pour brancher le hook

L'installation décrite tient en trois lignes : git clone https://github.com/0xwilliamortiz/ratchet.git, puis cd ratchet, puis npm install -g . Il suffit ensuite de se placer dans le dépôt à surveiller et de lancer ratchet. Cette première exécution enregistre les hooks, démarre la mesure, accepte comme référence tout le code déjà présent et ouvre une fenêtre d'état ; l'agent doit être redémarré pour que les hooks soient pris en compte.

Les prérequis annoncés sont Node 20 ou plus récent et git dans le PATH. Sans git, le jeu de règles et les détecteurs fonctionnent toujours, mais ni le mark, ni le ledger, ni l'audit. Les commandes ratchet init et ratchet baseline permettent de rejouer ces étapes une par une, et sous Windows un fichier hooks/ratchetui.exe livré avec le dépôt s'ouvre automatiquement pendant l'installation.

Quatre modes définis par des seuils chiffrés

Le README pose les modes sous forme de tableau de nombres plutôt que de qualificatifs. advise tolère 8 nouveaux fichiers, 3 nouvelles dépendances et 400 lignes nettes ajoutées, et se contente d'afficher les constats. guard, le mode par défaut, descend à 3 fichiers, 1 dépendance et 150 lignes, en y ajoutant des avertissements de budget. strict impose 1 fichier, 0 dépendance et 60 lignes, et bloque la modification en cas de dépassement. off ne fait rien tourner.

Le mode se change en cours de session par une commande du type /ratchet strict, se rend persistant avec /ratchet default advise, ou se fixe par la variable d'environnement RATCHET_MODE. Ce choix de seuils explicites rend le comportement prévisible ; le README ne justifie en revanche aucune de ces valeurs, qui restent des arbitrages non argumentés.

Huit détecteurs étiquetés, trois niveaux de confiance

Chaque opération passe par huit détecteurs nommés. dep repère un nom nouvellement apparu dans un manifeste comme package.json ou requirements.txt. exists signale un nouveau symbole dont le nom normalisé existe déjà ailleurs dans le dépôt, en excluant les noms de moins de cinq caractères et sans jamais atteindre le niveau certain. stdlib vise du code écrit à la main qui duplique la bibliothèque standard, native une dépendance ou un code qui réimplémente ce que la plateforme fait déjà, wrapper une fonction dont le corps ne fait que transmettre l'appel avec les mêmes arguments.

yagni repère une interface, une classe abstraite ou un protocole n'ayant qu'une seule implémentation ; validation cible l'expression régulière d'adresse email écrite maison, qualifiée systématiquement d'incorrecte par le README ; budget porte sur les totaux cumulés de fichiers, dépendances et lignes. Chaque constat reçoit un niveau, certain, likely ou heuristic, et le mode strict ne bloque que sur certain, les deux autres niveaux restant à l'appréciation de l'agent ou de l'utilisateur.

Assumer une dette par écrit plutôt que la combattre

Deux mécanismes laissent passer un constat, et le README les distingue par l'intention. Un commentaire d'une ligne, par exemple ratchet-ignore: profiled, the clone is the hot path, écarte un constat isolé avec une justification écrite. La commande ratchet baseline accepte au contraire d'un bloc tout ce qui existe déjà, si bien que seule la dette ajoutée ensuite déclenche des alertes.

Les constats sont identifiés par une empreinte fondée sur l'étiquette, le chemin et la forme du code, non sur le numéro de ligne ; une référence de base résiste donc, d'après le README, à un reformatage ou à un déplacement. Un fichier mark.json conserve une taille de dépôt acceptée, en lignes et en fichiers, avec sa raison. À chaque fin de session, une ligne (mode, lignes ajoutées et supprimées, dépendances, constats, taille du dépôt) rejoint ledger.jsonl, consultable par ratchet report, et relever le mark exige un appel à accept-mark.js accompagné d'une justification entre guillemets.

Ce que le projet concède lui-même

Le README ne vend pas ses détecteurs pour autre chose que ce qu'ils sont : des expressions régulières et du git grep, pas un vérificateur de types. Il en découle des faux positifs assumés, un mode par défaut qui signale sans bloquer, et un mode strict laissé optionnel. Le détecteur exists peut confondre un utilitaire réellement dupliqué avec deux fonctions sans lien qui portent le même nom. Les fichiers de test et les fixtures, aux chemins correspondant à tests/, __tests__/, spec/ ou *.test.*, sont ignorés par défaut, sauf si scanTests est réglé sur true.

Le document admet qu'aucun benchmark ne démontre un code meilleur ; seuls les comptes rapportés sont réels, et le blocage dépend du respect par l'agent hôte du champ decision de PostToolUse. La section Development décrit 115 tests, non rejoués ici. Les affirmations selon lesquelles ratchet doctor et ratchet log auraient attrapé deux bugs réels (un index de symboles masquant un doublon, un champ de nom de dépendance stockant une phrase entière) viennent du récit du projet lui-même. Les métadonnées du dépôt, au 29 août 2026, montrent 402 étoiles, 43 forks et aucun ticket ouvert.

Conclusion éditoriale

Sous licence MIT, Ratchet peut être copié, modifié et redistribué, y compris à des fins commerciales, à condition de garder la mention de copyright et le texte de la licence, sans garantie ni engagement de support. Avant d'y confier une session entière, exécuter ratchet doctor juste après l'installation, vérifier sur une édition factice que l'agent hôte honore bien le champ decision de PostToolUse, puis lire la première ligne de ledger.jsonl : c'est là que les détecteurs se jugent, pas dans l'exemple flatpickr du README.

Sources officielles

1. Project repository