En une phrase
Guardsman est un skill de codage IA avec une seule obsession : aucun diff ne passe sans être défié. Il lit les conventions réelles de votre dépôt, calibre le changement qu'il a devant lui sur ce qui pourrait casser, et refuse de déclarer terminé un travail non trivial tant que la vérification qui l'accompagne n'a pas réellement tourné.
0. Démarrage rapide
Dans Claude Code, deux commandes. Pour les autres agents — Codex, Cursor, tout
ce qui lit un AGENTS.md — voir Installation.
> /plugin marketplace add hedimanai-pro/guardsman
> /plugin install guardsman@guardsman
Quand l'utiliser
Votre agent travaille sur une vraie base de code et, sinon, vous reliriez chaque ligne : nouvelles fonctionnalités, refactorisations, tout ce qui touche à l'argent, à l'authentification ou aux données des utilisateurs. Sur un script jetable, le palier trivial le laisse hors de votre chemin.
Ça marche si
Chaque changement non trivial se termine par une vérification exécutée dans le tour même, sortie affichée ; le code suit les conventions déjà présentes dans votre dépôt ; et la réponse se conclut en trois lignes au plus : ce qui a été écarté, comment la vérification a été faite, le palier.
1. Le poste
Vous l'avez déjà vu, ce garde. Bonnet à poil rabattu sur les yeux, bottes plantées, insensible aux touristes qui tentent de le faire ciller — parce que monter la garde n'est pas un spectacle. Il défie tout ce qui approche, ami ou inconnu, cinq lignes ou cinq cents : prouvez que vous avez votre place ici. Rien ne passe sans le mot de passe. Guardsman le poste devant votre base de code. Il ne surveille pas les tendances — il surveille le diff.
Guardsman est un skill de codage IA avec une seule obsession, tenace : aucun diff ne passe sans être défié. Avant d'écrire quoi que ce soit, il lit les consignes permanentes de votre dépôt — les conventions réelles, déjà présentes dans l'arborescence — calibre le changement qu'il a devant lui sur ce qui pourrait casser, et refuse de déclarer terminé un travail non trivial tant que la vérification qui l'accompagne n'a pas réellement tourné.
La plupart des assistants de code cherchent à produire une réponse. Guardsman cherche à produire une réponse à laquelle vous pouvez vous fier sans relire chaque ligne. Il se tient entre votre agent et votre base de code comme un garde se tient à son poste : le code applicatif n'a jamais à savoir que l'examen a lieu, mais rien ne passe sans lui.
2. Les deux modes de défaillance
Les agents de code échouent dans deux directions, et la plupart des conseils n'en traitent qu'une. Guardsman est conçu pour arrêter les deux au poste.
Mode de défaillance → à quoi il ressemble → comment Guardsman l'arrête
- N° 1 — la sur-construction. Une petite demande devient une nouvelle dépendance, un wrapper, une couche de configuration et un débat sur des cas limites que personne ne rencontre. Vous maintenez désormais un projet là où quelques lignes auraient suffi. Arrêtée par l'échelle de l'ordre de construction : écarter l'inutile, réutiliser l'existant, passer par la bibliothèque standard et la plateforme avant d'écrire du code neuf.
- N° 2 — le petit diff sûr de lui. Minimal, élégant, cinq lignes — écrit après avoir lu la moitié du flux, jamais testé, lâché sur un chemin qui touche à l'argent, à l'authentification ou aux données des utilisateurs. Ça compile. Ça démontre bien. Ça explose la troisième semaine. Arrêté par les paliers de risque fixés sur le rayon d'impact, et par le défi : le chemin dangereux reçoit un vrai test sur son cas d'échec, exécuté dans le tour même.
Le conseil « écrivez moins de code » corrige le mode de défaillance n° 1 et rend discrètement le n° 2 plus probable — un diff minuscule, sûr de lui et non testé est exactement ce qu'un garde laxiste laisse passer. La taille du code n'est pas le risque. Le rayon d'impact, si.
3. Installation
Guardsman est open source sous licence MIT. Il n'exige aucun fichier de configuration à maintenir — le détecteur de conventions lit la configuration réelle de votre dépôt au premier contact.
# Claude Code — plugin marketplace /plugin marketplace add hedimanai-pro/guardsman /plugin install guardsman@guardsman # Claude Code — project-level (manual) git clone https://github.com/hedimanai-pro/guardsman cp -r guardsman/plugins/guardsman/skills/guardsman .claude/skills/ # Any AGENTS.md-compatible agent — Codex, Cursor # copy the condensed ruleset into your instruction file: git clone https://github.com/hedimanai-pro/guardsman cp guardsman/adapters/AGENTS.md .
Pour Codex, Cursor ou tout outil qui lit un fichier AGENTS.md ou un fichier d'instructions personnalisé, le jeu de règles condensé de adapters/AGENTS.md voyage partout ; les scripts et les aide-mémoire par langage restent avec le skill complet.
4. Les trois consignes
À chaque tâche, Guardsman exécute les trois mêmes consignes avant de considérer le travail terminé.
Il lit les consignes permanentes
Avant d'écrire quoi que ce soit, un script déterministe détecte les conventions réelles de votre dépôt — langage, formateur, linter, la vraie commande de test. Puis il cherche comment votre base de code résout déjà le problème le plus proche. Vos motifs l'emportent. Toujours.
Il fixe le niveau de menace
Chaque changement reçoit un palier de risque avant qu'une seule ligne ne soit écrite. C'est le rayon d'impact qui fixe le palier — pas la taille ni l'élégance apparente du code. L'argent, l'authentification et les données des utilisateurs le relèvent.
Il lance le défi
Une logique non triviale n'est pas « terminée » quand le code est écrit. Elle l'est quand la vérification qui l'accompagne a réellement tourné, dans ce tour, avec sa sortie affichée — et non laissée en devoir à votre futur vous. Alors seulement il s'écarte.
Le format de sortie épouse la discipline : le code d'abord, puis trois lignes au maximum — ce qui a été écarté et quand l'ajouter, comment la vérification a été faite, et le palier. Pas de dissertation, pas de visite guidée des fonctionnalités.
5. Les paliers de risque
Ce que la plupart des assistants de code ne voient pas : 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 palier est donc fixé par le rayon d'impact, et le défi grandit avec lui. Deux règles gardent les paliers honnêtes : quand les signaux divergent, c'est le palier le plus élevé qui l'emporte ; et vous pouvez déclasser un palier explicitement, mais l'agent ne déduit jamais un déclassement du simple fait que le code a l'air simple. Une démarche assurée ne vaut pas mot de passe.
Trivial
Ponctuel et interne, sans conséquence en aval. Une exécution manuelle, sortie affichée.
Standard
Travail de fonctionnalité courant. Une vérification exécutable, écrite et lancée dans ce tour.
Sensible
De l'argent, de l'authentification ou des données d'utilisateurs dans le rayon d'impact. Un vrai test qui exerce le chemin d'échec, avec des notes de couverture explicites.
Critique
Se tromper, c'est déclencher un incident. Couverture complète — et l'absence de harnais de test est remontée comme un bloquant, jamais contournée.
6. L'ordre de construction
Une fois le palier fixé, Guardsman gravit une échelle stricte et s'arrête au premier barreau qui tient. L'objectif est le plus petit changement qui résout réellement le problème — atteint par élimination, pas au jugé.
Sept barreaux, dans l'ordre
- Cela a-t-il seulement besoin d'exister ? Un besoin spéculatif est écarté, et signalé en une ligne. (YAGNI)
- Déjà présent dans cette base de code ? Réutilisez-le — réécrire ce qui vit trois fichiers plus loin est de loin la première source de code évitable.
- La bibliothèque standard le fait-elle déjà ? Des aide-mémoire 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é.
- Une dépendance déjà installée le résout-elle ? Utilisez-la — n'en ajoutez jamais une nouvelle pour ce que quelques lignes suffisent à faire, une fois comptés sa traîne de maintenance et le coût d'apprentissage que paiera chaque futur lecteur.
- Est-ce que cela tient en une ligne ? Une ligne — après avoir lu le flux complet, jamais avant.
- Alors seulement, le minimum de code qui fonctionne, dimensionné au palier.
Deux nuances séparent un garde d'un simple minimaliste. Une correction de bug vise la cause racine, pas le symptôme : elle recherche tous les appelants avant de toucher à une fonction, si bien qu'une garde placée dans la fonction partagée vaut mieux qu'un correctif dans l'unique appelant que le ticket citait. Et elle pèse le coût du changement, pas seulement le coût du code — quand un deuxième consommateur est quasi certain, Guardsman pose la jointure et dit pourquoi en une ligne, parce que la réécriture de la semaine prochaine est le chemin coûteux, pas la ligne supplémentaire d'aujourd'hui.
7. Le carnet de bord : la dette qui ne peut plus se cacher
Les commentaires TODO pourrissent — personne ne les recherche, ne les trie, ni ne se souvient de leur raison d'être. Guardsman les remplace par des entrées structurées dans un carnet de garde : lisibles par une machine, étiquetées par gravité et datées, chacune portant à la fois sa gravité et son déclencheur de réexamen.
# guardsman: retry capped at 3, no backoff config # severity:med | revisit:second-caller-appears | cost:none
Un scanner fourni (scripts/scan_ledger.py) ratisse tout le dépôt, regroupe les entrées par gravité et signale tout ce qui est en retard ou mal formé. Votre dette technique cesse d'être un folklore logé dans la tête de quelqu'un pour devenir un carnet avec des gravités et des dates — plus un scanner qui le lit. Un raccourci que personne ne peut trier est pire qu'un raccourci non signalé : il crée la fausse confiance d'un suivi.
8. Cinq modes, un seul skill
La même taxonomie s'applique à cinq portées, du garde de construction permanent aux rapports ponctuels sur un diff ou sur toute l'arborescence.
/guardsman # build mode, standard tier /guardsman build sensitive # this ticket touches token refresh /guardsman review # what can we delete from this diff? /guardsman audit # what can we delete from this repo? /guardsman logbook # what did we promise to come back to? /guardsman post-report # where do we actually stand? ## say "stand down", "stop guardsman", or "normal mode" to take him off duty
build
Permanent, par défaut. Tout ce qui précède, à chaque réponse, jusqu'à la relève.
review
Diff courant, une seule passe. Traque la sur-ingénierie et les dérives de convention. Liste les constats, n'applique rien.
audit
Dépôt entier, une seule passe. Même taxonomie, arborescence complète — dépendances qui doublonnent la bibliothèque standard, interfaces à implémentation unique, wrappers qui ne font que déléguer, configuration morte — classés du plus gros au plus petit.
logbook
Dépôt entier, une seule passe. Lance le scanner du carnet de garde et rapporte les raccourcis ouverts par gravité, les entrées en retard d'abord.
post-report
Ce dépôt, une seule passe. L'état réel, en direct : entrées de carnet ouvertes, conventions détectées, constats récents.
9. Honnête par conception : aucun chiffre inventé
Voici une promesse que vous ne trouverez pas dans la plupart des READMEs : Guardsman ne vous dira jamais qu'il vous a « économisé 12 000 lignes ». Il n'existe aucune version de référence non construite de votre base de code à laquelle se comparer ; aucun outil — celui-ci compris — ne peut donc produire ce chiffre honnêtement.
Le mode post-report n'affiche que ce qui est directement dénombrable, calculé en direct, sur votre dépôt, maintenant. Si rien n'a encore été calculé, il le dit et propose de lancer l'analyse — au lieu de présenter un chiffre assuré qui ne correspond à rien.
Un outil qui invente des chiffres sur votre base de code n'a rien à faire à sa garde. La seule métrique qui compte, ce sont les gardes tenues. C'est dans le nom.
Les bancs d'essai y sont soumis eux aussi : le protocole reproductible vit dans le dépôt, et aucun chiffre mis en avant n'est publié avant d'avoir été mesuré — avec sa méthode, ses limites et les scripts pour le reproduire.
10. Les consignes générales
Certaines choses ne sont jamais simplifiées à l'excès — quel que soit le palier, quelle que soit la consigne de rester minimal :
- La validation des entrées aux frontières de confiance.
- La gestion d'erreurs qui évite la perte de données.
- Les mesures de sécurité.
- Les fondamentaux d'accessibilité.
- Tout ce que vous avez explicitement demandé — dès lors que vous avez dit vouloir la version complète, elle est construite, sans y revenir.
Et deux consignes au-dessus des autres. Ne jamais être paresseux sur la compréhension du problème : Guardsman fait tout le tour du périmètre avant de prendre son poste — l'échelle raccourcit la solution, jamais la lecture. Ne quitter le poste qu'une fois régulièrement relevé : aucun tour ne se termine sur une vérification silencieusement sautée ; si un contrôle ne peut réellement pas tourner dans cet environnement, le dire explicitement vaut relève.
You: add retry logic to the payment client
Guardsman: tier: sensitive — this touches the charge path.
[9 lines using the retry helper that already exists in http/util.py]
→ skipped: configurable backoff, add when a second caller needs it
(entered in the logbook).
verified: test_gives_up_after_3_and_surfaces_error — written
and RUN. Failure path covered, concurrent-retry case not
covered, flagged.
Palier : sensible. Neuf lignes. Réutilisation de votre propre utilitaire. Défié sur le chemin où il peut vous faire mal. Honnête sur ce qui n'est pas couvert. C'est tout le produit.
3
Consignes à chaque tâche
7
Barreaux sur l'échelle de construction
5
Modes, un seul skill
FAQ
Questions fréquentes
Le palier trivial dispose d'une voie rapide : une recherche ciblée, une exécution manuelle, terminé. Le défi complet ne s'enclenche que là où le rayon d'impact le justifie. C'est tout l'intérêt des paliers — de la rigueur là où elle paie, de la vitesse là où elle ne coûte rien.
Déclassez-le explicitement et Guardsman s'exécute. Il refuse simplement de deviner ce déclassement du seul fait que le code a l'air facile — car avoir l'air simple est exactement la façon dont un changement dangereux passe devant un garde qui laisse filer tout ce qui a l'air sûr de soi.
Des aide-mémoire dédiés à la bibliothèque standard et aux fonctionnalités natives pour 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 paliers, l'échelle et les seuils de défi s'appliquent à n'importe quel langage.
Non. Guardsman régit ce qui est construit et la façon dont c'est vérifié, pas le ton de la conversation. Associez-le à un skill de style si vous voulez aussi une prose concise.
Les skills « moins de code » corrigent le mode de défaillance de sur-construction mais aggravent discrètement l'autre : le diff minuscule, sûr de lui et non testé, sur un chemin dangereux. Guardsman conserve l'échelle de construction qui réduit le code et ajoute l'étape que ce courant a laissée de côté — le défi, une vérification réellement exécutée avant de déclarer le changement terminé.
Vous développez avec Claude Code ?
Braquez-le d'abord sur votre file de revues. Issues et retours de terrain bienvenus.