# Recettes d'agents

Livrable du point 1.8 de **#426**. Ce document dit ce que le dépôt offre pour
travailler avec un agent : les agents disponibles, les hooks qui les
contraignent, et les scripts d'appui.

Il existe parce que `.claude/README.md` décrivait un répertoire `templates/`
inexistant tout en taisant seize agents et huit hooks. Une configuration qu'on
ne peut pas trouver ne sert à personne.

---

## 1. Les huit hooks, et ce qu'ils empêchent vraiment

Un hook qui « avertit » et un hook qui « bloque » ne se remplacent pas. La
colonne compte autant que le nom.

| Hook | Moment | Bloque ? |
|---|---|---|
| `pretool-deny-prod-action.sh` | avant l'outil | **oui** — commandes Bash dangereuses |
| `pretool-deny-secret-write.sh` | avant l'outil | **oui** — écriture dans un fichier porteur de secret |
| `pretool-warn-sensitive-edit.sh` | avant l'outil | non — avertit sur une modification sensible |
| `posttool-format.sh` | après l'outil | non — formate le fichier édité |
| `posttool-warn-unwrap.sh` | après l'outil | non — signale un `unwrap` introduit |
| `stop-leak-scan.sh` | à l'arrêt | **oui** — secrets dans les changements en attente |
| `session-start.sh` | au démarrage | non — vérifie les dépendances, alerte sur branche protégée |
| `userprompt-inject-rules.sh` | à chaque message | non — injecte les règles critiques dans le contexte |

**Trois bloquent, cinq informent.** Confondre les deux catégories, c'est croire
protégé ce qui est seulement commenté — le défaut le plus fréquent de ce
dépôt, retrouvé six fois le 2026-09-07 dans les gardes de CI.

## 2. Les seize agents

`.claude/agents/` contient huit agents, chacun avec son fichier de mémoire :

| Agent | Domaine |
|---|---|
| `rust-expert` | backend, domaine, hexagonal |
| `astro-svelte-expert` | frontend, Svelte 5, Astro |
| `code-reviewer` | revue |
| `devops-engineer` | CI, conteneurs |
| `platform-engineer` | plateforme |
| `sre-platform` | exploitation, incidents |
| `csi-analyst` | amélioration continue |
| `support-agent` | support utilisateur |

Le fichier `*.memory.md` de chacun conserve ce qu'il a appris. Le lire avant de
lancer l'agent évite de refaire une enquête déjà menée.

## 3. Les scripts d'appui

`.claude/scripts/` — quatre scripts, dont le rôle n'est pas devinable au nom :

- `sync-playwright-videos.sh` et `copy-videos.sh` — récupèrent les
  enregistrements de la documentation vivante ;
- `generate-video-rst.py` — en produit les pages ;
- `sync-docs-structure.sh` — aligne l'arborescence documentaire.

`slow-down-tests.sh` et `restore-test-speed.sh` **ne sont plus là** : ils
ralentissaient les parcours en **modifiant les fichiers du gate**, ce que la
Méthode Foyer nomme comme l'anti-patron de la documentation vivante (#876).
La cadence est désormais une constante d'un harnais séparé — `make vitrine`.

## 4. Les gardes du dépôt, et ce qu'elles gardent

Ce sont des tests, pas des hooks : ils s'exécutent en CI et échouent.

| Garde | Ce qu'elle refuse |
|---|---|
| `garde-data-testid` | la disparition d'un identifiant de test (#802) |
| `garde-couverture-testid` | l'aggravation de la dette d'ancrage (#803) |
| `garde-messages-en-dur` | un message de toast non traduit (#833) |
| `garde-libelles-en-dur` | l'aggravation des libellés non traduits (#834) |
| `garde-roles` | un rôle serveur sans menu ni registre (#814) |
| `garde-roles-non-travestis` | un rôle remplacé par un autre (#836) |
| `garde-classes-tailwind` | une classe assemblée à l'exécution (#788) |
| `garde-secrets-console` | un secret écrit dans la console |
| `garde_ecriture`, `garde_lecture` | l'aggravation de la dette d'identité (#772) |
| `garde_perimetre_wbs` | une issue du périmètre absente du WBS |
| `garde_classement_par_souschaines` | l'aggravation du tri d'erreurs par sous-chaîne (#762) |
| `check-no-f64-money.sh` | un montant en `f64`, dans `src/` **et** dans `tests/` (#443) |

**La plupart sont des cliquets** : ils bornent une dette sans exiger sa
disparition immédiate. Celui qui touche un écran le laisse mieux ancré et mieux
traduit qu'il ne l'a trouvé.

## 5. La règle qui vaut plus que les autres

> Jouer les suites, adapter les spécifications, ajouter les tests manquants
> **dans le même commit que le changement** — pas en passe de nettoyage après
> coup.

Et sa conséquence directe : **vérifier une garde neuve par témoin.** On
réintroduit le défaut, on s'assure que le test échoue, on le retire. Sans ce
geste, on ne sait pas si la garde garde.

Six gardes ont été trouvées inopérantes le 2026-09-07 — l'une affichait sans
bloquer, une autre comptait la mauvaise porte, une troisième éprouvait un
chemin que la production n'emprunte pas, une quatrième regardait le mauvais
répertoire. Aucune n'avait été vérifiée par témoin.