Introduction

Lorsque vous travaillez avec Claude Code sur des projets réels, vous réaliserez rapidement qu'un agent unique qui s'exécute séquentiellement ne suffit pas pour gérer des tâches complexes. Cette leçon se concentre sur deux mécanismes avancés : les hooks, qui vous permettent d'intervenir dans le comportement de l'agent avant et après chaque opération, et les subagents, qui vous permettent de répartir le travail en plusieurs flux de traitement parallèles.

Bien comprendre et appliquer ces deux mécanismes, c'est ce qui distingue un workflow automatisé basique d'un système qui peut réellement passer à l'échelle.

Hooks : contrôler le comportement avant et après une opération

Les hooks dans Claude Code sont des fonctions de rappel (callback) enregistrées pour s'exécuter à des points précis du cycle de vie d'un appel d'outil. Il existe deux types principaux : PreToolUse, qui s'exécute avant que l'outil ne soit lancé, et PostToolUse, qui s'exécute après que l'outil a terminé.

La configuration des hooks est déclarée dans le fichier de configuration, généralement .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash /scripts/validate_command.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash /scripts/run_linter.sh"
          }
        ]
      }
    ]
  }
}

Le champ matcher spécifie à quel outil ce hook s'applique. Vous pouvez utiliser un nom d'outil précis tel que Bash, Write ou Edit, ou utiliser un wildcard pour intercepter tous les outils.

Lorsqu'un script de hook s'exécute, Claude Code transmet les informations concernant l'appel d'outil via stdin au format JSON. Votre script peut lire ces données pour prendre des décisions. Le code de sortie détermine ce qui se passe ensuite : exit 0 signifie que l'opération est autorisée à continuer, tandis qu'exit 2 bloque l'opération et renvoie un message d'erreur à l'agent.

Voici un exemple d'un simple script validate utilisé comme hook PreToolUse sur l'outil Bash, empêchant l'agent de supprimer des fichiers en dehors du répertoire du projet :

#!/bin/bash
input=$(cat)
command=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))")

if echo "$command" | grep -qE 'rm -rf /|sudo rm'; then
  echo "Blocked: lệnh xóa nguy hiểm bị từ chối" >&2
  exit 2
fi

exit 0

Les hooks PostToolUse sont utiles pour des tâches telles que lancer automatiquement un linter après chaque écriture de fichier par l'agent, enregistrer les résultats dans un fichier d'audit, ou envoyer une notification lorsque l'agent termine un groupe d'opérations.

Subagents : traiter des tâches complexes en parallèle

Un subagent est un mécanisme par lequel l'agent principal (l'orchestrateur) crée et coordonne des agents enfants indépendants. Chaque subagent dispose de son propre contexte, de ses propres accès aux outils, et peut s'exécuter en concurrence avec d'autres subagents.

Dans Claude Code, vous activez un subagent en utilisant l'outil Task dans le prompt de l'orchestrateur. L'orchestrateur décrit la tâche, et le système crée un agent enfant avec un contexte séparé pour l'exécuter :

claude -p "Hãy phân tích codebase này bằng cách:
1. Dùng Task tool để tạo subagent A: quét toàn bộ file .py và liệt kê các function chưa có docstring
2. Dùng Task tool để tạo subagent B: kiểm tra tất cả file config và báo cáo các key bị thiếu so với .env.example
3. Tổng hợp kết quả từ cả hai và tạo báo cáo audit.md"

Les subagents A et B s'exécutent en parallèle, puis l'orchestrateur attend les résultats des deux avant de les synthétiser. Cela fait gagner un temps significatif par rapport à une exécution séquentielle des tâches.

Un point important : chaque subagent consomme sa propre fenêtre de contexte, il faut donc concevoir la tâche de chaque subagent de manière spécifique et autonome. Évitez les situations où un subagent doit effectuer plusieurs allers-retours avec l'orchestrateur — cela annule l'avantage de la parallélisation.

Vous pouvez combiner les hooks avec les subagents : les hooks s'appliquent à la fois à l'agent principal et aux subagents, ce qui vous permet d'imposer des politiques de contrôle cohérentes dans l'ensemble du système, quel que soit le nombre d'agents enfants en cours d'exécution.

Erreurs courantes

L'erreur la plus fréquente lors de l'utilisation des hooks est un script qui se termine avec un mauvais code de sortie, entraînant le blocage de l'agent alors qu'il ne le devrait pas, ou l'absence de blocage alors qu'il le devrait. Testez toujours les scripts de hook indépendamment avant de les intégrer, en envoyant un payload JSON d'exemple via un pipe dans le script et en vérifiant le code de sortie retourné.

Avec les subagents, une erreur fréquente consiste à confier à deux subagents exécutés en parallèle des tâches trop vagues ou mutuellement dépendantes. Par exemple, si le subagent B doit lire un fichier créé par le subagent A, ces deux tâches ne peuvent pas s'exécuter en parallèle — l'orchestrateur doit terminer A avant de lancer B.

Une autre erreur est de ne pas gérer le cas où un subagent échoue. L'orchestrateur a besoin d'instructions claires sur ce qu'il doit faire lorsqu'une tâche enfant signale une erreur, plutôt que de l'ignorer silencieusement et de continuer à synthétiser des résultats incomplets.

Résumé

Les hooks vous offrent un contrôle fin sur le comportement de l'agent à chaque étape, depuis la validation des commandes dangereuses jusqu'à l'automatisation du QA après chaque opération. Les subagents débloquent des capacités de traitement parallèle, idéales lorsqu'une tâche peut être découpée en parties indépendantes. En combinant les deux, vous pouvez construire des pipelines d'automatisation à la fois sûrs et efficaces pour des projets réels à l'échelle de la production.