Claude Code Hooks: automatiser vos quality gates

Ce qu'est vraiment un hook

Chaque hook a trois parties: un evenement (le moment du cycle de vie ou il se declenche), un matcher optionnel (un filtre pour qu'il ne tourne que pour certains tools) et une action (la commande shell qu'il execute). Quand un hook se declenche, Claude Code lui passe du JSON via l'entree standard qui decrit l'evenement (ID de session, repertoire de travail, le nom du tool et son input), et votre script decide quoi faire. Le code de sortie de la commande pilote le flux: exit 0 signifie continuer, et un exit non nul (par convention 2) bloque l'action et renvoie votre message a l'agent pour qu'il reagisse.

• Evenement: quand le hook se declenche (par exemple apres qu'un tool a tourne).
• Matcher: un filtre optionnel, par exemple uniquement sur les edits de fichiers.
• Action: la commande shell que Claude Code execute.

Les evenements du cycle de vie que vous pouvez hooker

Les hooks couvrent tout le cycle de vie des tools. Ceux que vous utilisez le plus sont PreToolUse et PostToolUse (autour de chaque appel de tool), Stop (quand l'agent veut terminer) et SessionStart (quand une session commence). Pour un controle plus fin, il y en a d'autres.

• PreToolUse: avant qu'un tool ne tourne - valider ou bloquer l'action.
• PostToolUse: apres qu'un tool a tourne - formater, linter ou verifier le resultat.
• UserPromptSubmit: quand vous envoyez un prompt - injecter du contexte ou securiser l'input.
• Stop et SubagentStop: quand l'agent (ou un subagent) veut s'arreter - lancer les tests comme dernier gate.
• SessionStart et Notification: setup de session et quand l'agent a besoin de votre attention.

Ou les hooks se configurent

Les hooks vivent dans votre settings.json Claude Code. Mettez les gates non negociables a l'echelle de l'equipe dans le fichier de projet sous .claude/settings.json, pour que tout le monde partage les memes garde-fous, et gardez les preferences personnelles dans vos user settings. Chaque entree associe un evenement a un matcher et a la commande a executer.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "bun run lint --fix" }
        ]
      }
    ]
  }
}

Un setup de quality gate pratique

Le setup le plus puissant est petit: formater et linter a chaque write, et lancer votre suite de tests comme gate Stop, pour que l'agent ne puisse pas declarer une tache faite avec des tests rouges. Ajoutez un guard PreToolUse si vous voulez bloquer les commandes shell destructrices. Gardez les scripts de hooks rapides et idempotents, parce qu'ils tournent souvent, et en cas de blocage, ecrivez un message clair sur la sortie d'erreur standard pour que l'agent sache comment le corriger.

Pas à pas

1. 01

   Creer votre fichier de settings

   Creez .claude/settings.json a la racine de votre projet s'il n'existe pas. C'est ici que vivent les hooks partages a l'echelle de l'equipe.

2. 02

   Ajouter un hook PostToolUse pour formater et linter

   Sous hooks.PostToolUse, ajoutez un matcher "Edit|Write" et une commande qui execute votre formatter et votre linter, pour que le code soit nettoye apres chaque changement de l'agent.

3. 03

   Ajouter un hook Stop qui lance vos tests

   Sous hooks.Stop, ajoutez une commande qui execute votre suite de tests. Exit non nul en cas d'echec, pour que l'agent ne puisse pas terminer avec des tests qui echouent et continue plutot a les corriger.

4. 04

   Ajouter un guard PreToolUse pour les commandes risquees

   Sous hooks.PreToolUse avec un matcher Bash, ajoutez un script qui verifie la commande depuis le JSON stdin et bloque avec exit 2 les operations destructrices comme le force-push ou la suppression recursive.

5. 05

   Tester et committer

   Faites un petit edit et confirmez que les hooks se declenchent comme attendu, puis committez le fichier de settings pour que toute l'equipe herite des memes garde-fous.

Questions fréquemment posées

Continuez à apprendre