Les hooks qui valent la peine sur un dépôt de site

Un agent capable de modifier votre dépôt le modifiera un jour de travers. Rarement, et rarement d'une façon qui saute aux yeux dans le diff, mais assez souvent pour que relire chaque changement vous-même annule l'intérêt de l'agent. La réponse n'est pas de mieux relire. C'est une barrière: un script qui s'exécute seul à un moment fixe de la session et refuse le changement quand il échoue. Claude Code appelle cela des hooks, et sur un dépôt de site trois d'entre eux font l'essentiel.

Un hook est une commande shell qui a un avis

Un hook est une commande que Claude Code exécute à un moment nommé de la session, avec sur stdin un JSON décrivant ce qui vient de se passer. Votre script lit ce JSON, décide, puis répond par son code de sortie. Sortie 0: aucun avis, l'action suit le flux de permissions habituel. Sortie 2: l'action est bloquée, et ce que le script a écrit sur stderr devient la raison que Claude voit. Tout autre code est une erreur non bloquante. C'est à peu près toute l'interface, et le guide de démarrage couvre le reste.

Cela compte plus qu'il n'y paraît. Une barrière qui se contente d'avertir n'est pas une barrière: un agent lancé dans une tâche longue lira l'avertissement, en prendra acte et continuera. Une barrière qui sort en 2 supprime le choix. La discipline consiste à décider, pour chaque contrôle qui vous importe, si vous voulez réellement arrêter le travail ou seulement l'annoter, puis à choisir le code de sortie correspondant.

La référence des hooks liste des dizaines d'événements, ce qui intimide jusqu'à ce qu'on remarque qu'ils tiennent en trois cadences: une fois par session, une fois par tour, une fois par appel d'outil. Un dépôt de site a besoin d'un événement de chaque.

Barrière un: ne laissez pas le build casser en silence

Le hook le plus rentable sur un dépôt de site lance le typecheck et le build de production sur l'événement Stop, quand Claude termine sa réponse. C'est la réponse la moins chère à la question qui clôt chaque session d'agent: est-ce vraiment vert? Une session qui a touché quatorze fichiers et annonce un succès n'est pas une preuve. Un build qui compile en est une.

Sur ce site, la barrière tient en une commande, et elle a attrapé des défauts réels que la lecture du diff a laissés passer. Neuf clés d'icônes inventées dans un même lot d'articles, parce que le fichier de données les valide au build et rien avant. Une entrée manquante dans une table de correspondance qui aurait planté quatre-vingt-huit pages de ville à la requête. Les deux auraient atteint la production portés par un résumé confiant. Aucun n'a survécu au build. L'article compagnon sur la vérification du travail de l'agent parcourt le reste de la liste.

Barrière deux: bloquez la modification que vous n'approuveriez jamais

PreToolUse se déclenche avant un appel d'outil et peut le refuser. Le motif documenté: un matcher qui cible un outil, une condition optionnelle qui affine, et un script qui sort en 2 avec une raison. Sur un site, la liste de ce qui mérite un refus est courte et stable: les écritures dans le fichier d'environnement, celles dans tout fichier généré, et toute commande qui pousse avant que le build ait tourné.

La tentation est de l'écrire comme une règle de permission, et pour une partie c'est le bon choix: une règle deny dans votre fichier de réglages est plus simple et ne demande aucun script. Le hook s'impose quand la décision dépend du contenu et non du chemin, ce qui est précisément le cas des secrets. Une règle de chemin ne peut pas vous dire que la chaîne sur le point d'être écrite dans un composant est une clé d'API active. Un hook qui inspecte le contenu proposé, si.

Barrière trois: dites à l'agent ce qu'il ne peut pas savoir

Le champ le plus sous-utilisé de tout le système est additionalContext sur PostToolUse. Il prend une chaîne, l'emballe en note et la dépose à côté du résultat de l'outil, si bien que Claude la lit à la requête suivante. Ce n'est pas un blocage. C'est une correction livrée au seul moment où l'agent tient encore la pensée concernée.

Le nôtre se déclenche à l'écriture d'un fichier sous le dossier d'images et dit une seule chose: l'optimiseur met en cache par chemin source, pas par contenu, donc un remplacement sur place sert l'ancien fichier jusqu'au vidage du cache. C'est un comportement documenté de l'optimisation d'images de Next.js, invisible dans le diff, invisible au build et invisible sur une capture prise trop tôt. Cela nous a coûté deux tours de confusion avant le hook. Plus rien depuis.

Chaque dépôt a trois ou quatre faits de ce genre: vrais, lourds de conséquences, et non déductibles du code. Leur place est un hook plutôt que vos instructions de projet, parce qu'une note déclenchée sur la modification concernée porte mieux qu'une ligne dans un fichier lu quarante minutes plus tôt. L'article sur un CLAUDE.md qui change les décisions montre où passe la frontière.

Les hooks ne sont pas de l'intégration continue

Un hook tourne sur votre machine, dans votre session, sous vos réglages. Il protège le travail en cours. Il ne protège pas la branche: un collègue sans votre fichier de réglages n'en bénéficie pas, ni rien qui atteigne le dépôt par une autre voie. Pour cela, il vous faut toujours un workflow en CI qui lance les mêmes commandes sur une copie propre.

La bonne façon de tenir les deux: le hook est une barrière locale rapide, réglée pour la boucle de l'agent, et la CI est la barrière lente et faisant autorité, réglée pour la branche. Lancez le même script dans les deux pour n'avoir qu'une définition du vert. En cas de désaccord, c'est le hook qui a tort.

Commencez par un

Trois barrières, c'est l'aboutissement, pas le départ. Ajoutez le hook Stop qui lance votre build, vivez avec une semaine, et regardez ce qui passe encore. Les deuxième et troisième hooks doivent être écrits contre des défauts réellement vécus, car une barrière qui garde un échec qui n'arrive jamais est un impôt sur chaque session pour rien. Sur un site comme le nôtre, l'ordre était évident après coup: la barrière de build s'est payée le premier jour, la note sur le cache d'images la première semaine, et la barrière des secrets ne s'est jamais déclenchée, ce qui est exactement la bonne dose pour celle-là.

Si le dépôt n'est pas encore en place, le guide de construction est le point de départ, et l'article sur les skills couvre l'autre moitié de la configuration. Nous faisons cela sur les projets clients dans le cadre d'un build sur mesure, et les barrières font partie de la livraison.