Skip to main content
Tous les guides
Sommaire du guide

Sommaire du guide

Temps de lecture : 12 min
#automation#hooks#claude#code#guide#beginners
Débutant12 min

Hooks dans Claude Code pour débutants : automatiser les actions répétitives

Guide pratique complet sur la configuration des Hooks dans Claude Code : linting automatique, formatage, vérifications de sécurité avant commit, notifications et automatisation Headless.

Publié :
POUR AGENT IAChatGPTClaude

1. Qu'est-ce que les Hooks dans Claude Code et pourquoi sont-ils essentiels

En travaillant avec un assistant IA dans le terminal, les développeurs sont souvent contraints de répéter les mêmes commandes routinières : "lancez maintenant ESLint", "formatez le code via Prettier", "vérifiez les types avant le commit". Même si ces règles sont inscrites dans les instructions système CLAUDE.md, le modèle de langage peut parfois oublier de les appliquer ou les sauter pour économiser des tokens.

Les Hooks dans Claude Code résolvent ce problème radicalement : il s'agit de déclencheurs déterministes qui exécutent automatiquement des commandes système ou des scripts à des moments précis du cycle de vie de l'assistant.

La logique des hooks est simple :

Si Claude a effectué l'événement X → le système d'exploitation garantit le lancement de l'action Y.

mermaid
flowchart LR subgraph Текстова_інструкція["CLAUDE.md (Ймовірнісна)"] A["Промпт: 'Завжди запускай лінтер'"] --> B{"Модель пам'ятає?"} B -->|Іноді| C["Запуск перевірки"] B -->|Пропустила| D["Помилки накопичуються"] end subgraph Нативний_Hook["Hooks у settings.json (Детермінована)"] E["Подія: Редагування файлу"] --> F["Автоматичний тригер ОС"] F --> G["Гарантоване виконання npx eslint"] end

Comparaison des approches d'automatisation

CaractéristiquePrompts manuelsInstructions dans CLAUDE.mdHooks natifs
Fiabilité d'exécutionFaible (dépend de la mémoire humaine)Moyenne (comportement probabiliste du LLM)100% (interception déterministe des événements)
Consommation de tokensÉlevée (les tokens de requête sont consommés à chaque fois)Moyenne (la règle est chargée dans chaque contexte)Nulle (exécution locale dans le shell)
Vitesse de réactionLente (saisie manuelle des commandes)Nécessite un tour de génération supplémentaireInstantanée (appel natif du processus)
Possibilité de blocageAbsenteAbsenteOui (un exit code non nul stoppe l'action)
Note

Les hooks Claude Code se configurent au format JSON dans le fichier .claude/settings.json au niveau d'un dépôt spécifique ou globalement dans ~/.claude/settings.json.

2. Cycle de vie des événements : PreToolUse, PostToolUse, Notification, Stop

Claude Code prévoit quatre points d'interception fondamentaux (événements) auxquels vous pouvez associer des commandes automatisées.

mermaid
sequenceDiagram autonumber actor Dev as Розробник participant Agent as Claude Code participant Hook as Система Hooks participant Tool as Інструмент (Bash/Edit/Write) Dev->>Agent: Запит на модифікацію коду Agent->>Hook: Спроба виклику інструмента Note over Hook: PreToolUse Hook Hook-->>Agent: Перевірка пройдена (Exit Code 0) Agent->>Tool: Виконання операції Tool-->>Agent: Результат успішний Agent->>Hook: Подія завершення операції Note over Hook: PostToolUse Hook Hook-->>Agent: Результат лінтингу / форматування Agent->>Hook: Завершення відповіді моделі Note over Hook: Stop Hook (Сповіщення) Agent-->>Dev: Фінальна відповідь

Points de déclenchement principaux

  1. PreToolUse (Avant l'utilisation de l'outil) : se déclenche avant que l'agent n'exécute une action. Si la commande du hook retourne une erreur (exit code différent de 0), l'exécution de l'action est bloquée. C'est l'endroit idéal pour les vérifications de sécurité avant les commits ou les pushes.
  2. PostToolUse (Après l'utilisation de l'outil) : se déclenche immédiatement après l'exécution réussie d'un outil. C'est le déclencheur le plus populaire pour le formatage automatique du code (Prettier) ou le linting du fichier modifié (ESLint).
  3. Notification (Notification) : s'active lorsque l'assistant doit envoyer un message système important ou demander une autorisation supplémentaire.
  4. Stop (Fin de réponse) : se déclenche au moment où Claude Code a complètement terminé la génération de la réponse et attend le prochain message utilisateur. Utilisé pour la lecture de signaux sonores et les notifications desktop.
Points de déclenchement des Hooks dans le cycle de vie ЗбільшитиPoints de déclenchement des Hooks dans le cycle de viePoints de déclenchement des Hooks dans le cycle de vie

3. Structure de configuration dans settings.json et syntaxe Matcher

La configuration des hooks est stockée dans le fichier .claude/settings.json. Si ce fichier n'existe pas encore à la racine de votre projet, créez-le.

Syntaxe de configuration de base

json
{ "hooks": { "PreToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "echo 'Починається редагування файлу...'" } ] } ], "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo 'Bash-команда завершена успішно'" } ] } ] } }

Fonctionnement du champ Matcher

Le champ matcher détermine sur quel outil spécifique de l'agent le hook doit réagir :

  • "Edit" — intercepte la modification de fichiers existants.
  • "Write" — se déclenche lors de la création d'un nouveau fichier ou d'une réécriture complète.
  • "Bash" — réagit au lancement de n'importe quelle commande console.
  • "Bash(git commit*)" — modèle précis qui filtre les appels Bash commençant par la commande git commit.
  • "*" — sélecteur universel (wildcard), qui se déclenche sur n'importe quel outil de l'agent.
Astuce

Les modèles matcher sont sensibles à la casse. Utilisez les noms standard des outils Claude Code : Edit, Write, Bash, Glob, Grep.

4. Linting et formatage automatiques (ESLint + Prettier)

Le scénario quotidien le plus pratique consiste à déléguer le formatage et la vérification initiale du style aux utilitaires Prettier et ESLint. Grâce à cela, le code est toujours sauvegardé dans le dépôt dans un état impeccable.

Configuration PostToolUse pour ESLint et Prettier

json
{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] }, { "matcher": "Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ] } }

Analyse des drapeaux de sécurité dans la commande

  • "$CLAUDE_FILE_PATH" — variable d'environnement dynamique dans laquelle Claude insère automatiquement le chemin complet vers le fichier dès qu'il est modifié par l'agent.
  • 2>/dev/null — supprime les sorties d'erreur inutiles du flux stderr pour ne pas surcharger le terminal.
  • || true — construction bash cruciale. Elle garantit que même si le linter trouve des erreurs irrécupérables et retourne le code 1, le hook lui-même se terminera avec le code 0 et n'arrêtera pas le fonctionnement ultérieur de l'agent.
mermaid
flowchart TD A["Claude викликає Edit"] --> B["Файл збережено на диску"] B --> C["PostToolUse тригер"] C --> D["npx eslint --fix $CLAUDE_FILE_PATH"] D --> E{"Успішно або || true"} E --> F["Агент продовжує вирішувати задачу"]

5. Barrières de sécurité avant git commit (TypeCheck + Tests)

Si nous avons utilisé des hooks doux avec || true pour le formatage, la fixation des modifications dans le système de contrôle de version nécessite un contrôle qualité strict (Quality Gate).

À l'aide de PreToolUse, vous pouvez bloquer la création d'un commit si le projet contient des erreurs de compilation TypeScript ou si les tests unitaires échouent.

Configuration d'un hook Pre-commit bloquant

json
{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm run lint" } ] } ] } }

Ce qui se passe en cas de détection d'erreurs

  1. Claude formule la commande git commit -m "...".
  2. Avant son exécution, le système active PreToolUse.
  3. Les commandes de validation sont lancées : npm run typecheck et npm run lint.
  4. Si une erreur est détectée : le processus retourne un code de sortie non nul (exit code 1).
  5. Claude Code capture la sortie de l'erreur du compilateur directement dans son contexte.
  6. Au lieu d'un commit cassé, l'assistant analyse le texte de l'erreur, corrige automatiquement les types dans le code et effectue une nouvelle tentative propre de commit.
Important

Notez bien : dans les vérifications bloquantes PreToolUse, n'utilisez jamais || true, sinon la vérification sera toujours considérée comme réussie et la barrière de sécurité cessera de fonctionner.

6. Notifications audio et desktop à la fin des tâches (Stop Hook)

Les refactoring complexes ou l'exécution de suites de tests complètes peuvent durer de 2 à 10 minutes. Plutôt que de fixer sans relâche le terminal, configurez des notifications via l'événement Stop.

Astuce

La notification se déclenche uniquement lorsque l'agent termine complètement la génération de la réponse finale, et non entre les appels intermédiaires aux outils.

7. Transmission du contexte via les variables d'environnement

Pour que les scripts d'automatisation soient flexibles et adaptatifs, Claude Code exporte automatiquement les métadonnées de l'opération courante dans les variables d'environnement système (Environment Variables).

Variables d'environnement Claude Code pour les hooks ЗбільшитиVariables d'environnement Claude Code pour les hooksVariables d'environnement Claude Code pour les hooks

Référentiel des variables système Claude Code

Variable d'environnementType de valeurDescription et exemple de contenu
$CLAUDE_FILE_PATHChemin absoluChemin vers le fichier spécifique actuellement créé ou édité (/Users/dev/project/src/index.ts)
$CLAUDE_TOOL_NAMEIdentifiant textuelNom de l'outil qui a initié l'événement (Edit, Write, Bash)
$CLAUDE_PROJECT_DIRChemin absoluRépertoire racine du projet où la session actuelle de Claude Code est lancée

Exemple de script Bash contextuel pour un hook

Créons le script .claude/hooks/smart-validator.sh :

bash
#!/usr/bin/env bash set -e # Перевіряємо, чи існує файл і яке у нього розширення if [[ -f "$CLAUDE_FILE_PATH" ]]; then case "$CLAUDE_FILE_PATH" in *.ts|*.tsx) echo "⚡ Валідація TypeScript файлу: $CLAUDE_FILE_PATH" npx eslint --fix "$CLAUDE_FILE_PATH" || true ;; *.json) echo "🔍 Перевірка валідності JSON..." jq empty "$CLAUDE_FILE_PATH" 2>/dev/null || echo "Помилка формату JSON!" ;; *.md) echo "📝 Оновлено документацію: $(basename "$CLAUDE_FILE_PATH")" ;; esac fi

Désormais, dans .claude/settings.json, il suffit d'indiquer l'appel de ce script :

json
{ "hooks": { "PostToolUse": [ { "matcher": "*", "hooks": [ { "type": "command", "command": "bash .claude/hooks/smart-validator.sh" } ] } ] } }

8. Pattern « CI-in-a-Loop » : feedback continu

Dans le développement traditionnel sans hooks, un pattern de rupture apparaît : l'agent apporte des modifications à une dizaine de fichiers, puis le build du projet se lance et génère une avalanche de 40 erreurs de types. Il est difficile pour l'agent de déterminer quelle modification précise a causé la panne.

CI-in-a-Loop (Court cycle de feedback) inverse ce processus :

mermaid
flowchart TD A["Claude вносить правку в код"] --> B["Миттєвий запуск tsc"] B --> C{"Є помилка?"} C -->|Так| D["Claude бачить 1 точкову помилку"] D --> E["Миттєвий фікс за 5 секунд"] E --> B C -->|Ні| F["Перехід до наступного рядка/файлу"]

Configuration de l'audit cyclique TypeScript

json
{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx tsc --noEmit 2>&1 | head -n 20 || true" } ] } ] } }

Pourquoi utiliser impérativement head -n 20

Si la sortie du compilateur retourne des centaines de lignes de logs, elles entrent dans le contexte du modèle et peuvent saturer la limite de tokens. La limitation via head -n 20 affiche les premières erreurs les plus critiques, offrant au modèle un repère précis pour une correction immédiate sans surcharger la session.

9. Automatisation Headless : mode -p, Cron et Git Hooks

Les hooks peuvent être combinés avec le mode autonome (headless) de Claude Code — le drapeau -p (print/prompt). Cela permet d'automatiser l'exécution des tâches entièrement sans intervention humaine.

mermaid
flowchart LR A["Розклад Cron (02:00)"] --> B["Скрипт nightly-audit.sh"] B --> C["claude -p 'Run test suite, fix bugs, commit'"] C --> D["Хуки PostToolUse контролюють код"] D --> E["Автоматичний Push результату"]

Script autonome d'audit nocturne (nightly-audit.sh)

bash
#!/usr/bin/env bash cd /var/www/my-project # Запуск Claude Code в автономному режимі з фіксованим завданням claude -p "Run full test suite. If any tests fail, inspect the stack trace and fix them. Ensure typecheck passes. Finally, commit all fixes with a conventional commit." >> /var/log/claude-audit.log 2>&1

Configuration de l'horaire d'exécution via Cron

Ouvrez le planificateur de tâches (crontab -e) et configurez l'exécution chaque nuit à 03:00 :

text
0 3 * * * /usr/local/bin/nightly-audit.sh

Lancement de la vérification dans un Git Hook natif (.git/hooks/post-merge)

Pour qu'une analyse de compatibilité se lance automatiquement après chaque récupération de mises à jour via git pull :

bash
#!/usr/bin/env bash # .git/hooks/post-merge echo "🚀 Запуск автоматичної перевірки залежностей через Claude..." claude -p "Check if package.json was updated. If so, run npm install, verify build, and report summary."

N'oubliez pas d'accorder les droits d'exécution au script : chmod +x .git/hooks/post-merge.

10. Meilleures pratiques d'ingénierie et règles de sécurité des Hooks

Des hooks mal configurés peuvent boucler l'exécution ou bloquer le fonctionnement du terminal. Respectez quatre règles fondamentales d'hygiène d'ingénierie.

Quatre règles de conception sécurisée des hooks

  1. Rapidité extrême : Les hooks avec l'événement PostToolUse s'exécutent après chaque modification de fichier. Si un hook prend plus de 1-2 secondes, le travail interactif avec Claude deviendra lent et inconfortable. Lancez les tests E2E lourds uniquement dans PreToolUse avant le commit, mais pas après chaque Edit.

  2. Journalisation obligatoire de la sortie : Redirigez toujours la sortie des scripts de diagnostic vers un fichier log temporaire :

    bash
    "command": "bash .claude/hooks/check.sh >> /tmp/claude-hooks.log 2>&1 || true"

    Si un hook cesse de se déclencher, vous pourrez ouvrir immédiatement /tmp/claude-hooks.log et trouver la cause.

  3. Test isolé dans un terminal propre : Avant d'ajouter une commande à settings.json, exécutez-la vous-même dans un shell standard. Si la commande produit une erreur dans la console, elle cassera garantitivement la session Claude Code.

  4. Prévention de la récursion infinie : Ne configurez jamais une commande dans PostToolUse qui modifie elle-même les fichiers du projet sans drapeaux d'ignorance (par exemple, un script tiers qui appelle un Edit répétitif), sinon l'agent entrera dans une boucle d'appels éternelle.

Avertissement

Ne lancez pas via les hooks des commandes qui attendent une saisie interactive de l'utilisateur (par exemple, confirmation read -p ou sudo avec demande de mot de passe). Cela entraînera le gel du processus terminal.

11. Atelier pratique, mémo et checklist de synthèse

Pour démarrer rapidement dans votre propre projet, utilisez un mémo synthétique prêt à l'emploi et une configuration production éprouvée.

Mémo pour choisir le type de Hook pour l'automatisation ЗбільшитиMémo pour choisir le type de Hook pour l'automatisationMémo pour choisir le type de Hook pour l'automatisation

Fichier de configuration prêt à l'emploi .claude/settings.json

Copiez cette configuration étalon dans le dossier .claude de votre projet :

json
{ "hooks": { "PreToolUse": [ { "matcher": "Bash(git commit*)", "hooks": [ { "type": "command", "command": "npm run typecheck && npm test" } ] } ], "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] }, { "matcher": "Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "osascript -e 'display notification \"Роботу завершено!\" with title \"Claude Code\"' 2>/dev/null || true" } ] } ] } }

Auto-vérification rapide

Astuce

1. En quoi PreToolUse diffère-t-il fondamentalement de PostToolUse ?

Réponse : PreToolUse se lance avant l'exécution de l'action de l'outil et peut la bloquer en cas d'exit code non nul. PostToolUse se lance après la fin réussie de l'opération et est utilisé pour le formatage ou le linting.

Astuce

2. Pourquoi ajoute-t-on || true dans les hooks de formatage ?

Réponse : Pour éviter que les erreurs du linter ou du formateur ne retournent un statut critique et n'arrêtent le processus de génération de la réponse de l'agent.

Astuce

3. Quelle variable d'environnement contient le chemin vers le fichier venant d'être édité ?

Réponse : La variable $CLAUDE_FILE_PATH.

Checklist de synthèse pour l'implémentation des Hooks

  • Le répertoire .claude/ et le fichier settings.json ont été créés à la racine du projet.
  • Le formatage automatique des fichiers modifiés est configuré via PostToolUse + Prettier.
  • Les barrières de sécurité avant commit (PreToolUse) sont en place avec TypeCheck et Tests.
  • Les notifications Stop sont configurées pour les longues sessions.
  • Les scripts utilisent correctement les variables d'environnement ($CLAUDE_FILE_PATH).
  • Les logs sont activés pour le débogage des hooks.
Ce guide est entièrement gratuit. S'il vous a fait gagner une soirée, vous pouvez soutenir la croissance du projet.
Soutenir l'auteur