Hooks et scripts : automatiser votre workflow

Vue d'ensemble

Les hooks exécutent des scripts automatiquement à des moments définis, pour que la bonne chose se produise, que quelqu'un s'en souvienne ou non. Claude Code a ses propres lifecycle hooks qui se déclenchent autour des actions de l'agent, et Git a des hooks qui se déclenchent autour des commits et des pushes. L'usage classique le plus précieux est un quality gate qui lance votre linter, votre typechecker et vos tests avant que le code ne puisse quitter votre machine, si bien qu'une régression ne peut physiquement pas atteindre votre repo ou la production. Cette leçon câble les deux avec une configuration réelle et exécutable.

Ce que vous allez apprendre

Vous allez apprendre ce qu'est un hook, les lifecycle events dans lesquels Claude Code vous laisse vous accrocher, comment configurer un hook dans settings.json, en quoi cela diffère d'un git pre-push hook et comment assembler un quality gate qui protège automatiquement votre projet. Vous repartez avec un snippet settings.json fonctionnel et un git hook fonctionnel, que vous pouvez adapter.

Prérequis

Un projet sous version control issu du Cours 1 et au moins un contrôle exécutable depuis la ligne de commande, comme un script de lint ou de test. La CLAUDE.md de la leçon un aide aussi, car votre fichier de règles devrait déjà nommer la commande de quality gate que vos hooks vont imposer. Le détail de ce qui doit aller dans le gate est le Cours 5.

Le problème

Vous savez que vous devriez lancer les tests avant de pousser. La plupart du temps, vous le faites. Mais c'est vendredi, le changement est petit, vous êtes sûr que tout va bien, et vous le sautez. C'est le push qui casse la production. Se reposer sur la discipline humaine pour des contrôles de routine échoue tôt ou tard, pour tout le monde, parce que l'attention est finie et que le contrôle ennuyeux est la première chose à sauter quand vous êtes fatigué ou pressé. La solution n'est pas plus de discipline. C'est de retirer l'humain de la boucle, pour que le contrôle tourne automatiquement à chaque fois, sans qu'aucune décision n'intervienne.

Ce qu'est un hook

Un hook est une commande qui tourne automatiquement quand un event précis se déclenche. Vous décidez de l'event et de la commande, et si la commande se termine en erreur, l'action peut être bloquée. Claude Code fournit des lifecycle hooks autour du travail de l'agent : avant qu'un outil ne tourne (PreToolUse), après qu'un outil a tourné (PostToolUse), quand l'agent a fini de répondre (Stop) et d'autres. Vous pouvez utiliser PostToolUse pour formater automatiquement un fichier au moment où l'agent le modifie, ou PreToolUse pour bloquer une commande dangereuse. Ces hooks sont déterministes - c'est le harness qui exécute votre script, pas le modèle qui décide de le faire.

• PreToolUse : tourne avant un appel d'outil. Utilisez-le pour valider ou bloquer une action avant qu'elle ne se produise.
• PostToolUse : tourne après un appel d'outil. Utilisez-le pour formater ou linter automatiquement un fichier juste après une modification.
• Stop : tourne quand l'agent a fini de répondre. Utilisez-le pour lancer un contrôle final ou vous notifier.
• Les hooks sont un comportement déterministe du harness, donc ils se déclenchent de façon fiable - contrairement à demander poliment au modèle de se souvenir.

Câbler un hook dans settings.json

Les hooks de Claude Code se configurent dans settings.json, dans votre projet sous .claude/settings.json ou dans votre configuration utilisateur. Chaque hook correspond à un event et à un motif d'outil et exécute une commande shell. Voici un vrai hook PostToolUse qui formate et linte chaque fichier TypeScript dès que l'agent le modifie ou l'écrit, pour que la codebase ne reste jamais dans un état désordonné entre les tours.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bun run prettier --write \"$CLAUDE_FILE_PATHS\" && bun run eslint --fix \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}

Le matcher cible les outils Edit et Write, et la commande tourne contre les fichiers que l'agent vient de toucher. Désormais, le formatage n'est jamais quelque chose auquel vous ou l'agent devez penser, parce que le harness s'en charge après chaque changement. Consultez les docs officielles sur les hooks pour les variables d'environnement exactes et la syntaxe des matchers, car elles sont affinées avec le temps.

Le quality gate pre-push

L'automatisation de loin la plus précieuse est un gate qui lance votre suite complète de contrôles avant que le code ne puisse quitter votre machine. L'endroit le plus robuste pour cela est un git pre-push hook, car il protège le repo quel que soit l'agent ou l'humain qui pousse. Un git hook est simplement un script exécutable dans le dossier .git/hooks, ou mieux, géré par un outil comme Husky pour être committé et partagé. Si un contrôle échoue, le script se termine avec un code non nul et le push est refusé. Le code cassé ne peut pas atteindre votre repo, point.

#!/usr/bin/env bash
# .husky/pre-push - bloque le push si un contrôle échoue

set -e  # s'arrêter à la première commande qui échoue

echo "Running quality gate before push..."
bun run lint
bun run typecheck
bun run test

echo "All checks passed. Pushing."

Avec set -e, le premier contrôle en échec interrompt le script et le push n'a jamais lieu. Ce seul gate empêche la façon la plus fréquente dont les équipes shippent des régressions : quelqu'un saute les tests sur un « petit » changement. Il vous coûte une minute à chaque push et vous épargne l'après-midi qu'un déploiement cassé aurait coûté.

Agent hooks versus git hooks

Ces deux systèmes se complètent, et savoir lequel vous utilisez compte. Les hooks de Claude Code se déclenchent autour des actions de l'agent et sont formidables pour garder chaque modification propre - formater à l'écriture, bloquer une commande interdite, vous notifier quand une longue tâche se termine. Les git hooks se déclenchent autour des events de version control et sont le bon endroit pour le quality gate dur, car ils gardent le repo, peu importe qui ou quoi déclenche le push. Le schéma qu'utilisent la plupart des builders sérieux : agent hooks pour le rangement en chemin, git hooks pour le gate final que rien ne franchit. Deux valent mieux qu'un.

Erreurs fréquentes

Les courantes : mettre votre unique quality gate dans un agent hook, si bien qu'un push manuel depuis le terminal passe droit à côté ; écrire un hook si lent que chaque push devient une corvée et que vous commencez à le contourner ; oublier set -e, si bien qu'un contrôle en échec est ignoré et que le push continue quand même ; et ne pas committer vos git hooks (utilisez Husky), si bien qu'ils ne protègent que votre machine et pas vos coéquipiers. Un gate ne fonctionne que s'il est rapide, partagé et vraiment bloquant.

ROI business

L'automatisation bat la discipline à chaque fois, et le calcul est brutalement en sa faveur. Un gate pre-push qui dure une minute empêche le déploiement cassé qui coûte un après-midi de pompiers plus la perte de confiance d'un bug visible par les clients. Coder le contrôle comme un hook signifie qu'il tourne pour tout le monde, à chaque fois, avec zéro attention en continu. Pour une fondatrice, cela transforme « j'espère que tout le monde pense à tester » en « le code cassé ne peut pas shipper » - une garantie au lieu d'un souhait. Une bonne automatisation fait de la bonne chose le réglage par défaut, et le réglage par défaut est ce qui se passe réellement le vendredi à 18 h.

Checklist

Vous êtes prêt à avancer quand chacun de ces points est vrai. Le gate que vous bâtissez ici est la colonne vertébrale du travail qualité du Cours 5.

• Vous savez nommer trois lifecycle events de Claude Code et à quoi chacun sert.
• Vous avez un hook PostToolUse qui formate ou linte après les modifications.
• Vous avez un git pre-push hook qui lance lint, typecheck et test et bloque en cas d'échec.
• Vos git hooks sont committés et partagés, pas seulement sur votre machine.

Ressources

Gardez en favoris la documentation officielle des hooks de Claude Code pour les noms d'events, matchers et variables d'environnement à jour. Husky est l'outil standard pour des git hooks committés et partagés - ses docs vous guident dans le setup en quelques commandes. La leçon de tests du Cours 5 traite exactement de ce que vous mettez dans le gate, pour qu'il attrape de vrais bugs sans être lent.

Votre mission

Ajoutez un git pre-push hook dans un vrai projet, qui lance vos commandes lint, typecheck et test et bloque le push si l'une échoue. Cassez délibérément un test, tentez de pousser et regardez le refus. Ajoutez ensuite un hook PostToolUse de Claude Code qui formate les fichiers après les modifications. Vous avez maintenant une automatisation qui impose vos standards, au lieu de votre mémoire.

Prochaine leçon

Votre agent suit désormais des règles, pilote des workflows empaquetés et impose des gates automatiquement. La prochaine leçon le connecte au monde au-delà de vos fichiers : MCP, le Model Context Protocol, qui donne à votre agent l'accès à des bases de données, des outils de design, des services et des sources de données via un connecteur standard.