Subagents : sous-traitez le travail, ne portez pas tout sur vos épaules

📚 Navigation de la série : L'article précédent 22 MCP vous a appris à connecter Claude à des outils externes pour lui permettre de requêter des bases de données et de se connecter à GitHub. Cet article propose une autre approche — non pas lui « ajouter des outils », mais lui apprendre à sous-traiter le travail : un subagent, un assistant spécialisé avec un contexte indépendant, des permissions indépendantes et un rôle indépendant, qui ne renvoie que la conclusion une fois le travail terminé.

Tout le monde dit que les subagents sont puissants et représentent la « méthode avancée » de Claude Code. Beaucoup de gens s'enthousiasment lorsqu'ils découvrent cette fonctionnalité, voulant diviser une tâche en temps de latence ou plusieurs subagents en même temps, pensant que c'est « plus professionnel et plus efficace ».

Mais pour être honnête : la plupart des gens qui divisent les tâches dès le début font fausse route.

C'est une chose que l'on ne comprend qu'après avoir utilisé l'outil pendant un certain temps. Nous expliquerons pourquoi en détail plus tard — mais voici d'abord la conclusion : les subagents ne doivent pas être utilisés simplement « parce qu'il y a beaucoup de tâches ». C'est un outil avec des scénarios d'application bien précis. Utilisé correctement, il vous simplifie la vie ; mal utilisé, il s'avère lent et coûteux. Savoir « s'il faut diviser la tâche » est beaucoup plus important que de savoir « comment la diviser ».

Dans cet article, je vais non seulement vous apprendre à créer et à déclencher des subagents, mais surtout vous aider à définir cette ligne de démarcation : quand sous-traiter, et quand faire le travail soi-même plus rapidement.

À la fin de cet article, vous aurez compris :

• Ce qu'est réellement un subagent — contexte indépendant, outils indépendants, rôle indépendant, résumé en une phrase de la différence avec la conversation principale.
• Les trois problèmes qu'il résout réellement (isolation du contexte, tâches spécialisées, parallélisation), ainsi que le piège contre-intuitif : quand il ne faut pas diviser la tâche.
• Comment créer un subagent de manière interactive avec /agents, ou en écrivant manuellement un fichier de configuration .claude/agents/name.md (avec l'explication de chaque champ).
• Les deux façons de les déclencher : délégation automatique basée sur la description ou appel direct.
• Un atelier pratique avec des étapes à suivre et le résultat attendu : créer votre premier petit subagent et le faire travailler.

---

01 Comprendre d'abord : qu'est-ce qu'un subagent au juste ?

Commençons par la conclusion : un subagent est un assistant spécialisé temporairement embauché par Claude — il travaille dans sa propre pièce, et ne vous renvoie que la conclusion une fois terminé. Toute la documentation qu'il consulte en cours de route n'encombre pas votre bureau.

Analogie : sous-traiter un travail à un assistant spécialisé. Vous avez beaucoup de choses à faire, et parmi elles, une tâche fastidieuse qui prend de la place comme « parcourir mille lignes de logs pour trouver celles qui contiennent des erreurs ». Vous ne voulez pas étaler ce travail sur votre bureau principal, car cela l'encombrerait. Vous le confiez donc à un assistant spécialisé dans ce domaine : il travaille dans sa propre pièce, sur son propre bureau, et parcourt les mille lignes de logs. Une fois terminé, il ne vous rapporte pas les mille lignes de logs brutes, mais vous tend un simple papier : « Il n'y a que ces trois lignes d'erreur, respectivement aux lignes 207, 589 et 903 ». Votre bureau reste parfaitement propre.

Cet assistant dispose de trois éléments qui lui sont « propres » et qui sont complètement isolés de vous (la conversation principale). La documentation officielle le formule de manière très stricte, ce qui vaut la peine d'être retenu :

Chaque subagent s'exécute dans sa propre fenêtre de contexte (context window), avec des invites système personnalisées, des droits d'accès aux outils spécifiques et des permissions indépendantes.

Voici ce que signifient ces trois aspects « indépendants » :

Dimension	Conversation principale (Vous)	Subagent (L'assistant externe)
Contexte	Tout l'historique de votre discussion avec Claude	Une page blanche, qui ne reçoit qu'une « consigne de tâche » sans voir ce dont vous avez parlé auparavant
Invite système (Rôle)	La configuration de Claude Code par défaut	Le rôle spécifique que vous lui écrivez, par exemple « Tu es un relecteur de code extrêmement pointilleux »
Outils / Permissions	Tous les outils que vous avez autorisés	Possibilité de restreindre spécifiquement, par exemple « Lecture seule uniquement, interdiction d'écrire »

Le point le plus crucial, et le plus souvent négligé, est la première ligne : le subagent commence avec une page blanche. La documentation officielle le dit directement — il « ne peut pas voir l'historique de votre conversation, les compétences que vous avez déjà appelées ou les fichiers que Claude a déjà lus ». Claude lui rédige une « consigne de tâche », et il commence à travailler à partir de cette phrase.

Ce point détermine ce pour quoi le subagent is « doué ou non », ce qui nous servira de critère de décision dans la section suivante.

💡 En résumé : Subagent = assistant externe avec contexte indépendant + rôle indépendant + outils indépendants, travaillant dans sa propre pièce et ne renvoyant que la conclusion ; n'oubliez pas qu'il commence avec une page blanche et ne voit pas vos conversations précédentes.

---

02 Quels problèmes résout-il — et le piège contre-intuitif

Maintenant que nous savons « ce que c'est », comprenons « pourquoi il existe ». Les subagents résolvent réellement trois problèmes, que je vais détailler un par un. Avec le troisième point, j'en profiterai pour aborder le piège contre-intuitif mentionné au début.

Problème 1 : Isoler le contexte pour ne pas polluer le fil principal

C'est l'utilisation la plus essentielle et la plus précieuse des subagents.

Le contexte — le « plan de travail » de Claude — est limité. Plus vous discutez longtemps avec lui et plus vous lisez de fichiers, plus le plan de travail s'encombre. Une fois plein, Claude commence à oublier des choses et devient moins performant. Certaines tâches consomment énormément d'espace de travail, alors que vous ne regarderez plus jamais les données intermédiaires produites.

Par exemple, « exécuter toute la suite de tests et me dire lesquels ont échoué ». L'exécution des tests peut générer des centaines ou des milliers de lignes de sortie, mais ce que vous voulez vraiment, c'est juste une phrase : « Ces trois tests ont échoué, avec l'erreur XXX ». Si vous lancez cela directement dans la conversation principale, ces centaines de lignes vont encombrer tout votre espace de travail.

Dans ce cas, sous-traitez la tâche à un subagent : il gère ces centaines de lignes dans sa propre pièce et ne renvoie que la phrase « quels tests ont échoué ». Votre plan de travail de la conversation principale reste aussi propre qu'au début. La documentation officielle classe cet usage parmi les « utilisations les plus efficaces » des subagents :

L'exécution de tests, la récupération de documentation ou le traitement de fichiers de logs peuvent consommer beaucoup de contexte. En déléguant ces tâches à un subagent, la sortie détaillée reste dans le contexte du subagent, tandis que seul le résumé pertinent est renvoyé à votre conversation principale.

Scénario réel : Lors de l'intégration d'un SDK tiers, vous devez faire des appels curl répétés sur son API pour voir les retours, ce qui affiche à chaque fois un écran entier de JSON. Après une dizaine de tours de discussion, la conversation principale est tellement encombrée de JSON qu'elle commence à oublier la demande initiale. Changez de méthode — laissez un subagent s'occuper spécifiquement de « tester cet appel d'interface et me dire simplement à quoi ressemblent les champs ». La conversation principale redevient instantanément claire, et vous ne perdez pas le fil de vos idées.

Problème 2 : Spécialisation dans un type de tâche

Deuxième usage : définir un « spécialiste » pour un travail récurrent.

Si vous vous retrouvez à répéter souvent la même instruction — comme demander à Claude après chaque modification de code d'« analyser le code du point de vue d'un relecteur senior, en se concentrant sur la sécurité et le nommage » — il est préférable de figer cette instruction sous forme de subagent nommé code-reviewer, que vous pourrez appeler d'une seule commande par la suite. La documentation officielle le dit ainsi : « Lorsque vous générez constamment le même type de travailleur et utilisez les mêmes instructions, définissez un subagent personnalisé. »

Sa « spécialisation » repose sur deux éléments : un rôle dédié (défini dans l'invite système sous la forme « Tu es un relecteur de code extrêmement pointilleux ») et des outils dédiés (un relecteur ne devrait faire que lire sans écrire, vous pouvez donc supprimer les outils Write et Edit pour qu'il ne puisse pas modifier le code même s'il le voulait).

Problème 3 : Parallélisation

Troisième usage : plusieurs tâches indépendantes peuvent être confiées à plusieurs subagents en même temps.

Par exemple, « faire des recherches sur les modules d'authentification, de base de données et d'API » — ces trois blocs ne dépendent pas les uns des autres, vous pouvez donc lancer trois subagents pour les explorer en parallèle, puis Claude synthétisera les trois rapports pour vous. En séquentiel, vous devriez attendre trois fois plus longtemps ; en parallèle, c'est réglé en une seule fois.

Le piège contre-intuitif : diviser n'est pas toujours la solution

Après avoir présenté ces trois usages, revenons à notre affirmation du début — pourquoi « diviser dès le début » est-il une erreur ?

Parce que les débutants ont souvent cette idée reçue : « plus c'est divisé = plus c'est professionnel = plus c'est rapide ». C'est tout le contraire. Les subagents ont trois coûts cachés qui apparaissent immédiatement pour les tâches simples :

Comparaison	Tâche simple traitée directement dans la conversation principale	Tâche simple confiée à tort à un subagent
Coût de démarrage	Aucun, Claude commence immédiatement	Le subagent part d'une page blanche et doit d'abord passer du temps à « rassembler le contexte »
Allers-retours	Dialogue direct et modifications immédiates	Si la consigne est floue, il faut recommencer ; le subagent ne voit pas vos discussions précédentes
Coût	Une seule consommation de token	Ouvrir un nouveau contexte = consommer plus de tokens ; plus vous en ouvrez, plus vous consommez
Réintégration des résultats	N'existe pas	Chaque subagent renvoie ses résultats détaillés dans la conversation principale, ce qui finit par encombrer de nouveau l'espace de travail si on en utilise trop

La documentation officielle propose une liste de critères pour choisir entre la conversation principale et un subagent, que je résume ainsi : les tâches nécessitant de nombreux allers-retours, le partage du contexte, des modifications rapides et de la rapidité doivent rester dans la conversation principale. En revanche, les tâches qui génèrent beaucoup de données intermédiaires inutiles, nécessitent de restreindre l'accès aux outils, ou peuvent être traitées de manière autonome avec une simple conclusion en retour, doivent être sous-traitées.

La documentation souligne également un point contre-intuitif — le subagent est désavantagé lorsque le temps de latence est important :

La latence est importante. Les subagents partent de zéro et peuvent avoir besoin de temps pour rassembler le contexte.

Scénario réel : Si vous vous obstinez à créer un subagent pour une tâche aussi simple que « modifier le nom d'une variable » pour faire « plus professionnel ». Que va-t-il se passer ? Le subagent devra relire le fichier depuis le début (puisqu'il n'a pas votre contexte récent), effectuer la modification lentement, puis renvoyer le résultat. C'est beaucoup plus lent que de dire directement dans la conversation principale « modifie ce nom de variable », et cela consomme beaucoup plus de tokens. Il y a donc une règle d'or à retenir : si la tâche s'explique en une phrase et que la modification est sous vos yeux, ne la sous-traitez jamais.

💡 En résumé : Les subagents permettent d'isoler le contexte, de spécialiser les tâches et de les paralléliser. Cependant, les tâches simples sont plus rapides et moins coûteuses à réaliser directement — diviser ne signifie pas être plus professionnel, une division excessive ne fera que ralentir le processus, augmenter les coûts et réencombrer votre espace de travail.

Ce schéma montre clairement le principe de la « sous-traitance » : la conversation principale est votre espace de travail. Vous confiez à un subagent une tâche ingrate qui génère beaucoup de sorties intermédiaires (comme lancer des tests ou analyser des logs). Le subagent gère tous les détails dans sa pièce de contexte indépendante, et seule une ligne de « résumé des conclusions » revient vers le fil principal, gardant votre bureau toujours propre.

---

03 Comment faire : Création interactive avec /agents

Après avoir vu « quand l'utiliser », passons à la création. La méthode la plus simple est d'utiliser la commande /agents, qui est entièrement interactive et ne nécessite pas d'écrire la moindre ligne de configuration.

Dans votre session Claude Code, tapez :

/agents

Une interface de gestion va s'ouvrir. Pour en créer un nouveau, voici les étapes recommandées par la documentation officielle (que je décris ici pour que vous puissiez les suivre facilement) :

1. Choisir l'emplacement : Allez dans l'onglet Library → Create new agent → sélectionnez Personal. L'option Personal l'enregistrera dans ~/.claude/agents/, ce qui le rendra disponible pour tous vos projets ; l'option Project le limitera au projet en cours et permettra de le versionner avec git pour le partager avec votre équipe (nous détaillerons cette différence dans la section suivante).
2. Laisser Claude le générer : Choisissez Generate with Claude, puis décrivez simplement le type d'assistant que vous souhaitez. Par exemple : « Un assistant de relecture de code qui analyse les fichiers et propose des suggestions d'amélioration sur la lisibilité, les performances et les bonnes pratiques, en expliquant le problème à chaque fois, en montrant le code actuel et en fournissant la version améliorée. » Claude rédigera automatiquement le nom, la description et l'invite système correspondante.
3. Sélectionner les outils : Un relecteur ne doit faire que lire, donc cochez uniquement Read-only tools et décochez tout le reste. La documentation officielle donne un avertissement crucial : « Si vous laissez tous les outils sélectionnés, le subagent héritera de tous les outils disponibles dans la conversation principale. » — Si vous ne les limitez pas, il pourra tout faire.
4. Choisir le modèle : Sélectionnez un modèle spécifique pour ce subagent. Pour de la relecture, l'exemple officiel choisit Sonnet (bon équilibre entre capacités d'analyse et rapidité).
5. Enregistrer : Vérifiez le résumé de la configuration, appuyez sur s ou Entrée pour enregistrer, et il sera immédiatement prêt à l'emploi. (L'interface réelle vous proposera également de choisir une couleur de fond et une portée de mémoire [memory scope] ; la couleur est optionnelle, laissez la mémoire sur None par défaut pour débuter.)

Analogie : Remplir un « formulaire de recrutement de sous-traitance ». Vous n'avez pas besoin de savoir comment rédiger un contrat de travail. L'accueil (l'interface /agents) vous pose des questions une par une : comment s'appelle le poste, quelles sont ses tâches, quels outils il peut utiliser et quel niveau de compétence est requis. Une fois rempli, le « poste » est créé. L'option Generate with Claude fonctionne comme un assistant RH qui vous aide à remplir parfaitement le formulaire.

Scénario réel : C'est ainsi que l'on crée un subagent permanent très utile — un test-runner, dont le rôle est uniquement de « lancer les tests et ne renvoyer que ceux qui ont échoué avec leur message d'erreur ». Lors de sa création, on ne lui donne que les outils Read et Bash, et pas Write, justement pour éviter qu'il ne tente de modifier votre code pendant qu'il s'exécute. Créez-le une fois, et utilisez-le tous les jours.

💡 En résumé : /agents est la méthode recommandée pour créer des subagents. C'est un processus entièrement interactif où Claude vous aide à rédiger le rôle ; n'oubliez pas de limiter les outils, sinon le subagent héritera de toutes les permissions de la conversation principale.

---

04 Comment faire : Écrire manuellement un fichier de configuration

Une fois créé via l'interface interactive, le subagent est enregistré sur votre disque sous la forme d'un simple fichier Markdown. Comprendre la structure de ce fichier vous permet de l'écrire vous-même ou de modifier celui de quelqu'un d'autre.

Voici à quoi ressemble un fichier de subagent — une section YAML (frontmatter) en haut pour la configuration, et le corps du texte en dessous pour définir son rôle (l'invite système) :

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Analogie : Un badge d'accès + une fiche de poste pour votre assistant externe. La section YAML contient les informations techniques du badge — son nom, sa fonction, ses outils autorisés et son niveau (name/description/tools/model). Le corps du texte sous la ligne est sa fiche de poste : « qui tu es, ce que tu dois faire en arrivant, et selon quelles normes ». Il ne consulte que ces deux éléments pour travailler, et n'a pas accès aux autres informations de votre entreprise.

La documentation officielle précise que seuls les champs name et description sont obligatoires. Voici le détail des champs les plus courants :

Champ	Obligatoire	Rôle	Point clé pour débutant
name	Oui	Identifiant unique, en minuscules avec des tirets (ex. code-reviewer)	Doit être unique dans tout le projet, sinon l'un d'eux sera ignoré silencieusement
description	Oui	Indique à Claude « quand lui confier une tâche »	Plus elle est claire, plus la délégation automatique est précise ; c'est la clé du déclenchement
tools	Non	Les outils qu'il peut utiliser	Si omis = hérite de tous les outils de la conversation principale ; listez ici les outils autorisés pour restreindre les droits
model	Non	Le modèle à utiliser	sonnet/opus/haiku/inherit ; valeur par défaut : inherit (le même que la conversation principale)
permissionMode	Non	Le mode de permissions	Options : default/acceptEdits/auto/dontAsk/bypassPermissions/plan

L'emplacement du fichier est important car il détermine « qui peut l'utiliser ». La documentation officielle liste plusieurs niveaux, mais voici les deux plus courants à retenir :

Emplacement	Qui peut l'utiliser	Cas d'usage
~/.claude/agents/	Tous vos projets	Assistants personnels génériques, comme un relecteur de code que vous voulez utiliser partout
.claude/agents/	Uniquement le projet en cours	Assistants spécifiques à un projet ; peut être versionné avec git et partagé avec l'équipe

Le conseil de la documentation officielle pour le niveau projet est très pertinent :

Les subagents de projet (.claude/agents/) sont parfaits pour les tâches spécifiques à un codebase. Ajoutez-les au contrôle de version pour que votre équipe puisse les utiliser et les améliorer ensemble.

Enfin, un piège classique pour les débutants, signalé par une note importante dans la documentation officielle — si vous écrivez ou modifiez directement un fichier sur le disque, vous devez redémarrer la session pour qu'il soit pris en compte ; en revanche, les modifications effectuées via l'interface /agents s'appliquent immédiatement sans redémarrage. Après avoir écrit manuellement votre premier subagent, il est fréquent qu'il ne réponde pas parce que vous avez oublié de redémarrer la session.

💡 En résumé : Un subagent est un simple fichier Markdown avec une section YAML pour la configuration (seuls name et description sont obligatoires) et le corps du texte pour son rôle. Placez-le dans ~/.claude/agents/ pour un usage global, ou dans .claude/agents/ pour un partage au sein d'un projet ; n'oubliez pas de redémarrer la session si vous modifiez le fichier manuellement.

---

05 Comment le déclencher : Délégation automatique vs Appel direct

Une fois le subagent créé, comment le faire travailler ? Deux solutions : Claude l'appelle automatiquement en fonction de sa « description de poste », ou vous l'appelez directement par son nom.

Option 1 : Délégation automatique basée sur la description

Vous exprimez votre besoin normalement, et Claude compare votre phrase avec la description de chaque subagent. S'il trouve une correspondance, il lui délègue automatiquement le travail. Vous n'avez même pas besoin de savoir que ce subagent existe.

C'est pourquoi nous avons insisté dans la section précédente sur l'importance de rédiger une description précise — c'est le seul critère utilisé par Claude pour déléguer les tâches. La documentation officielle donne une astuce pour encourager Claude à utiliser un agent : inclure des expressions comme « use proactively » (utiliser de manière proactive) dans la description. Par exemple, si la description du relecteur est « relire de manière proactive le code dès qu'il est écrit ou modifié », le subagent pourra s'activer de lui-même dès que vous modifierez du code.

Analogie : Une bonne fiche de poste permet aux RH de distribuer correctement le travail. La description est l'« offre d'emploi » de ce poste externe. Si l'offre est vague (« traiter certaines tâches »), les RH (Claude) ne sauront pas quand faire appel à lui. Si elle est précise (« spécialisé dans la sécurité du code et le nommage, intervient de manière proactive après l'écriture du code »), dès qu'une tâche correspondante se présente, les RH pensent naturellement à lui.

Option 2 : Appel direct

Si la délégation automatique ne fonctionne pas comme vous le souhaitez, ou si vous préférez imposer un subagent spécifique, appelez-le directement. La documentation officielle propose plusieurs syntaxes, mais voici les deux plus simples à retenir :

Appel en langage naturel — mentionnez simplement son nom dans votre phrase, sans syntaxe particulière :

Utilise le subagent code-reviewer pour examiner mes dernières modifications

Appel avec @ — tapez @ et sélectionnez-le dans la liste (ce qui insérera une mention de type @"code-reviewer (agent)"), ou tapez directement @agent- suivi de son nom. Cette méthode « garantit » son utilisation, sans laisser le choix à Claude :

@agent-code-reviewer examine les modifications liées à l'authentification

La différence entre les deux méthodes est clairement expliquée dans la documentation : le langage naturel est une suggestion (« Claude déléguera généralement »), tandis que @ est une directive (« garantit qu'un subagent spécifique s'exécute »). Une bonne pratique pour débuter : utilisez toujours @ pour les nouveaux subagents dont vous ne maîtrisez pas encore le comportement, afin d'éviter que Claude ne décide de ne pas les appeler.

Comment la conclusion est-elle renvoyée ?

Quelle que soit la méthode de déclenchement, le subagent effectue son travail et ne renvoie que la « conclusion » à la conversation principale, laissant tout le processus dans sa propre pièce. C'est la concrétisation de l'analogie de la section 01 : l'assistant parcourt mille lignes de logs et ne renvoie qu'une note indiquant « les erreurs sont à ces trois lignes ». La documentation officielle le confirme : il « travaille de manière indépendante et renvoie les résultats », et « la sortie détaillée reste dans le contexte du subagent, tandis que seul le résumé pertinent est renvoyé à votre conversation principale ».

⚠️ Attention toutefois au piège de la quantité, explicitement mentionné dans la documentation : si vous lancez trop de subagents et que chacun renvoie un rapport extrêmement détaillé, votre espace de travail principal finira tout de même par être encombré. Ne surchargez donc pas le parallélisme — et respectez le critère de la section 02 : ne sous-traitez que les tâches autonomes qui peuvent se résumer en une phrase simple.

💡 En résumé : Le déclenchement peut se faire de deux manières — automatiquement par Claude via la description (qui doit être très précise), ou manuellement via le langage naturel ou un @ (le @ garantit son exécution) ; les subagents ne renvoient que leurs conclusions, mais des retours trop volumineux peuvent tout de même encombrer votre espace de travail.

---

06 En pratique : Créer et utiliser un premier subagent en 5 minutes

Rien ne vaut la pratique. Voici comment créer manuellement un petit subagent et le faire travailler, pour observer concrètement le flux « sous-traitance → retour de la conclusion ». Cette procédure ne nécessite aucune configuration complexe.

Nous allons créer un subagent très simple : un « relecteur de code » en lecture seule qui lit les fichiers et propose des pistes d'amélioration, mais sans avoir le droit de modifier le moindre caractère (accès aux outils Read uniquement, pas de Write/Edit).

Étape 1 : Créer un projet de test et le dossier des subagents (Mac / Linux)

mkdir sub-demo
cd sub-demo
mkdir -p .claude/agents

(Note pour Windows : Utilisez PowerShell ou créez ces dossiers via l'explorateur de fichiers)

Résultat attendu : Le dossier sub-demo contient maintenant la structure .claude/agents/. La commande ls .claude (ou dir .claude sous Windows) confirme la présence du dossier agents.

Étape 2 : Écrire le fichier de configuration du subagent

Avec votre éditeur de code préféré, créez le fichier sub-demo/.claude/agents/code-reviewer.md et collez-y le contenu suivant :

---
name: code-reviewer
description: 只读的代码点评员，读指定文件并从可读性、命名、潜在 bug 角度给改进建议。审查任何代码时主动使用。
tools: Read, Grep, Glob
---

你是一个资深代码审查员，只挑刺、不改代码。
被调用时：
1. 读用户指定的文件
2. 按可读性、命名、潜在 bug 三类列出问题
3. 每条问题给出具体的改进建议，但不要直接修改文件

按严重程度分组：必须改、建议改、可以考虑。

Notez que nous n'avons pas défini le champ model — par défaut, il prendra la valeur inherit (le même modèle que votre conversation principale). Les tools sont limités à trois outils de lecture seule : il ne pourra pas modifier votre code même s'il le souhaite.

Étape 3 : Créer un code « perfectible » à lui soumettre

echo 'def f(a, b):
    return a / b' > calc.py

Le nom de cette fonction f et de ses paramètres a et b ne sont pas explicites, et elle ne gère pas la division par zéro — c'est le cobaye idéal pour notre relecteur.

Résultat attendu : Le fichier calc.py est créé dans sub-demo avec ces deux lignes de code.

Étape 4 : Lancer Claude et appeler le subagent

claude

Une fois dans la session, utilisez le @ pour l'appeler directement (pour garantir son exécution, sans laisser Claude décider). Tapez @agent-code-reviewer ou tapez @ et sélectionnez code-reviewer dans la liste :

@agent-code-reviewer examine le fichier calc.py

Résultat attendu : Vous devriez voir Claude indiquer qu'il délègue la tâche au subagent code-reviewer (un indicateur visuel, souvent coloré, s'affiche pendant l'exécution). Le subagent va lire le fichier calc.py dans son propre contexte, puis renvoyer uniquement son rapport de relecture dans la conversation principale — il signalera probablement que le nom f et les paramètres a/b manquent de clarté, qu'il manque une gestion de la division par zéro, et proposera des corrections adaptées. Remarquez qu'il s'est contenté de donner des conseils et n'a pas modifié votre fichier (car l'outil Write ne lui a pas été attribué).

Étape 5 : Vérifier que le fichier n'a pas été modifié

Quittez Claude (tapez exit ou utilisez le raccourci Ctrl+D), puis vérifiez le fichier dans votre terminal :

cat calc.py

(Sous Windows PowerShell, utilisez type calc.py)

Résultat attendu : Le fichier calc.py est inchangé et contient toujours ses deux lignes d'origine — c'est la démonstration de la force de la « limitation des outils » : n'ayant que des outils de lecture, le subagent ne peut pas toucher à vos fichiers, même s'il voulait vous aider en appliquant ses corrections.

En suivant ces cinq étapes, vous avez configuré, chargé, déclenché un subagent et vérifié son fonctionnement dans son contexte isolé avec des permissions restreintes. Tous les subagents que vous créerez par la suite reposeront sur ce même principe : ajuster le rôle et définir les outils.

⚠️ Si le nom @agent-code-reviewer n'apparaît pas dans la liste des suggestions, c'est probablement que le fichier du subagent n'a pas été chargé — n'oubliez pas que les fichiers créés manuellement nécessitent de redémarrer la session de Claude Code (le piège décrit dans la section 04). Quittez et relancez Claude, ou passez par l'interface /agents pour éviter d'avoir à redémarrer.

💡 En résumé : Créer manuellement un relecteur limité à l'outil Read, l'appeler avec @ pour analyser un fichier, puis vérifier avec cat que le fichier n'a pas bougé — tester vous-même cette chaîne « exécution isolée + permissions restreintes » est le meilleur moyen de comprendre le fonctionnement des subagents.

---

07 En résumé

Dans cet article, nous avons vu comment décider d'utiliser un subagent, comment le créer, le déclencher et valider son comportement. Le plus important n'est pas de concevoir des architectures complexes de subagents, mais de savoir tracer la ligne de démarcation entre ce qui doit être sous-traité et ce qui doit être fait directement.

Voici un récapitulatif des points clés :

Ce que vous vouliez comprendre	Réponse	Point clé
Qu'est-ce qu'un subagent	Un assistant externe avec contexte + rôle + outils indépendants	Commence avec une page blanche, sans accès à vos discussions passées
Ce qu'il résout	Isolation du contexte, spécialisation des tâches, parallélisation	Sa grande force : faire le travail ingrat de son côté et ne renvoyer que la conclusion
Quand ne pas l'utiliser	Tâches simples, allers-retours fréquents, besoin de rapidité	Diviser n'est pas toujours synonyme d'efficacité ; une utilisation excessive est lente et coûteuse
Comment le créer	Avec la commande interactive /agents ou en écrivant .claude/agents/name.md	Seuls name et description sont obligatoires ; redémarrer après modification manuelle
Comment le déclencher	Automatiquement via sa description ou manuellement en langage naturel ou avec @	La mention @ garantit son exécution ; la description doit être précise pour la délégation automatique

Vous êtes maintenant capable de : évaluer si une tâche mérite d'être déléguée à un subagent, créer un subagent avec un rôle et des outils spécifiques via /agents ou un fichier Markdown, et l'appeler par délégation automatique ou appel direct pour récupérer proprement ses conclusions. Cette capacité à juger s'il faut faire soi-même ou déléguer est la véritable compétence requise pour maîtriser les subagents — la technique s'apprend en dix minutes, le discernement vient avec la pratique.

Rappelez-vous de notre constat de départ : la puissance d'un subagent réside dans la pertinence de son utilisation, pas dans le nombre d'agents créés.

💡 En résumé : La difficulté avec les subagents n'est pas de savoir les créer, mais de savoir quand les créer — sous-traitez les tâches ingrates, autonomes et nécessitant des permissions strictes ; faites le reste vous-même directement.

---

L'article suivant 24 « Les plug-ins (Plugins) » — vous commencez à accumuler de nombreux éléments : CLAUDE.md, commandes slash, Skill et maintenant Subagent. Configurer tout cela un par un peut sembler fastidieux. Le prochain article vous expliquera comment regrouper tous ces éléments au sein d'un plug-in, installable et partageable en un clic, ou comment en récupérer de prêts à l'emploi. Imaginez pouvoir importer instantanément les subagents et les commandes configurés par d'autres développeurs !

---

Lectures recommandées

• Guide de référence de la CLI : commandes et drapeaux
• Création de vidéos (Remotion) [Optionnel]
• Installation et utilisation