Guardsman : aucun diff ne passe sans être défié

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.
Ce que la plupart des outils ratent

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.

Démarrage rapide Claude Code
# 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.

Une entrée du carnet Exemple
# 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.

Changer de mode Claude Code
/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.
La règle d'honnêteté est le produit

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.

Exemple traité Ajouter une logique de réessai au client de paiement
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.

Vous développez avec Claude Code ?

Braquez-le d'abord sur votre file de revues. Issues et retours de terrain bienvenus.

Ajouter une étoile sur GitHub

Contact

Un système à construire ?

Si vous montez un pipeline RAG, un workflow d'agents IA ou une intégration MCP et que vous voulez comparer vos notes, échanger des idées, ou simplement éviter les erreurs que j'ai déjà faites — écrivez-moi.

Ou recevez le Playbook par e-mail — un message quand une nouvelle leçon sort, et rien d'autre.

Pas de bruit, pas de spam. Désinscription à tout moment.