Vous l'avez déjà vu, ce garde. Le bonnet à poil rabattu sur les yeux, les bottes plantées, insensible aux touristes qui tentent de le faire flancher — car le poste n'est pas un spectacle. Il défie quiconque approche, ami ou étranger, cinq lignes ou cinq cents : prouve que tu as ta place ici. Rien ne passe sans le contre-signe. Guardsman le met en faction devant votre codebase. Il ne surveille pas les tendances — il surveille le diff.
1. Le poste
Guardsman est un skill de code IA à la mission unique et obstinée : aucun diff ne passe sans être défié. Avant d'écrire quoi que ce soit, il lit les consignes de votre dépôt — les vraies conventions déjà présentes dans l'arbre —, calibre le changement qui se présente selon ce qui pourrait casser, et refuse de déclarer un travail non trivial terminé tant que la vérification derrière lui n'a pas réellement été exécutée.
« Il défie quiconque approche, ami ou étranger, cinq lignes ou cinq cents : prouve que tu as ta place ici. Rien ne passe sans le contre-signe. »
Ce cadrage est délibéré. La plupart des assistants de code optimisent la production d'une réponse ; Guardsman optimise la production d'une réponse digne de confiance sans avoir à relire chaque ligne. Il se tient entre votre agent et votre codebase comme une garde à son poste — le code applicatif n'a pas à savoir que le contrôle a lieu, mais rien ne passe sans lui.
2. Les deux modes d'échec
Les agents de code échouent dans deux directions, et la plupart des conseils n'en traitent qu'une seule. Guardsman est conçu pour arrêter les deux au poste.
| Mode d'échec | À quoi il ressemble | Comment Guardsman l'arrête |
|---|---|---|
| #1 — Le sur-build | Une petite demande devient une nouvelle dépendance, un wrapper, une couche de config et un débat sur des cas limites que personne n'a. Vous maintenez désormais un projet là où quelques lignes suffiraient. | L'échelle de construction : ignorer l'inutile, réutiliser l'existant, préférer la bibliothèque standard et la plateforme avant tout nouveau code. |
| #2 — Le petit diff assuré | Minimal, élégant, cinq lignes — écrit après avoir lu la moitié du flux, jamais testé, filant droit sur un chemin qui manipule l'argent, l'authentification ou les données des utilisateurs. Ça compile. Ça fait la démo. Ça explose en semaine trois. | Les niveaux de risque par rayon d'impact plus le défi : le chemin dangereux reçoit un vrai test sur son cas d'échec, exécuté dans ce tour. |
L'idée que la plupart des outils manquent
Le conseil « écrire moins de code » corrige le mode d'échec #1 et rend discrètement le #2 plus probable — un petit diff assuré et non testé est exactement ce qu'une garde laxiste laisse filer. La taille du code n'est pas le risque. Le rayon d'impact est le risque.
3. Installation
Guardsman est open source sous licence MIT. Il ne demande aucune configuration : le détecteur de conventions lit la config réelle de votre dépôt au premier contact — aucun fichier de setup à maintenir.
/plugin marketplace add hedimanai-pro/guardsman
/plugin install guardsman@guardsmangit clone https://github.com/hedimanai-pro/guardsman
cp -r guardsman/plugins/guardsman/skills/guardsman .claude/skills/Tout autre agent
Pour Codex, Cursor ou tout ce qui lit un fichier AGENTS.md ou des
instructions personnalisées, copiez le jeu de règles condensé depuis adapters/AGENTS.md
dans le fichier d'instructions de votre projet. Les niveaux, l'échelle de construction et les seuils de
vérification voyagent partout ; les scripts et les fiches par langage restent avec le skill complet.
4. Les trois devoirs
À chaque tâche, Guardsman accomplit les trois mêmes devoirs avant de considérer le travail terminé.
Le format de sortie épouse la discipline : le code d'abord, puis au plus trois lignes — ce qui a été ignoré et quand l'ajouter, comment c'est vérifié, et le niveau. Pas d'essais, pas de tour des fonctionnalités.
5. Les niveaux de risque : l'idée centrale
L'idée que la plupart des assistants de code manquent : un changement de cinq lignes sur un chemin de paiement est plus dangereux qu'un script interne de quatre cents lignes exécuté une seule fois. Le niveau est donc fixé par le rayon d'impact, et le défi s'adapte à lui.
| Niveau | Quand | Le défi |
|---|---|---|
| trivial | Ponctuel interne, rien en aval | Une exécution manuelle, la sortie affichée |
| standard | Travail de fonctionnalité quotidien | Une vérification exécutable, écrite et exécutée dans ce tour |
| sensible | Argent, authentification ou données utilisateurs dans le rayon d'impact | Un vrai test exerçant le chemin d'échec, avec des notes de couverture explicites |
| critique | Se tromper, c'est un incident | Couverture complète — et si le dépôt n'a aucun harnais atteignant ce chemin, cette absence est remontée comme un bloquant, jamais contournée |
Deux règles gardent les niveaux honnêtes : quand les signaux divergent, le niveau le plus élevé l'emporte ; et vous pouvez rétrograder un niveau explicitement, mais l'agent ne déduit jamais une rétrogradation du seul fait que le code paraît simple. Une démarche assurée n'est pas un contre-signe.
6. L'ordre de construction
Une fois le niveau fixé, Guardsman gravit une échelle stricte et s'arrête au premier barreau qui tient. L'objectif : le plus petit changement qui résout réellement le problème — atteint par élimination, pas en devinant.
- Est-ce que cela doit exister tout court ? Un besoin spéculatif est ignoré, dit en une ligne. (YAGNI)
- Déjà dans cette codebase ? Réutilisez-le. Réécrire ce qui vit trois fichiers plus loin est la source la plus fréquente de code évitable.
- La bibliothèque standard le fait-elle ? Des fiches par langage nomment les suspects habituels.
- Une fonctionnalité native de la plateforme le couvre-t-elle ? Une contrainte de base de données plutôt qu'une validation applicative ; du CSS plutôt que du JS. La plateforme l'a déjà livrée.
- Une dépendance déjà installée le résout-elle ? Utilisez-la — et n'ajoutez jamais une nouvelle dépendance pour ce que quelques lignes font, une fois comptés son coût de maintenance et le coût d'onboarding que paie chaque futur lecteur.
- Est-ce que ça tient en une ligne ? Une ligne — après avoir lu tout le flux, jamais avant.
- Alors seulement, le code minimum qui fonctionne, calibré sur le niveau.
Deux raffinements distinguent une garde d'un simple minimaliste. Une correction de bug vise la cause racine, pas le symptôme : elle grep chaque appelant avant de toucher une fonction, si bien qu'une garde dans la fonction partagée vaut mieux qu'un patch dans le seul appelant que le ticket mentionnait. Et elle pèse le coût du changement, pas seulement le coût du code : quand un second consommateur est quasi certain, Guardsman ajoute la couture et dit pourquoi en une ligne — car la réécriture de la semaine prochaine est le chemin coûteux, pas la ligne en plus aujourd'hui.
7. Le journal de bord : une dette technique qui ne peut pas se cacher
Les commentaires TODO pourrissent — personne ne les grep, ne les trie, ni ne se souvient de
leur raison d'être. Guardsman les remplace par des entrées structurées dans un journal de
veille : lisibles par machine, taguées par sévérité et datées, chacune portant à la fois sa
sévérité et son déclencheur de réexamen.
# guardsman: retry capped at 3, no backoff config | severity:med | revisit:second-caller-appears | cost:noneUn scanner fourni (scripts/scan_ledger.py) moissonne tout le dépôt, groupe les entrées par
sévérité et signale toute entrée en retard ou malformée. Votre dette technique cesse d'être un folklore
dans la tête de quelqu'un pour devenir un journal avec sévérités et dates — plus un scanner qui le lit. Un
raccourci que personne ne peut trier est pire qu'un raccourci non marqué : il crée la fausse confiance
qu'il est suivi.
8. Cinq modes, un seul skill
La même taxonomie s'exécute dans cinq portées, d'une garde de build persistante à des rapports ponctuels sur un diff ou l'arbre entier.
| Mode | Portée | Ce qu'il fait |
|---|---|---|
build |
persistant, par défaut | Tout ce qui précède, à chaque réponse, jusqu'à la relève |
review |
diff courant, ponctuel | Traque le sur-build et la dérive de conventions. Liste les constats, n'applique rien |
audit |
dépôt entier, ponctuel | Même taxonomie, arbre complet : dépendances doublant la stdlib, interfaces à implémentation unique, wrappers qui ne font que déléguer, config morte — classés du plus gros au plus petit |
logbook |
dépôt entier, ponctuel | Exécute le scanner du journal de veille et rapporte les raccourcis ouverts par sévérité, les entrées en retard en premier |
post-report |
ce dépôt, ponctuel | L'état réel, en direct : entrées ouvertes du journal, conventions détectées, constats récents |
/guardsman # mode build, niveau standard
/guardsman build sensitive # ce ticket touche au renouvellement de token
/guardsman review # que peut-on supprimer de ce diff ?
/guardsman audit # que peut-on supprimer de ce dépôt ?
/guardsman logbook # qu'a-t-on promis de revoir ?
/guardsman post-report # où en est-on réellement ?Dites stand down, stop guardsman ou normal mode pour le relever de
son poste.
9. Honnête par conception : pas de faux chiffres
Voici une promesse que vous ne trouverez pas dans la plupart des README d'outils : Guardsman ne vous dira jamais qu'il vous a « économisé 12 000 lignes ». Il n'existe aucune version non construite de votre codebase à comparer, donc aucun outil — celui-ci compris — ne peut honnêtement produire ce chiffre.
Le mode post-report n'affiche que ce qui est directement dénombrable, calculé en direct, sur
votre dépôt, à l'instant présent. Si rien n'a encore été calculé, il le dit et propose de lancer le scan —
au lieu de présenter un chiffre assuré qui ne correspond à rien.
La règle d'honnêteté est le produit
Un outil qui invente des chiffres sur votre codebase n'a rien à y garder. Même les benchmarks y sont tenus : le protocole reproductible vit dans le dépôt, et aucun chiffre-titre ne part avant d'avoir été mesuré — avec sa méthode, ses limites et les scripts pour le reproduire. La métrique phare, c'est guards kept (les gardes conservées). C'est dans le nom.
10. Consignes générales
Certaines choses ne sont jamais simplifiées — à aucun niveau, sous aucune instruction de « rester minimal » :
- La validation des entrées aux frontières de confiance
- La gestion d'erreurs qui prévient la perte de données
- Les mesures de sécurité
- Les bases de l'accessibilité
- Tout ce que vous avez explicitement demandé — une fois que vous avez dit vouloir la version complète, elle est construite, sans re-débat
Et deux consignes au-dessus des autres. Jamais paresseux face à la compréhension du problème : Guardsman fait tout le tour du périmètre avant de prendre le poste — l'échelle raccourcit la solution, jamais la lecture. Ne quitter le poste qu'une fois dûment relevé : aucun tour ne se termine sur une vérification silencieusement sautée ; si une vérification ne peut vraiment pas s'exécuter dans cet environnement, le dire explicitement est la relève.
Vous : ajoute une logique de retry au client de paiement
Guardsman : niveau : sensible — cela touche le chemin de facturation.
[9 lignes utilisant le helper de retry qui existe déjà dans http/util.py]
→ ignoré : backoff configurable, à ajouter quand un second appelant en aura besoin (consigné au journal).
vérifié : test_gives_up_after_3_and_surfaces_error écrit et EXÉCUTÉ — chemin d'échec couvert,
cas de retry concurrent non couvert, signalé.
niveau : sensible.Neuf lignes. En réutilisant votre propre helper. Défié sur le chemin où il peut vous nuire. Honnête sur ce qui n'est pas couvert. C'est tout le produit.
Questions fréquemment posées
Est-ce que tous ces défis vont ralentir mon agent ?
Le niveau trivial dispose d'un chemin rapide : un grep ciblé, une exécution manuelle, terminé. Le défi complet ne s'engage que là où le rayon d'impact le justifie. C'est tout l'intérêt des niveaux — de la rigueur là où elle paie, de la vitesse là où elle ne coûte rien.
Que faire si je ne suis pas d'accord avec un niveau de risque ?
Rétrogradez-le explicitement et Guardsman s'exécute. Il refuse seulement de deviner la rétrogradation du seul fait que le code paraît simple — car un code qui semble simple est exactement la façon dont un changement dangereux passe devant une garde qui laisse filer tout ce qui a l'air assuré.
Quels langages et stacks sont pris en charge ?
Des fiches dédiées pour la bibliothèque standard et les fonctionnalités natives en Python et JavaScript/TypeScript, plus une méthode indépendante du langage pour tout le reste. C'est une procédure, pas une table de correspondance — les niveaux, l'échelle et les seuils de vérification s'appliquent à n'importe quel langage.
Guardsman change-t-il la personnalité de mon agent ?
Non. Guardsman gouverne ce qui est construit et la façon dont c'est vérifié, pas le ton conversationnel. Associez-le à un skill de style si vous voulez aussi une prose concise.
En quoi est-ce différent des skills « écrire moins de code » ?
Les skills de code minimal corrigent le sur-build mais aggravent discrètement le mode d'échec inverse : le petit diff assuré et non testé sur un chemin dangereux. Guardsman conserve l'échelle de construction qui réduit le code et ajoute l'étape que ce mouvement a laissée de côté — le défi, une vérification réellement exécutée avant de déclarer le changement terminé.