Trois mois. C'est le temps pendant lequel j'ai laissé les Claude Code Hooks traîner dans la documentation, sans les lire, tandis que je me plaignais que l'IA produisait du code qui ignorait mes conventions de formatage. J'avais configuré Claude Code en janvier, j'ai commencé à livrer des fonctionnalités avec presque immédiatement, et je me suis dit que je « m'occuperais de ce truc avec les hooks plus tard ». Classique.
Il s'avère que les hooks n'étaient pas un plus appréciable. C'était la pièce manquante qui rendait Claude Code vraiment compatible avec un flux de travail d'agence réel, au lieu d'être un complément de code très coûteux qui ignorait occasionnellement ESLint.
Ce que les Claude Code Hooks font réellement (pas d'abstractions vagues)
Les Hooks sont des commandes shell que Claude Code déclenche à des points spécifiques pendant son propre fonctionnement. Pensez-les comme des événements de cycle de vie, similaires aux Git Hooks si vous avez déjà écrit un script de pre-commit, mais intégrés à la boucle d'utilisation d'outils de l'IA plutôt qu'au pipeline de commit de Git.
Il y a quatre types d'événements en ce moment :
PreToolUse, s'exécute avant que Claude n'appelle n'importe quel outil (éditions de fichiers, commandes bash, etc.)PostToolUse, s'exécute après la fin d'un appel d'outilNotification, se déclenche quand Claude vous envoie une notificationStop, s'exécute quand Claude termine son tour de réponse complet
Vous les configurez dans un fichier settings.json à l'intérieur du dossier .claude/ de votre projet, ou globalement dans ~/.claude/settings.json si vous les voulez partout. Chaque hook obtient un matcher (quel outil ou événement le déclenche) et un tableau hooks de commandes shell à exécuter.
La sortie de votre hook est réinjectée dans le contexte de Claude. Ce dernier point est ce qui rend cela véritablement intéressant plutôt que juste un travail cron de fantaisie.
En quoi c'est différent de simplement exécuter des scripts vous-même
Vous pourriez manuellement exécuter Prettier après chaque modification de Claude. Je l'ai fait, pendant environ deux semaines, jusqu'à ce que j'oublie pendant une poussée de deadline et que je pousse une PR avec 47 violations de formatage. Les hooks s'exécutent automatiquement, à l'intérieur de la session, et Claude peut lire leur sortie. Donc si votre linter lève un avertissement, Claude le voit et peut agir dessus dans la même session. Cette boucle de rétroaction est tout le but du jeu.
La configuration qui a vraiment fonctionné pour les projets Seahawk
Je vais être spécifique ici parce que les conseils génériques « ajoutez les hooks à votre config » que vous trouverez dans la plupart des articles sont inutiles sans contexte.
Chez Seahawk, une grande partie de notre travail est les builds WordPress et les personnalisations WooCommerce. Nous faisons aussi des frontends React pour les configurations headless, et nous utilisons Next.js intensément depuis 2022. La configuration de hook sur laquelle j'ai atterri aborde des problèmes spécifiques à ces stacks.
Voici la structure settings.json que j'utilise pour un projet Next.js :
`` { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATHS && npx eslint --fix $CLAUDE_FILE_PATHS" } ] } ], "Stop": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "npx tsc --noEmit 2>&1 | head -20" } ] } ] } } ``
Le hook PostToolUse déclenche Prettier et ESLint immédiatement après que Claude touche à un fichier. Le hook Stop exécute une vérification de type TypeScript à la fin de chaque tour et affiche les 20 premières lignes de toute erreur. Claude lit cette sortie, et s'il y a des erreurs de type, il les corrige avant même que je ne voie la réponse.
Cette seule vérification TypeScript m'a probablement fait gagner quatre heures le mois dernier sur un projet de tableau de bord fintech où le client avait défini noImplicitAny strictement. Claude continuait à générer des types any dans les fonctions utilitaires. Après que j'aie ajouté le hook Stop, il a commencé à s'autocorriger dans le même tour.
Les Hooks que j'utilise sur les projets WordPress / PHP
WordPress, c'est une bête différente. Pas de TypeScript, bien sûr, mais PHP_CodeSniffer avec le ruleset WordPress Coding Standards, c'est ce qui garde les choses saines. En 2022, j'avais un junior sur un projet WooCommerce qui a passé deux semaines sans lancer PHPCS. La revue de code était... pas agréable.
Pour les projets chargés en PHP, mon hook PostToolUse exécute :
`` vendor/bin/phpcs --standard=WordPress $CLAUDE_FILE_PATHS 2>&1 | tail -30 ``
Et j'apparie ça avec un hook PreToolUse sur les commandes bash :
`` { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo 'Bash tool triggered' >> ~/.claude/audit.log && date >> ~/.claude/audit.log" } ] } ``
Celui-là, c'est de la pure paranoïa. Il écrit chaque commande bash que Claude exécute dans un journal d'audit. Quand vous lancez Claude Code sur un environnement de staging en direct (oui, je l'ai fait, oui c'est un peu risqué), savoir exactement quelles commandes shell ont été exécutées est franchement rassurant.
Bloquer le Comportement Avec les Codes de Sortie des Hooks
Cette partie de la documentation m'a pris du temps à trouver. Si votre hook se termine avec le code 2, Claude Code le traite comme un blocage et ne procède pas à l'appel d'outil. Le code de sortie 0 c'est le succès, n'importe quel non-zéro (mais pas 2) redonne juste stderr en tant que contexte.
Vous pouvez donc écrire un hook PreToolUse qui empêche réellement Claude de faire quelque chose. Je l'utilise sur les projets qui ont un répertoire migrations/ que je ne veux pas que Claude touche de manière autonome :
`` #!/bin/bash if echo "$CLAUDE_FILE_PATHS" | grep -q "migrations/"; then echo "Migrations folder is protected. Do not edit migration files autonomously." exit 2 fi exit 0 ``
Ce script se trouve à .claude/hooks/guard-migrations.sh. Quand Claude essaie d'écrire dans n'importe quoi sous migrations/, il est bloqué et voit le message. Il me demande ensuite de confirmer avant de continuer. Simple, efficace.
C'est le genre de contrôle qui fait la différence entre « je fais un peu confiance à cette IA avec ma base de code » et « je lui fais vraiment confiance avec ma base de code ».
Des Patterns de Hooks Pratiques à Voler
Ce ne sont pas des théories. Chacun provient d'un problème spécifique.
- Exécuter les tests automatiquement après les modifications de fichiers. Je lance
npx jest --testPathPattern=$CLAUDE_FILE_PATHS --passWithNoTestsdans un hookPostToolUse. Il exécute uniquement les tests liés au fichier que Claude vient de modifier, pas la suite entière. Assez rapide pour ne pas être gênant. - Snapshot de formatage prêt pour la validation. Un hook
Stopqui exécutegit diff --statet redonne le résumé à Claude. Il voit exactement ce qui a changé au cours de la session, ce qui l'aide à écrire un message de validation sensé si je le lui demande. - Vérification de sécurité des variables d'environnement. Un hook
PreToolUsesurWritequi recherche les patterns de secrets codés en dur (les choses qui ressemblent à des clés API ou des mots de passe). S'il trouve quelque chose de suspect, exit2. J'aurais dû construire celle-ci il y a environ 18 mois. - Hook de
notificationpour les tâches longues. Quand Claude envoie une notification (l'événement Notification), je déclenche un appelcurlvers un endpoint Pushover pour recevoir une notification push sur mon téléphone. Vraiment utile quand vous lancez une grande refonte et allez vous faire une tasse de café. - Vérification de la syntaxe PHP avant bash. Sur les projets WordPress, un rapide
php -l $CLAUDE_FILE_PATHSavant n'importe quelle exécution bash. Attrape les erreurs de syntaxe fatales avant qu'elles ne cassent un serveur de staging.
La documentation officielle des hooks Claude Code a une référence complète des variables d'environnement disponibles dans les scripts de hook. À mettre en favori.
Ce que les Hooks ne Résolvent Pas
L'honnêteté compte ici. Les hooks ne sont pas une solution pour Claude qui génère du code logiquement faux. Ils résolvent les problèmes de processus : formatage, linting, sécurité des types, couverture des tests. Si Claude ne comprend pas votre modèle de données et construit la mauvaise fonction, aucun linting post-modification ne l'attrappera.
Les hooks ajoutent aussi de la latence. Si votre passage Prettier + ESLint prend quatre secondes, chaque modification de fichier prend maintenant quatre secondes de plus. Sur un projet avec 200 modifications de fichiers dans une session, c'est 13 minutes d'attente. Profiler vos commandes de hook. Gardez-les rapides. Je lance des variantes --fix (qui modifient les fichiers sur place) plutôt que des variantes report-only, précisément parce qu'une seule passe rapide bat une passe lente suivie d'une deuxième passe corrective.
Et ils vous obligent à vraiment réfléchir aux modes de défaillance de votre projet à l'avance. Qu'est-ce qui peut mal tourner si Claude édite le mauvais fichier ? Quels standards doivent absolument être appliqués ? Cette réflexion est précieuse de toute façon, mais cela signifie que les hooks récompensent davantage les développeurs expérimentés que les débutants.
Configuration des Hooks : Étape par Étape
Pour tous ceux qui commencent de zéro :
- Créez un dossier
.claude/à la racine de votre projet s'il n'existe pas. - Ajoutez un fichier
settings.jsonavec votre configuration de hooks (structure montrée ci-dessus). - Pour tout ce qui dépasse une ligne, écrivez un script shell séparé (.claude/hooks/your-script.sh), faites
chmod +xdessus, et appelez-le depuis la config plutôt que d'inliner la commande. - Testez en exécutant
claudedans votre projet et en déclenchant délibérément la condition du hook. Lisez ce qui revient dans le contexte de session. - Vérifiez les logs d'exécution des hooks dans
~/.claude/logs/si quelque chose ne se déclenche pas comme prévu.
La documentation pour développeurs d'Anthropic couvre le schéma complet des settings. Et si vous réfléchissez à la manière dont les hooks s'intègrent dans des workflows de codage IA plus larges, le blog de Simon Willison est où je dirais à quiconque de consulter pour réfléchir plus sérieusement à l'outillage IA agentif dans les vrais projets.
Une chose que j'ai mal comprise au départ : j'ai mis tous mes hooks dans le fichier global ~/.claude/settings.json et me suis demandé pourquoi mes hooks PHP se déclenchaient sur les projets JavaScript. Les paramètres au niveau du projet remplacent les paramètres globaux. Mettez les hooks spécifiques à une stack dans le .claude/settings.json du projet et gardez votre config globale pour les choses qui doivent s'appliquer partout (comme le log d'audit et le hook de notification).
FAQ
Les hooks Claude Code fonctionnent-ils sur Windows ?
Les commandes de hook s'exécutent dans le shell que votre système utilise. Sur Windows, c'est par défaut PowerShell ou CMD, ce qui signifie que les scripts de style bash ne fonctionneront pas nativement. WSL2 est la réponse pratique ici. Je suis sur macOS et Ubuntu sur mes machines de dev, donc je n'ai pas eu ce problème personnellement, mais la documentation d'Anthropic note explicitement la dépendance du shell.
Les hooks peuvent-ils accéder au contexte de conversation de Claude ?
Pas directement. Les hooks s'exécutent comme des commandes shell et reçoivent des variables d'environnement comme CLAUDE_FILE_PATHS et CLAUDE_TOOL_NAME, mais ils n'obtiennent pas la transcription complète de la conversation. Ce qu'ils peuvent faire, c'est écrire la sortie vers stdout, que Claude lit comme contexte après l'exécution du hook.
Les hooks ralentiront-ils noticeablement mes sessions Claude Code ?
Cela dépend entièrement de ce que vos hooks font. Une vérification de syntaxe php -l sur un seul fichier prend moins de 100ms. Exécuter votre suite Jest complète à chaque modification de fichier serait énervant. Gardez les commandes individuelles de hook sous deux ou trois secondes et vous les remarquerez à peine.
Est-ce sûr d'utiliser les hooks sur des environnements de production ?
Je poserais cette question à l'envers : êtes-vous en train d'exécuter Claude Code directement sur la production ? Si oui, les hooks sont le moindre de vos soucis. Utilisez-les sur staging, utilisez le pattern de blocage PreToolUse pour protéger les répertoires sensibles, et gardez Claude loin des bases de données de production entièrement.
Quelle est la différence entre les hooks au niveau du projet et les hooks globaux ?
Les hooks globaux se trouvent dans ~/.claude/settings.json et s'appliquent à chaque session Claude Code sur votre machine. Les hooks au niveau du projet se trouvent dans .claude/settings.json à l'intérieur d'un projet spécifique et ne se déclenchent que lorsque vous êtes dans ce projet. Le niveau du projet a la priorité quand les deux définissent le même événement.
---
Le résumé honnête : les hooks ne sont pas glamoureux. Personne ne va écrire un article de blog sur la belle architecture d'un script shell qui exécute Prettier. Mais c'est la différence entre Claude Code qui est un jouet prototype et quelque chose en lequel vous feriez réellement confiance sur du travail client. J'aurais dû les mettre en place dès le premier jour. Vous devriez probablement aussi.