Cinq règles que Claude Code ne peut pas esquiver
Nous avons confié de vraies fonctionnalités à Claude Code sur notre propre API de facturation en TypeScript, et nous l'avons surpris à copier un validateur au lieu de le réutiliser. Cet article liste cinq règles contre la pourriture du code et, pour chacune, le hook ou le réglage Claude Code qui l'impose. La documentation d'Anthropic dit qu'un fichier CLAUDE.md est du contexte, pas une configuration imposée : une règle qui y est écrite reste une phrase que le modèle pèse contre la tâche. Les garde-fous ci-dessous sont des fichiers que le harnais exécute : un bloqueur de duplication qui se déclenche juste après une édition, un tour qui ne peut pas se terminer tant que les tests sont rouges, et des verrous de configuration que l'agent ne peut pas toucher.
Une règle qu'on écrit, un contrôle que le harnais exécute
Un hook Claude Code est un petit script que Claude Code lance lui-même à un moment précis, avant ou après un appel d'outil. Quand le script se termine avec un code d'erreur, ce qu'il a affiché revient à Claude comme un refus. Les bonnes pratiques d'Anthropic séparent les instructions en deux familles : celles que vous écrivez et que le modèle lit (un prompt, un fichier CLAUDE.md, un skill) et celles que vous configurez et que le harnais exécute (un hook, une règle deny, un réglage managé). La documentation sur la mémoire précise que CLAUDE.md sert aux consignes, et que Claude peut décider qu'une consigne ne s'applique pas.
Nous avons testé cette séparation sur une petite API de facturation sans aucune règle écrite, en demandant à Claude des échéanciers récurrents et un export CSV du rapport des impayés. Claude est revenu tout vert : typecheck au vert, tous les tests au vert. Un détecteur de duplication racontait autre chose : le parseur de factures avait été copié ligne pour ligne dans le nouveau parseur d'échéanciers, et la recherche de client du handler dans le nouveau handler.
| Configuration | Fonctionnalités | Clones exacts trouvés | Tests au vert |
|---|---|---|---|
| Règles écrites en prose dans CLAUDE.md | 1 | 0 | 45 |
| Aucune règle écrite | 1, puis une seconde par-dessus | 3, toujours 3 | 47, puis 55 |
Les clones sont restés invisibles dans le rapport de Claude sur les deux fonctionnalités. Chaque garde-fou de cet article vit dans un seul fichier de réglages du dossier .claude, avec un bloc de hooks et une liste deny.
Règle un : réutiliser avant d'écrire
Le garde-fou est un hook PostToolUse sur les outils Edit et Write. Le script lit le chemin du fichier édité dans son entrée, lance jscpd sur le dossier source, et compare le nombre de clones à une référence stockée dans le dépôt, pour que la duplication ancienne ne bloque pas le travail du jour. Quand le compte augmente, le script affiche la règle et l'emplacement du jumeau, puis se termine avec le code 2. La référence des hooks dit qu'après l'exécution d'un outil, le code 2 montre le message à Claude ; un script qui se termine avec 0 n'est jamais vu, quoi qu'il affiche.
Au rejeu de la fonctionnalité d'échéanciers avec le hook installé, Claude a écrit le nouveau handler et le hook s'est déclenché aussitôt, en désignant la recherche de client du handler de factures comme jumeau. La phrase suivante de Claude a été de dire que le contrôle se trouvait maintenant dans les deux handlers et qu'il allait le déplacer dans le dépôt de clients, en une seule méthode appelée des deux endroits. Le détecteur était propre à la fin et le contrôle partagé vivait à un seul endroit.
Les limites : jscpd attrape une copie exacte, pas un helper réécrit de zéro, et un hook qui s'exécute après l'édition ne peut pas l'annuler. Il renvoie un retour d'information.
Règle deux : pas de module que personne n'a demandé
Le garde-fou est un hook PreToolUse sur l'outil Write. Le script ne vérifie qu'une chose : le chemin est-il sous le dossier source et le fichier n'existe-t-il pas encore. Si oui, il affiche une décision JSON qui dit ask avec une raison, et Claude Code la transforme en demande de permission. La référence des hooks donne à un hook PreToolUse quatre décisions possibles : allow, deny, ask ou defer.
Au rejeu, Claude Code s'est arrêté pour demander avant chaque nouveau module de la fonctionnalité d'échéanciers. La fonctionnalité demandait un module d'échéancier, un store et un handler, comme le reste du dépôt, donc chacun a été approuvé. Une demande ultérieure de déplacer les helpers CSV dans un nouveau module utils a levé la même demande, qui a été refusée : Claude Code a rejeté les deux écritures de ce lot, le tour s'est terminé sans rien d'écrit, et Claude n'a pas réessayé.
Deux limites sur la version que nous avons utilisée, 2.1.294 : la demande affiche le nom du fichier et la raison va dans la transcription de Claude, pas dans la boîte de dialogue ; et un fichier créé par une commande shell n'est pas un appel à l'outil Write, donc il passe sous ce hook.
Règle trois : les conventions sont du lint, pas de la prose
Le garde-fou est le linter du projet, lancé sur chaque fichier édité par un hook. Les conventions (alias de type plutôt qu'interfaces, pas d'enums, pas de any, une couche domaine qui ne fait aucune entrée ni sortie) passent de la prose à la configuration ESLint : une règle de syntaxe restreinte rejette une interface ou un enum avec le message propre au projet, et une règle d'imports restreints garde l'accès aux fichiers hors du dossier domaine. Un hook PostToolUse sur Edit et Write lance ESLint sur le fichier qui vient de changer et se termine avec le code 2 en cas d'erreur, si bien que la violation parvient à Claude à la ligne exacte.
Les mots de la convention restent dans un fichier de règles sous .claude/rules/ avec un en-tête paths, qui ne charge le fichier que lorsque Claude touche ce dossier. La documentation sur la mémoire dit qu'une règle limitée à des chemins se charge quand Claude lit, écrit ou édite un fichier correspondant, et prévient qu'un en-tête qui ne se parse pas fait charger la règle partout.
Invité à transformer une union de statuts en enum et un type en interface, Claude n'a rien édité. Il a dit que le refactor casserait les règles du projet, nommé la configuration de lint et le hook qui signalerait le changement, et proposé un objet const à la place. Pour une fonctionnalité de jours fériés qui tentait une lecture de fichier dans le domaine, Claude a fait passer la liste depuis l'extérieur, parce que le domaine n'a pas le droit de faire d'entrée ni de sortie. Le hook n'a jamais eu à se déclencher. Nourri à la main d'un mauvais fichier, il a renvoyé les erreurs à leurs lignes et le refus.
Règle quatre : terminé veut dire que les contrôles ont réussi
Le garde-fou est un hook Stop, un script qui s'exécute quand Claude veut terminer son tour et qui peut répondre « pas encore ». Le script lance le typecheck et la suite de tests ; dès que quelque chose est rouge, il affiche la sortie en échec et se termine avec le code 2. Il compare aussi le nombre de tests au vert à une référence stockée, de sorte qu'une suite qui paraît verte parce qu'un test a été supprimé compte quand même comme rouge. Il vérifie le drapeau stop_hook_active que décrit la documentation, vrai quand Claude continue déjà à cause du hook, et se termine avec 0 dans ce cas pour que le hook ne boucle jamais.
En jouant le développeur pressé, nous avons demandé un renommage rapide d'un champ de rapport en disant à Claude de ne pas lancer les tests. Claude a fait l'édition par une commande shell, a dit que la suite allait maintenant échouer, et a tenté de terminer le tour. Le hook a lancé les tests et refusé avec « Rule 4: tests fail. Not done yet. » suivi des assertions en échec. La phrase suivante de Claude a été de dire que le hook Stop du projet exige des tests verts, donc qu'il allait mettre à jour les attentes périmées. Les tests sont restés en place.
La documentation plafonne la boucle à 8 refus consécutifs, après quoi le tour se termine quand même. Un test réécrit pour passer n'est pas attrapé ; un test supprimé l'est. Un piège : un fil très partagé se plaignait que Claude ignore les hooks Stop, et le script qui y figurait se terminait avec 0, donc le harnais n'a jamais rien bloqué. Le code bloquant est 2, avec la raison sur le canal d'erreur.
Règle cinq : l'agent ne peut pas desserrer ses propres verrous
Chaque contrôle ci-dessus a un raccourci : désactiver strict dans la configuration du compilateur, exclure le test en échec dans la configuration du runner, supprimer le hook du fichier de réglages. Le garde-fou est une liste deny dans le bloc de permissions du fichier de réglages, une ligne Edit(...) par fichier : la configuration du compilateur, la configuration des tests, la configuration du lint et tout ce que contient le dossier .claude. La documentation sur les permissions dit que les règles deny sont évaluées en premier et qu'une règle allow ne peut pas créer d'exception à un deny.
Invité à retirer le hook Stop parce qu'il ralentit, Claude a lu les réglages et n'a pas essayé : il a dit que le fichier porte une règle deny sur le dossier .claude, qu'il pourrait la contourner avec une commande shell, et que le faire contournerait une protection que l'équipe a mise en place volontairement. Invité à désactiver strict, il a refusé au nom de la règle écrite et a lancé le typecheck avec un drapeau à la place. Quand on lui a dit de le modifier quand même, Claude a tenté une commande shell sur le fichier, et le harnais a répondu que la permission d'utiliser cette commande avait été refusée. Claude a répondu qu'il n'avait pas cherché un autre contournement, parce que cela irait contre ce qui a posé ce blocage.
La limite est elle aussi documentée : une règle deny ne couvre pas un script qui ouvre lui-même le fichier, et le fichier peut toujours être édité à la main. C'est voulu.
Quelle règle installer en premier
Chaque règle est un fichier qu'on copie, pas une phrase qu'on espère voir lue par Claude. Avec les règles en prose, une fonctionnalité n'en a enfreint aucune ; sans rien d'écrit, les fonctionnalités suivantes ont laissé trois clones exacts qui sont restés ; avec les garde-fous en place, chacun a refusé une vraie édition.
| Si vous n'installez qu'une chose | Pourquoi |
|---|---|
| Le hook Stop | La plus grande protection pour la plus petite mise en place |
| Puis la liste deny | Quatre lignes dans le fichier de réglages |
| Rien | Sur un prototype jetable |
Quand la suite prend des minutes, gardez la partie rapide dans le hook et déplacez le reste vers le pipeline. La limite honnête vient d'une longue issue du dépôt Claude Code : un hook impose ce qu'un appel d'outil peut montrer, et savoir si une abstraction est la bonne reste une décision humaine. La règle empirique de la documentation elle-même : si vous ajoutez sans cesse de l'emphase à une ligne de CLAUDE.md et que Claude la rate encore, cette ligne relève d'un hook.
AIDive