En bref et verdict
Nous avons confié de vraies fonctionnalités à Claude Code sur notre propre petite API de facturation en TypeScript (Claude Code 2.1.294, Opus 5.5, mode auto) et vérifié le résultat avec un détecteur de copier-coller, le typecheck et les tests. Puis nous avons installé un garde-fou par règle : un hook ou un réglage, pas une ligne dans CLAUDE.md.
- Avec les cinq règles écrites en prose dans CLAUDE.md, la fonctionnalité A (avoirs) n'en a enfreint aucune : 0 clone, 45 tests au vert (34 de référence plus 11), aucun test supprimé et aucune configuration touchée.
- Sans aucune règle écrite, la fonctionnalité B1 (échéanciers récurrents et export CSV) a laissé 3 clones exacts. Le parseur du corps de facture a été copié dans le parseur d'échéanciers, et le code répétitif de recherche d'un handler a été copié dans un second handler. Le typecheck était au vert et 47 tests passaient. Une seconde passe, B2, a laissé les 3 clones en place.
- Avec les garde-fous installés, nous avons rejoué les mêmes prompts. Le hook de clones s'est déclenché sur le handler d'échéanciers (jscpd a trouvé 1 clone, référence 0) et Claude a déplacé le contrôle partagé dans une seule méthode. Le hook de nouveau fichier a levé trois demandes de permission pour les modules d'échéancier, auxquelles nous avons répondu oui, et une pour un fichier utils, à laquelle nous avons répondu non, et rien n'a été écrit. Sur le prompt enum et interface, Claude n'a rien édité et a nommé la configuration de lint et le hook. Le hook Stop a refusé un renommage fait par une commande shell avec « Rule 4: tests fail. Not done yet. » et Claude a corrigé les deux attentes. Une commande shell sur tsconfig.json a été refusée par le harnais.
- Chaque garde-fou a aussi reçu une mauvaise édition faite à la main : le clone, les violations de lint, le build rouge et le test supprimé ont tous été refusés.
Verdict : installez d'abord le hook Stop, puis la liste deny, qui est courte. Passez votre tour sur un prototype jetable. Un hook impose ce qu'un seul appel d'outil peut montrer. Savoir si une abstraction est la bonne reste votre décision.
Synthèse sourcée
CLAUDE.md est du contexte, pas une configuration imposée. La documentation mémoire de Claude Code dit que CLAUDE.md et les règles sont chargés comme contexte, pas comme configuration imposée s2. La page des bonnes pratiques dit la même chose de l'autre côté : CLAUDE.md sert aux consignes, et Claude peut décider qu'une consigne ne s'applique pas. Un comportement obligatoire relève d'un hook, d'une règle deny ou d'un réglage managé s1.
Cela donne deux familles d'instructions. Dans la première, vous écrivez une ligne et le modèle la lit : un prompt, CLAUDE.md, un skill. Dans la seconde, vous configurez un contrôle et le harnais l'exécute : un hook, une règle deny, un réglage managé s1. Les cinq règles de ce pack sont toutes de la seconde famille.
Le code 2 fait une chose différente selon l'événement du hook. Sur PostToolUse, le code 2 montre stderr à Claude alors que l'outil a déjà tourné s3. Un avertissement PostToolUse doit se terminer avec 2 pour atteindre Claude, car stderr d'un hook qui se termine avec 0 n'est jamais vu s3. Sur PreToolUse, le code 2 bloque l'appel même si le hook a affiché une décision allow s3. Sur Stop, le code 2 bloque l'arrêt, et tout ce que la commande affiche sur stderr revient à Claude comme la raison pour laquelle il ne peut pas encore finir s1.
Un hook Stop a besoin d'une garde et a un plafond. Les hooks Stop reçoivent stop_hook_active, vrai quand Claude continue déjà à cause d'un hook Stop, donc on le vérifie pour éviter de bloquer sur une condition qui ne se résoudra jamais s3. La garde documentée se termine avec 0 quand il est vrai s18. Claude Code applique aussi un plafond de 8 continuations consécutives, relevé avec CLAUDE_CODE_STOP_HOOK_BLOCK_CAP s3. Le changelog de la 2.1.143 dit que le tour se termine désormais avec un avertissement après 8 blocages consécutifs s19.
PreToolUse a quatre décisions. Un hook PreToolUse renvoie sa décision dans hookSpecificOutput avec quatre issues : allow, deny, ask ou defer s3. Le hook de nouveau fichier de ce pack répond ask, ce qui vous remet dans la boucle sous forme de demande de permission. Un hook PreToolUse qui dépasse son délai ne bloque pas l'appel. Depuis la 2.1.295, vous pouvez définir onFailure: "block" pour qu'il bloque s3 s19.
Le matcher a un angle mort. Le matcher Edit|Write ne se déclenche que sur les outils Edit et Write, pas sur Bash s18. Les éditions faites par Bash peuvent atteindre un hook PostToolUse dans tool_response.bashEditDiff depuis la 2.1.269, derrière le réglage bashEditDiffEnabled s3 s19.
Règles deny : utilisez Edit(path), et connaissez la limite. Une règle deny Write(path) ne correspond pas. Utilisez Edit(path), qui couvre tous les outils d'édition de fichiers intégrés s4. Les règles deny ne couvrent pas non plus un script Python ou Node qui ouvre lui-même le fichier s4.
Règles limitées à des chemins, et le piège du frontmatter. Une règle limitée à des chemins se charge quand Claude utilise Read, Write ou Edit sur un fichier correspondant s2. Avant la 2.1.288, seul Read les chargeait s19. Si le YAML entre les marqueurs ne se parse pas, Claude Code ignore le frontmatter et charge la règle comme si elle n'avait pas de paths, donc elle s'applique partout s2.
jscpd n'attrape que les clones exacts. Lancé avec npx jscpd ., il cherche des clones. Les exécutions par défaut ne signalent que les clones exacts, et les clones renommés ou approchants sont à activer s20. La taille minimale de clone par défaut est de 50 tokens s20. Notre hook la ramène à 30 tokens et 4 lignes. Dans notre test, une quasi-copie réécrite, avec des lignes différentes et le même comportement, n'a pas été attrapée.
Pourquoi des garde-fous à chaque édition et pas un CLAUDE.md plus long. SlopCodeBench a constaté que le meilleur agent passe 14,8 % des points de contrôle. C'est un taux de réussite, pas une part de code bâclé. L'érosion structurelle augmente dans 77 % des trajectoires et la verbosité dans 75,5 % s6. Le code d'agent est 2,3 fois plus verbeux et 2,0 fois plus érodé que 473 dépôts Python open source s6. Des consignes de qualité explicites réduisent la verbosité et l'érosion initiales jusqu'à un tiers, sans effet sur les taux de dégradation s6. Les consignes aident au départ. Un garde-fou à chaque édition agit sur la pente.
Le hook Stop qui « ne fait rien ». Un fil Hacker News, « Claude is ignoring stop hooks », montre un script qui se terminait sur cat avec le code 0. Le harnais n'a jamais rien bloqué, car bloquer demande le code 2 avec la raison sur stderr s8.
Ce qu'un hook ne peut pas juger. Une issue Claude Code sur les règles de CLAUDE.md non suivies qualifie les hooks PreToolUse de palliatif partiel. Un hook impose ce qu'un seul appel d'outil peut montrer. « Est-ce la bonne abstraction ? » ne se décide pas par un hook, et si vous désactivez le hook, le comportement revient s7.
Code
Note d'installation : settings.json va dans .claude/settings.json, les quatre scripts de hook dans .claude/hooks/, domain.md dans .claude/rules/domain.md, et eslint.config.js à la racine du dépôt. Ajoutez eslint, typescript-eslint et jscpd en devDependencies. Créez deux fichiers de référence : .claude/jscpd-baseline (le nombre de clones) et .claude/test-baseline (le nombre de tests au vert). Les hooks utilisent jq, et le hook Stop appelle pnpm typecheck et pnpm test, donc ces scripts doivent exister dans votre package.json.
Le fichier de réglages contient la liste deny de la règle 5 (tsconfig.json, vitest.config.ts, eslint.config.js et .claude/**) et les entrées de hooks des règles 1 à 4. Placez-le dans .claude/settings.json.
settings.json
{
"permissions": {
"deny": [
"Edit(tsconfig.json)",
"Edit(vitest.config.ts)",
"Edit(eslint.config.js)",
"Edit(.claude/**)"
]
},
"hooks": {
"PreToolUse": [
{ "matcher": "Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/new-file-ask.sh\"", "timeout": 10 } ] }
],
"PostToolUse": [
{ "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-clone.sh\"", "timeout": 60 } ] },
{ "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/lint-edit.sh\"", "timeout": 60 } ] }
],
"Stop": [
{ "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/done-check.sh\"", "timeout": 120 } ] }
]
}
}
Règle 1, réutiliser avant d'écrire. Un hook PostToolUse sur Edit|Write. Il lance jscpd sur src/ après chaque édition d'un fichier .ts, compare le nombre de clones à la référence, et se termine avec le code 2 en donnant l'emplacement du jumeau quand le compte augmente. Placez-le dans .claude/hooks/no-clone.sh.
no-clone.sh
#!/usr/bin/env bash
# PostToolUse hook (matcher: Edit|Write). Rule 1: reuse before you write.
# Runs the copy-paste detector on src/ after every edit. A clone that was not
# there at the baseline blocks with the twin's location (exit 2 -> stderr reaches Claude).
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
case "$FILE" in *.ts) ;; *) exit 0 ;; esac
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
BASE=$(cat .claude/jscpd-baseline 2>/dev/null || echo 0)
OUT=$(mktemp -d)
npx --no-install jscpd src --min-lines 4 --min-tokens 30 --reporters json --output "$OUT" --silent >/dev/null 2>&1
COUNT=$(jq '.statistics.total.clones // 0' "$OUT/jscpd-report.json" 2>/dev/null || echo 0)
if [ "$COUNT" -gt "$BASE" ]; then
echo "Rule 1 (reuse before you write): jscpd found $COUNT clone(s), baseline is $BASE. A helper you just wrote already exists:" 1>&2
jq -r '.duplicates[] | " \(.firstFile.name):\(.firstFile.start)-\(.firstFile.end) == \(.secondFile.name):\(.secondFile.start)-\(.secondFile.end)"' "$OUT/jscpd-report.json" 1>&2
echo "Import and reuse the existing one; do not keep both." 1>&2
rm -rf "$OUT"; exit 2
fi
rm -rf "$OUT"; exit 0
Règle 2, pas de module que personne n'a demandé. Un hook PreToolUse sur Write. Quand le chemin est sous src/ et que le fichier n'existe pas encore, il répond ask avec une raison, et Claude Code affiche une demande de permission. Placez-le dans .claude/hooks/new-file-ask.sh.
new-file-ask.sh
#!/usr/bin/env bash
# PreToolUse hook (matcher: Write). Rule 2: no module nobody asked for.
# Creating a file that does not exist yet under src/ becomes a permission prompt:
# the human says yes or no, the model does not decide alone.
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
CWD=$(printf '%s' "$INPUT" | jq -r '.cwd')
case "$FILE" in "$CWD"/src/*) ;; *) exit 0 ;; esac
[ -e "$FILE" ] && exit 0
REL=${FILE#"$CWD"/}
jq -cn --arg r "Rule 2: new module under src/ ($REL). One new file needs a reason: approve only if the task asked for it, otherwise put the code in the module it belongs to." \
'{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"ask",permissionDecisionReason:$r}}'
Règle 3, les conventions sont du lint. Un hook PostToolUse sur Edit|Write qui lance ESLint sur le fichier .ts édité et se termine avec le code 2 à la moindre erreur. Il se contente de lint et ne corrige jamais. Placez-le dans .claude/hooks/lint-edit.sh.
lint-edit.sh
#!/usr/bin/env bash
# PostToolUse hook (matcher: Edit|Write). Rule 3: conventions are lint, not prose.
# Runs ESLint on the file that was just edited; a violation is a lint error at the
# exact line, every edit (exit 2 -> stderr reaches Claude). Lint only, never --fix.
set -u
INPUT=$(cat)
FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty')
case "$FILE" in *.ts) ;; *) exit 0 ;; esac
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
if ! npx --no-install eslint --no-warn-ignored "$FILE" 1>&2; then
echo "Rule 3: the conventions above are enforced by eslint.config.js; fix the file, do not change the config." 1>&2
exit 2
fi
exit 0
Les règles de lint qu'il applique : type au lieu de interface, pas d'enum, pas de any, pas d'imports d'entrée-sortie ni de store dans src/domain/, et pas d'imports directs de store dans les handlers. Placez le fichier à la racine du dépôt.
eslint.config.js
// Conventions as lint rules. Run on every edited file by .claude/hooks/lint-edit.sh.
import tseslint from "typescript-eslint";
export default [
{
files: ["src/**/*.ts", "test/**/*.ts"],
languageOptions: { parser: tseslint.parser },
plugins: { "@typescript-eslint": tseslint.plugin },
rules: {
"no-restricted-syntax": [
"error",
{ selector: "TSInterfaceDeclaration", message: "Use `type`, never `interface` (project convention)." },
{ selector: "TSEnumDeclaration", message: "Use a const object or a union type, never `enum` (project convention)." },
],
"@typescript-eslint/no-explicit-any": "error",
},
},
{
files: ["src/domain/**/*.ts"],
rules: { "no-restricted-imports": ["error", { patterns: [
{ group: ["node:fs", "node:http", "fs", "http"], message: "src/domain has no I/O." },
{ group: ["../store/*", "../http/*", "**/store/*", "**/http/*"], message: "src/domain imports nothing from store or http." },
] }] },
},
{
files: ["src/http/handlers/**/*.ts"],
rules: { "no-restricted-imports": ["error", { patterns: [
{ group: ["../../store/*", "**/store/*"], message: "Handlers reach the store through the app context only." },
] }] },
},
];
Les mots des conventions vivent dans un fichier de règles limité à des chemins. Il ne se charge que lorsque Claude touche src/domain/. Gardez l'en-tête YAML valide, sinon la règle se charge partout. Placez-le dans .claude/rules/domain.md.
domain.md
---
paths:
- "src/domain/**"
---
# src/domain: pure functions, nothing else
- No I/O here: no `node:fs`, no `node:http`, nothing from `src/store/` or `src/http/`.
- `type`, never `interface`; const objects or union types, never `enum`; no `any`.
- Money is an integer number of cents; reuse `money.ts` (`assertCents`, `formatCents`, `sum`) instead of writing a new helper.
- One new file needs a reason the task gives. No class, factory or generic helper for one caller.
These conventions are checked by ESLint on every edit (`.claude/hooks/lint-edit.sh`).
Règle 4, terminé veut dire que les contrôles ont réussi. Un hook Stop avec la garde stop_hook_active. Il lance le typecheck et les tests, compare le nombre de tests au vert à .claude/test-baseline, et se termine avec le code 2 en donnant la sortie en échec tant que quelque chose est rouge ou qu'un test a disparu. Placez-le dans .claude/hooks/done-check.sh.
done-check.sh
#!/usr/bin/env bash
# Stop hook. Rule 4: done means the checks passed.
# Refuses the end of the turn while typecheck or tests are red, or while the test
# count dropped under the baseline (a suite made green by deleting tests is red).
set -u
INPUT=$(cat)
# Guard: when Claude Code is already continuing because of this hook, let it stop.
[ "$(printf '%s' "$INPUT" | jq -r '.stop_hook_active')" = "true" ] && exit 0
cd "$(printf '%s' "$INPUT" | jq -r '.cwd')" || exit 0
# Nothing changed since the last commit: nothing to check.
[ -z "$(git status --porcelain -- src test 2>/dev/null)" ] && exit 0
LOG=$(mktemp)
if ! pnpm --silent typecheck > "$LOG" 2>&1; then
echo "Rule 4: typecheck fails. Not done yet." 1>&2; tail -30 "$LOG" 1>&2; rm -f "$LOG"; exit 2
fi
if ! pnpm --silent test > "$LOG" 2>&1; then
echo "Rule 4: tests fail. Not done yet." 1>&2; grep -v '^\s*$' "$LOG" | tail -30 1>&2; rm -f "$LOG"; exit 2
fi
BASE=$(cat .claude/test-baseline 2>/dev/null || echo 0)
COUNT=$(grep -oE 'Tests +[0-9]+ passed' "$LOG" | grep -oE '[0-9]+' | head -1)
rm -f "$LOG"
if [ -n "$COUNT" ] && [ "$COUNT" -lt "$BASE" ]; then
echo "Rule 4: $COUNT tests passed, the baseline is $BASE. A test disappeared; restore it." 1>&2; exit 2
fi
exit 0
À faire lundi
- Lancez
claude --versionet vérifiez que vous êtes en 2.1.288 ou plus, pour que les règles limitées à des chemins se chargent sur Write et Edit s19. - Installez
eslint,typescript-eslintetjscpden devDependencies, et vérifiez quejqest dans votre PATH. - Copiez d'abord
done-check.sh, créez.claude/test-baselineavec votre nombre actuel de tests au vert, et ajoutez l'entrée Stop à.claude/settings.json. - Ajoutez la liste
permissions.denyavec des lignesEdit(...)pour la configuration de votre compilateur, de vos tests, de votre lint et.claude/**. N'écrivez pas de lignesWrite(...). - Copiez
eslint.config.js, lanceznpx eslint srcsur le dépôt intact, et corrigez ou mettez en référence tout ce qui remonte avant de brancher le hook. - Lancez
npx jscpd src --min-lines 4 --min-tokens 30, écrivez le nombre de clones dans.claude/jscpd-baseline, puis ajoutezno-clone.shetnew-file-ask.sh. - Copiez
domain.mddans.claude/rules/, adaptez le chemin à vos propres dossiers, et vérifiez que l'en-tête YAML se parse. - Rejouez le geste pour lequel chaque règle a été écrite et lisez le refus. Puis éditez un fichier à la main pour prouver qu'une règle se déclenche.
Mesures
Notre essai : une petite API de facturation en TypeScript avec 34 tests, Claude Code 2.1.294, Opus 5.5, mode auto, 2026-11-07. Clones comptés avec jscpd à --min-lines 4 --min-tokens 30.
| Configuration | Fonctionnalités données | Clones trouvés par jscpd | Tests au vert | Ce qui s'est déclenché |
|---|---|---|---|---|
| Règles en prose dans CLAUDE.md | A : avoirs (1 min 21 s) | 0 | 45 (34 de référence + 11) | Rien à déclencher. Aucune règle enfreinte |
| Aucune règle écrite | B1 : échéanciers récurrents et export CSV (2 min 27 s) | 3 | 47 (34 + 13) | Rien d'installé. 3 nouveaux modules, 14 fichiers modifiés |
| Aucune règle écrite | B2 : endpoint d'annulation et deux exports CSV (environ 1 min 30 s) | 3, les mêmes | 55 | Rien d'installé. Claude a extrait src/http/csv.ts et l'a réutilisé |
| Garde-fous actifs, rejeu en direct | B1 de nouveau, puis le refactor enum, un renommage pressé, un retrait de hook et un changement de tsconfig | 0 à la fin | 54 | Hook de clones une fois (1 clone, référence 0), 3 demandes de nouveau fichier plus 1 refusée, hook de lint jamais nécessaire, hook Stop une fois, deny une fois |
| Garde-fous actifs, test mécanique | Mauvaises éditions faites à la main | 0 sur la référence, 1 après collage d'une copie de 5 lignes de formatCents |
33 sur 34 après suppression d'un test | Hook de clones, ask de nouveau fichier, hook de lint (4 erreurs), hook Stop (build rouge, nombre de tests sous la référence) |
Détails du test mécanique. La configuration ESLint a donné 0 problème sur le dépôt intact. lint-edit.sh sur un fichier avec un import node:fs, une interface, un enum et un any a signalé 4 erreurs à leurs lignes et s'est terminé avec le code 2. Le hook de clones a signalé domain/money.ts:21 == http/views.ts:5. Un chemin sous src/ qui n'existait pas a renvoyé ask avec la raison. Le hook Stop a dit « Rule 4: 33 tests passed, the baseline is 34. A test disappeared; restore it. » Une quasi-copie réécrite n'a pas été attrapée par jscpd.
Aller plus loin
Ce que nous avons gardé hors des cinq règles, et où chacun a sa place.
Hooks git et Lefthook. Un hook git ou un contrôle de pipeline est un endroit valable pour les mêmes vérifications. Il s'exécute au commit, pas pendant que Claude édite, donc le retour arrive plus tard. C'est une autre mise en place que ce pack. Si votre suite prend des minutes, gardez la partie rapide dans le hook Stop et déplacez le reste vers votre pipeline.
Hooks de prompt au niveau de l'agent. Les hooks qui demandent à un modèle de juger une édition ne sont pas déterministes, donc ils ne font pas partie des cinq. Une règle qu'on peut vérifier avec une commande relève d'un script.
Commandes de revue. /simplify et /code-review sont manuelles. Elles sont utiles, mais la revue reste la vôtre, et aucune n'est une garantie imposée.
Chiffres d'incidents des éditeurs. Les rapports d'éditeurs sur les taux d'incidents par pull request sont un signal de corrélation, pas propre à Claude Code et pas mesuré sur notre code. Nous ne les avons pas utilisés. Chaque chiffre de ce pack vient des sources liées ci-dessus ou de notre propre essai.
Un jeu de règles prêt à l'emploi. Le dépôt anti-slop est un jeu de règles Oxlint à vendoriser, avec 18 règles génériques et 5 règles Effect. Il est conçu pour être vendorisé, sans paquet npm officiel s10. C'est un bon modèle de règle : une erreur de lint à la ligne exacte, à chaque exécution.
Règles en prose. Les collections de règles CLAUDE.md sont utiles pour les mots d'une convention. Gardez-les dans des fichiers de règles limités à des chemins, et laissez un contrôle porter la garantie.
FAQ
Une règle deny arrête-t-elle un script Python qui écrit le fichier ? Non. Les règles deny ne couvrent pas un script Python ou Node qui ouvre lui-même les fichiers s4. Quiconque a les clés peut toujours éditer le fichier à la main. La liste deny arrête les outils d'édition intégrés de l'agent et les raccourcis évidents.
Pourquoi mon hook Stop ne bloque-t-il jamais ?
Vérifiez d'abord le code de sortie. Bloquer demande le code 2 avec la raison sur stderr. Un script qui se termine sur cat avec le code 0 ne bloque jamais s8. Vérifiez ensuite la garde : si stop_hook_active est vrai, le hook doit se terminer avec 0. Le plafond met aussi fin au tour après 8 blocages consécutifs s3.
Le matcher Edit|Write attrape-t-il les éditions faites par Bash ?
Non. Il ne se déclenche que sur les outils Edit et Write, pas sur Bash s18. Depuis la 2.1.269, un diff des fichiers qu'une commande Bash a modifiés peut être ajouté au résultat de l'outil Bash derrière bashEditDiffEnabled s19. Notre hook Stop attrape quand même le résultat, parce qu'il lance le typecheck et les tests en fin de tour.
Et les fichiers créés par une commande shell ?
Un fichier créé ainsi n'est pas un appel à l'outil Write, donc le hook de nouveau fichier ne le voit jamais. Ajoutez un matcher Bash si vous voulez le surveiller, ou relisez git status en fin de tour.
Le hook annule-t-il l'édition ? Non. Un hook PostToolUse s'exécute après l'outil, qui a déjà tourné. Il montre stderr à Claude avec le code 2 s3. Claude corrige ensuite le fichier. Seuls le hook PreToolUse et la liste deny arrêtent une action avant qu'elle ait lieu.
AIDive