Subagents Claude Code : isolation du contexte, orchestrateur, reviewer et exécution en parallèle

Que sont les subagents de Claude Code

Un subagent est une nouvelle instance de l'agent, lancée par l'agent principal pour une tâche distincte. Il dispose de sa propre fenêtre de contexte, de son propre prompt système et de sa propre liste d'outils autorisés. L'agent principal lui transmet la description de la tâche, le subagent travaille de façon autonome — il lit des fichiers, lance des commandes — et ne renvoie que le message final.

Le mot clé ici est isolation. Tout ce que le subagent a lu en chemin — des dizaines de fichiers, une longue sortie de tests, des hypothèses sans issue — reste dans son contexte et n'entre pas dans celui de la session principale. L'agent principal ne voit qu'un résultat court : « l'erreur est dans la fonction X, la cause est telle, voici trois endroits concernés ».

Les subagents de Claude Code sont un cas particulier de l'idée plus générale des systèmes multi-agents : au lieu d'une seule boucle « réfléchir — agir — vérifier », on obtient un graphe de plusieurs nœuds, chacun avec son rôle et sa responsabilité.

Pourquoi isoler le contexte

La fenêtre de contexte est la principale ressource de l'agent. Y coexistent les instructions de CLAUDE.md, l'historique du dialogue, le code lu et la sortie des commandes. Quand l'agent passe une demi-heure à chercher la cause d'un bogue, le contexte se remplit de déchets : des fichiers qui n'ont finalement rien à voir, et des journaux dont une seule ligne compte.

Les conséquences sont connues de tous ceux qui travaillent longtemps avec des agents : le modèle respecte moins bien les règles du projet, confond les détails, et lors de la compression automatique de l'historique il perd ce qui comptait. Le subagent règle le problème structurellement : le travail sale se fait dans un contexte séparé, jeté après la réponse.

• Recherche et exploration. « Trouve tous les endroits où la fonction de paiement est appelée et décris leur fonctionnement » — une tâche typique pour un subagent.
• Vérifications bruyantes. Lancer les tests et analyser les échecs : confier cela à un subagent et recevoir la liste des causes.
• Lecture de gros documents. Une spécification de plusieurs centaines de pages ne sert que pour quelques faits : laissez le subagent les extraire.

Configurer un subagent : le dossier .claude/agents

Un subagent personnalisé se décrit par un fichier Markdown avec un en-tête YAML. Les fichiers du projet se trouvent dans .claude/agents/ du dépôt et sont disponibles pour toute l'équipe via git ; les fichiers personnels vont dans ~/.claude/agents/ et fonctionnent dans tous vos projets. On peut aussi créer et modifier un subagent de façon interactive, avec la commande /agents de Claude Code.

---
name: code-reviewer
description: Vérifie les modifications de code pour détecter les erreurs et les écarts aux règles du projet. À utiliser après la fin d'une tâche, avant le commit.
tools: Read, Grep, Glob, Bash
---
Tu es un relecteur de code. Tu n'as rien à corriger.

1. Regarde les modifications : git diff.
2. Vérifie chaque modification : erreurs de logique, gestion des erreurs,
   sécurité (SQL, échappement des sorties, secrets).
3. Compare avec les règles de AGENTS.md.
4. Renvoie la liste des remarques : fichier, ligne, problème, pourquoi c'est important.
   S'il n'y a aucune remarque, écris-le simplement.

Signification des champs :

Le corps du fichier est le prompt système du subagent. Il ne voit pas l'historique de votre dialogue : tout ce qu'il doit savoir sur son rôle et le format de sa réponse doit figurer dans le prompt ou dans la tâche transmise par l'agent principal.

Comment appeler un subagent

L'agent principal peut choisir lui-même un subagent si la tâche correspond à sa description. Il est plus sûr de le demander explicitement : « Utilise le subagent code-reviewer pour vérifier les modifications ». Des formulations comme « utilise-le de manière proactive » dans la description augmentent les chances qu'il soit appelé sans rappel, mais ne le garantissent pas.

Subagent explorateur

Un second fichier qui vaut la peine d'être créé dans presque tout projet : l'explorateur en lecture seule. Il répond aux questions sur le code et ne modifie rien.

---
name: explorer
description: Cherche dans la base de code les réponses à des questions sur l'emplacement et le fonctionnement de quelque chose. À utiliser quand il faut lire beaucoup de fichiers pour une réponse courte.
tools: Read, Grep, Glob
---
Tu explores le code et ne modifies rien.
Renvoie : une réponse courte à la question, la liste des fichiers avec les lignes
sur lesquelles elle repose, et ce qui n'a pas pu être vérifié.

Ce subagent est particulièrement utile au début d'une tâche : l'agent principal obtient une carte des endroits pertinents sans avoir consommé son contexte à tout lire, et il travaille ensuite sur des fichiers précis.

Schéma « orchestrateur et exécutants »

Le schéma multi-agents le plus répandu : un agent orchestrateur tient le plan et la vue d'ensemble, et confie les étapes concrètes à des exécutants. L'orchestrateur ne lit pas tout le code lui-même : il formule les tâches, reçoit les résultats et décide de la suite.

1. L'orchestrateur découpe la tâche en parties indépendantes et rédige pour chacune une consigne autonome : but, où chercher, ce qui est considéré comme terminé, sous quelle forme renvoyer la réponse.
2. Les exécutants réalisent les consignes dans leurs propres contextes.
3. L'orchestrateur rassemble les réponses, vérifie que les parties s'emboîtent, et lance l'étape suivante ou revient à l'étape précédente.

La faiblesse du schéma est la transmission de la tâche. Le subagent ne connaît que ce qu'on lui a écrit. La consigne « corrige le bogue dont on a parlé » ne lui dit rien : il n'a pas vu la discussion. Une bonne consigne se lit comme une tâche pour un nouveau collègue qui ouvre le dépôt pour la première fois.

Ce que doit renvoyer l'exécutant

Fixez le format de la réponse à l'avance : liste des fichiers, sortie, causes trouvées, ce qui n'a pas pu être vérifié. Une réponse courte et structurée économise le contexte de l'orchestrateur, et la rubrique « ce qui n'est pas vérifié » protège contre la fausse assurance : l'exécutant, comme tout agent, a tendance à rapporter un succès.

Relecteur séparé : pourquoi distinguer le juge de l'exécutant

Quand le même agent écrit le code et le vérifie lui-même, le juge et l'accusé partagent la même tête. L'agent se souvient de ce qu'il voulait faire et voit dans le code son intention, et non ce qui y est écrit. Il a en outre intérêt à finir : la vérification devient une formalité.

Un relecteur dans un contexte séparé échappe à ces problèmes. Il ne connaît pas l'historique des décisions, il ne voit que le diff et les règles du projet, et il évalue le résultat avec un regard neuf. C'est le même principe que dans une équipe vivante : l'auteur ne valide pas sa propre pull request.

• Ne donnez au relecteur que les outils de lecture et de lancement des vérifications, sans droit d'écriture. Il ne se mettra pas alors à « corriger discrètement » au lieu de signaler le problème.
• Décrivez explicitement les critères de vérification : ce qui est considéré comme une erreur, quelles règles du projet sont obligatoires.
• La décision sur les remarques revient à l'orchestrateur ou à l'humain. Le relecteur constate, l'exécutant corrige.

Le relecteur ne remplace pas les vérifications mécaniques. Les tests, le linter et la vérification des types sont des nœuds déterministes, plus fiables que n'importe quel modèle. Le relecteur attrape ce que la mécanique ne voit pas : une logique incorrecte, la violation d'accords, une complexité inutile.

Lancement parallèle de subagents

Claude Code peut lancer plusieurs subagents en même temps. Cela accélère le travail quand les parties de la tâche sont vraiment indépendantes : étudier trois modules, vérifier les modifications sous trois angles (sécurité, performance, tests), rassembler des informations depuis plusieurs sources.

Le parallélisme fonctionne bien en lecture et mal en écriture. Si deux exécutants modifient en même temps les mêmes fichiers, ils s'écrasent mutuellement leurs changements, et aucun ne le remarque. Dans les termes du graphe d'agents, c'est un état partagé sans règle de fusion. Règles pratiques :

• En parallèle : exploration, analyse, relecture. En séquence : les modifications des mêmes fichiers.
• Si les exécutants écrivent tout de même en parallèle, séparez les zones : chacun ne travaille que dans ses fichiers, ou dans sa propre copie du dépôt (par exemple dans un git worktree séparé).
• Les résultats sont réunis par un seul nœud, l'orchestrateur, et non par les exécutants entre eux.

Quand les subagents ne sont pas nécessaires

Un schéma multi-agents a un coût : plus de tokens, plus de temps, plus d'endroits où l'information se perd lors des transmissions. Les subagents de Claude Code ne sont pas toujours rentables.

Avant de construire un graphe d'agents, répondez à quelques questions simples : qui est responsable du but commun, qui peut opposer un veto et annuler une modification, quelles métriques définissent le succès. Sans réponses, plusieurs agents ne feront que multiplier la confusion d'un seul.

Erreurs typiques avec les subagents

Description floue

La description « assistant pour le code » ne permet pas à l'agent principal de savoir quand l'appeler. Écrivez le déclencheur : « après des modifications dans le dossier api/, avant le commit ».

Consigne sans contexte

Le subagent reçoit une tâche sans chemins, sans critères de fin et sans contraintes, et passe la moitié de son travail à deviner ce qu'on attend de lui. On y remédie avec un modèle de consigne : but, données d'entrée, contraintes, format de la réponse.

Droits trop larges

L'explorateur et le relecteur n'ont pas besoin du droit de modifier des fichiers. La restriction tools est un moyen peu coûteux de faire d'un rôle un mécanisme, et non une simple demande dans le prompt.

Confiance dans le rapport sans vérification

« Tous les tests sont passés » dans la réponse d'un subagent est une affirmation, pas un fait. L'orchestrateur doit s'appuyer sur ce qui est vérifiable : la sortie d'une commande, le code de retour, des lignes précises.

En résumé

Les subagents de Claude Code servent à trois choses : garder le contexte principal propre, séparer la vérification de l'exécution et paralléliser un travail indépendant. On les décrit par de courts fichiers Markdown dans .claude/agents/, et leur qualité dépend presque entièrement de la description du rôle, de la liste des outils et du caractère autosuffisant de la consigne. Quand la tâche est petite ou très liée au dialogue, un seul agent reste préférable. Le passage d'un cycle unique à un système de nœuds, d'arêtes et d'état partagé est présenté en pratique dans le cours.