Automatisation des workflows avec Claude Code : Hooks

1. Le système d'événements : Comment fonctionnent les hooks

Les hooks sont des scripts qui s'exécutent automatiquement lorsque des événements spécifiques se produisent dans Claude Code. Pensez-les comme des hooks git, mais pour votre assistant IA.

Événements disponibles

Le flux d'événements

Voici comment les événements circulent lors d'une interaction typique :

Visualiseur interactif du flux de hooks

Explorez le fonctionnement des hooks avec ce diagramme de flux interactif. Cliquez sur chaque type de hook pour voir des exemples de code en Bash et PowerShell :

Les hooks, c'est le moment où Claude Code cesse d'être un outil de chat pour devenir de l'infrastructure réelle, et le retour de la communauté reflète ce basculement. Sur r/devops et r/ClaudeAI, les prises de position enthousiastes du début (« j'ai automatisé tout mon workflow ! ») sont maintenant tempérées par les prises plus sobres qui suivent (« j'ai passé un week-end à déboguer pourquoi mon pre-commit se déclenche deux fois »). Les deux sont vraies. Les hooks déverrouillent des garde-fous déterministes autour d'un agent non déterministe — exactement la combinaison nécessaire pour la confiance — mais chaque hook ajouté est un nouveau mode d'échec à porter.

Ce qui vaut la peine d'être automatisé, d'après ce que les praticiens gardent réellement : les garde-fous de sécurité (bloquer les écritures sur main, imposer les conventional commits, empêcher la lecture de .env), le formatage et le linting en PreToolUse, et une notification sur les sessions longues. Ce qui ne vaut pas encore la peine : tout ce qui modifie un état de façon irréversible sur la base d'une décision du modèle. La référence hooks d'Anthropic est claire : les hooks tournent avec vos permissions locales — donc un hook qui déraille peut causer de vrais dégâts à vraie vitesse.

Règle opérationnelle honnête : chaque hook commence sa vie comme un script que vous pouvez lancer en standalone. S'il ne marche pas indépendamment, il ne marchera pas sous Claude Code — vous aurez juste plus de mal à le déboguer parce que l'échec sera emmêlé avec la sortie de l'agent. Testez en isolation, intégrez prudemment, et versionnez vos scripts de hooks à côté du code qu'ils protègent.

2. Créer votre premier hook

Les hooks sont enregistrés dans votre fichier de paramètres et pointent vers des scripts shell.

Enregistrement des hooks

Ajoutez les hooks dans .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/security-check.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Champs de configuration

Entrée et sortie des hooks

Votre hook reçoit du JSON sur stdin :

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules"
  },
  "session_id": "abc123",
  "cwd": "/my-project"
}

Votre hook peut produire du JSON en retour :

{
  "systemMessage": "Auto-formatted 3 files",
  "hookSpecificOutput": {
    "additionalContext": "Current branch: feature/auth"
  }
}

Codes de sortie

3. Hooks synchrones vs asynchrones

Claude Code prend en charge deux modèles d'exécution pour les hooks :

Synchrone (par défaut)

• →Claude attend la fin du hook
• →Le hook peut fournir un retour via stdout
• →Le code de sortie 2 peut bloquer les opérations
• →À utiliser pour : Validation de sécurité, vérification de types

Asynchrone

• →Claude continue immédiatement
• →Le hook s'exécute en arrière-plan
• →Ne peut pas bloquer les opérations ni fournir de retour
• →À utiliser pour : Journalisation, notifications, formatage

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/auto-format.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

4. Exemples de hooks essentiels

Bloqueur de sécurité (PreToolUse)

Bloquez les commandes dangereuses avant leur exécution :

#!/bin/bash
# .claude/hooks/security-blocker.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

# Dangerous patterns to block
DANGEROUS=(
    "rm -rf /"
    "rm -rf ~"
    "rm -rf *"
    "sudo rm"
    "git push --force origin main"
    "git push -f origin main"
    "> /dev/sda"
)

for pattern in "${DANGEROUS[@]}"; do
    if [[ "$COMMAND" == *"$pattern"* ]]; then
        echo "BLOCKED: Dangerous command: $pattern" >&2
        exit 2  # Exit code 2 = BLOCK
    fi
done

exit 0  # Allow the command

Formateur automatique (PostToolUse)

Formater automatiquement le code après chaque édition :

#!/bin/bash
# .claude/hooks/auto-format.sh

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')

# Only run for Edit/Write
if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then
    exit 0
fi

# Format based on file type
if [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx|json|css)$ ]]; then
    npx prettier --write "$FILE_PATH" 2>/dev/null
elif [[ "$FILE_PATH" =~ \.py$ ]]; then
    black "$FILE_PATH" 2>/dev/null
fi

exit 0

Injecteur de contexte Git (UserPromptSubmit)

Ajouter automatiquement le contexte git à chaque prompt :

#!/bin/bash
# .claude/hooks/git-context.sh

BRANCH=$(git branch --show-current 2>/dev/null || echo "not a git repo")
STAGED=$(git diff --cached --stat 2>/dev/null | tail -1 || echo "none")
UNSTAGED=$(git diff --stat 2>/dev/null | tail -1 || echo "none")

cat << EOF
{
  "hookSpecificOutput": {
    "additionalContext": "[Git] Branch: $BRANCH | Staged: $STAGED | Unstaged: $UNSTAGED"
  }
}
EOF

exit 0

5. Commandes slash personnalisées

Les commandes sont des fichiers Markdown qui définissent des workflows réutilisables. Ce sont des macros pour Claude Code.

Structure des commandes

Les commandes vivent dans .claude/commands/ :

.claude/commands/
├── tech/
│   ├── commit.md      → /tech:commit
│   └── pr.md          → /tech:pr
├── product/
│   └── scope.md       → /product:scope
└── debug/
    └── trace.md       → /debug:trace

Modèle de commande

# Command Name

## Purpose
[Ce que fait cette commande]

## Process

1. **Étape 1**
   [Instructions]

2. **Étape 2**
   [Instructions]

## Arguments
If $ARGUMENTS[0] provided: [utiliser comme X]
If no arguments: [comportement par défaut]

## Output Format
[Structure attendue]

Exemple : Commande de commit

# Smart Commit

## Purpose
Create a well-formatted git commit following Conventional Commits.

## Process

1. **Check Status**
   Run `git status` and `git diff` to understand changes.

2. **Determine Type**
   - `feat`: New feature
   - `fix`: Bug fix
   - `refactor`: Code restructuring
   - `docs`: Documentation
   - `test`: Test changes

3. **Draft Message**
   Format: `type(scope): description`
   
4. **Stage and Commit**
   ```bash
   git add [relevant files]
   git commit -m "[message]"

Arguments

If $ARGUMENTS[0] provided: Use as commit message hint Example: /tech:commit add user auth

Output

Commit: [hash] [message] Files: [number] changed

### Exemple : Commande de cadrage de problème

```markdown
# Problem Framer

## Purpose
Challenge and refine problem definitions before solution design.

## Process

1. **Capture Initial Problem**
   Record the problem as stated.

2. **5 Whys Analysis**
   Ask "Why?" 5 times to find root cause:
   - Why 1: [First answer]
   - Why 2: [Deeper]
   - Why 3: [Deeper still]
   - Why 4: [Getting to root]
   - Why 5: [Root cause]

3. **Stakeholder Analysis**
   - Who is affected?
   - Who decides?
   - Who benefits?

4. **Reframe**
   Write: "How might we [action] for [user] so that [outcome]?"

## Output
**Original**: [as stated]
**Root Cause**: [from 5 Whys]
**Refined**: "How might we [X] for [Y] so that [Z]?"

6. Scripts shell vs agents IA

Tout n'a pas besoin d'IA. Choisissez le bon outil pour la tâche :

La règle d'or

Si vous pouvez écrire une regex ou une condition simple pour le faire, utilisez un script shell. Si cela nécessite de la « compréhension » ou du « jugement », utilisez l'IA.

Exemple : Workflow de PR

# DÉTERMINISTE (script shell) : créer la branche, pusher, ouvrir la PR
git checkout -b feature/user-auth
git push -u origin feature/user-auth
gh pr create --title "Add user auth" --body "..."

# INTERPRÉTATION (agent IA) : vérifier la qualité du code
# → Utilisez les capacités de revue de code de Claude

7. Construire un workflow complet

Construisons un workflow prêt pour la production qui combine hooks, commandes et scripts.

Le workflow de développement

Configuration complète

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": ".*",
        "hooks": [{
          "type": "command",
          "command": ".claude/hooks/session-init.sh"
        }]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": ".*",
        "hooks": [{
          "type": "command",
          "command": ".claude/hooks/git-context.sh"
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": ".claude/hooks/security-blocker.sh",
          "timeout": 5000
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": ".claude/hooks/auto-format.sh",
          "async": true
        }]
      }
    ],
    "SessionEnd": [
      {
        "matcher": ".*",
        "hooks": [{
          "type": "command",
          "command": ".claude/hooks/session-handoff.sh"
        }]
      }
    ]
  }
}

8. Bonnes pratiques

Conseils de développement de hooks

1. →Commencez simple : Débutez avec un seul hook (comme le bloqueur de sécurité) avant de construire un pipeline complet
2. →Testez hors-ligne : Exécutez vos scripts manuellement avant de les enregistrer comme hooks
3. →Utilisez jq : Parsez l'entrée JSON de manière fiable avec jq
4. →Journalisez tout : Ajoutez de la journalisation pour déboguer le comportement des hooks
5. →Définissez des timeouts : Empêchez les hooks bloqués de bloquer Claude

Pièges courants

9. Avancé : Hook de handoff de session

Voici un hook de handoff de session complet qui capture votre travail :

#!/bin/bash
# .claude/hooks/session-handoff.sh

# Create handoff directory
mkdir -p claudedocs/handoffs

# Get session info
DATE=$(date +%Y-%m-%d)
TIME=$(date +%H:%M)
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")

# Get recent commits
COMMITS=$(git log --oneline -5 2>/dev/null || echo "No commits")

# Get changed files
CHANGED=$(git diff --name-only HEAD~5..HEAD 2>/dev/null || echo "No changes tracked")

# Create handoff file
cat > "claudedocs/handoffs/handoff-$DATE.md" << EOF
# Session Handoff - $DATE $TIME

## Branch
$BRANCH

## Recent Commits
$COMMITS

## Files Changed
$CHANGED

## Next Steps
[To be filled by Claude or user]

## Notes
[Session-specific notes]
EOF

echo "Created handoff: claudedocs/handoffs/handoff-$DATE.md"
exit 0

Résumé

Vous disposez maintenant des outils pour automatiser Claude Code comme un utilisateur avancé :

Checklist de démarrage rapide

• → Créer le répertoire .claude/hooks/
• → Ajouter un hook bloqueur de sécurité (PreToolUse)
• → Ajouter un hook formateur automatique (PostToolUse, async)
• → Créer votre première commande personnalisée
• → Tester avec une vraie tâche de développement

Continuez vers le Module 2 pour des exercices pratiques de construction de workflows d'automatisation en production.