Claude Code Agents : créer et utiliser des sous-agents

Un sous-agent s’apparente à une fonction à laquelle une tâche est déléguée : Claude lui confie une mission, il travaille dans une fenêtre distincte qui reste invisible, puis rend une réponse propre. Bien utilisé, c’est le levier le plus puissant pour préserver la cohérence de Claude Code pendant une session de plusieurs heures. Mal employé, il ne fait que consommer des tokens et ajouter de la latence. Ce guide couvre les deux aspects : le fonctionnement précis, le fichier de définition et la règle honnête qui permet de savoir quand un sous-agent mérite d’être lancé.

Claude Code Agents : l’essentiel en 20 secondes

Un sous-agent exécute une tâche autonome dans un contexte isolé, puis renvoie une courte synthèse à la conversation principale. Tout tient là. Il répond à un problème bien précis : au fil d’une longue session agentique, les résultats de grep, les logs de build et les fichiers lus une fois puis oubliés s’accumulent, jusqu’à ce que le modèle consacre davantage d’attention à gérer ce bruit qu’à accomplir le travail demandé.

Confiez cette partie bruyante à un sous-agent : tout le désordre reste dans son contexte, tandis que le fil principal ne reçoit que la conclusion. Le bon modèle mental n’est donc pas « une équipe d’ingénieurs IA qui collabore », mais une hygiène du contexte assortie d’une valeur de retour. Une fois cette idée acquise, toutes les autres décisions deviennent plus simples.

Ce qu’est réellement un sous-agent

Un sous-agent s’exécute dans sa propre fenêtre de contexte, avec un prompt système personnalisé, un accès défini aux outils et des autorisations indépendantes. Lorsque Claude rencontre une tâche correspondant au rôle déclaré du sous-agent, il la lui délègue ; celui-ci travaille seul, puis renvoie son résultat. C’est la définition officielle, et les éléments essentiels sont bien sa propre fenêtre de contexte et le retour de son résultat.

C’est aussi le point que la plupart des explications déforment. Un sous-agent repart de zéro. Il ne voit ni l’historique de la conversation, ni les fichiers déjà lus par Claude, ni les skills déjà invoqués. Claude rédige un bref message de délégation qui résume la mission ; le sous-agent travaille ensuite uniquement avec son propre prompt système et quelques informations élémentaires sur l’environnement, comme le répertoire de travail, sans recevoir l’intégralité du prompt système de Claude Code. À la fin, seule sa synthèse remonte.

Cette isolation est à double tranchant, et tout l’enjeu consiste à bien comprendre ce compromis :

• Le bénéfice : toute la partie verbeuse — les douze fichiers lus, le grep infructueux, le log analysé — reste hors du contexte principal. Vous obtenez la réponse sans le désordre.
• Le coût : le sous-agent doit reconstituer un contexte que vous aviez déjà. Si la tâche n’a de sens qu’avec l’historique de la conversation, un sous-agent parti de zéro risque de s’égarer.

Le fichier qui définit un sous-agent

Un sous-agent personnalisé se définit dans un fichier Markdown doté d’un frontmatter YAML. Le frontmatter contient la configuration ; le corps Markdown devient le prompt système du sous-agent. Seuls deux champs sont obligatoires : name et description.

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

Voilà un sous-agent complet et fonctionnel. Le champ description n’est pas décoratif : Claude le lit pour décider quand déléguer. Une formulation précise comme « analyse le code et intervient immédiatement après sa création ou sa modification » déclenche le sous-agent au bon moment ; un vague « assistant de code » risque de le laisser inutilisé. Rédigez cette description comme une offre de mission destinée à un spécialiste.

Il n’est pas nécessaire d’écrire ce fichier à la main. La commande /agents de Claude Code ouvre une interface à onglets pour gérer les sous-agents : Running affiche ceux qui sont actifs ou viennent de terminer — avec la possibilité de les ouvrir ou de les arrêter — tandis que Library permet de les créer, de les modifier et de les organiser. Attention à un détail : les sous-agents sont chargés au démarrage de la session. Après une modification directe du fichier sur le disque, il faut donc redémarrer la session. En revanche, toute création ou modification effectuée dans l’interface /agents prend effet immédiatement.

Où stocker les sous-agents, et quelle définition prévaut

Un même fichier de sous-agent ne se comporte pas de la même façon selon son emplacement. Celui-ci détermine à la fois qui peut l’utiliser et quelle définition l’emporte en cas de conflit de noms.

Lorsque deux sous-agents portent le même nom, l’emplacement prioritaire l’emporte : une définition gérée prime sur celle du projet, qui prime elle-même sur celle de l’utilisateur. Les sous-agents du projet sont découverts en remontant l’arborescence depuis le répertoire de travail et, depuis la v2.1.178, la définition la plus proche de ce répertoire gagne en cas de conflit. Il existe aussi une option limitée à la session : transmettre les sous-agents en JSON avec le flag --agents au lancement de Claude Code. Ils n’existent alors que pour cette session, sans jamais être enregistrés sur le disque, ce qui convient bien aux scripts d’automatisation et aux tests rapides.

La règle pratique est simple : un sous-agent qui formalise la manière de relire ou de tester ce codebase doit résider dans .claude/agents/ et être versionné afin que toute l’équipe en profite. Celui qui reflète votre propre façon de travailler doit aller dans ~/.claude/agents/ pour vous suivre d’un projet à l’autre.

Modèle et outils : les deux réglages décisifs

Deux champs du frontmatter concentrent l’essentiel de la valeur. Bien les régler fait passer les sous-agents du statut de curiosité à celui d’outil véritablement rentable.

Modèle. Le champ model accepte un alias (sonnet, opus, haiku, fable), un identifiant complet tel que claude-opus-4-8, ou inherit. S’il est omis, sa valeur par défaut est inherit : le sous-agent utilise alors le même modèle que la conversation principale. C’est un levier budgétaire facile à manquer. Un sous-agent dont l’unique mission consiste à « parcourir le codebase avec grep et résumer les résultats » n’a pas besoin d’un modèle de pointe. Avec model: haiku, le travail répétitif s’exécute sur un modèle plus rapide et moins cher, tandis que la session principale reste sur Opus pour le raisonnement.

Outils. Par défaut, un sous-agent hérite de tous les outils internes et MCP disponibles dans la conversation principale. Deux champs permettent de réduire cet accès : tools constitue une liste d’autorisation — uniquement les outils indiqués — tandis que disallowedTools forme une liste d’exclusion — tous les outils sauf ceux indiqués. Un sous-agent de recherche qui ne doit jamais toucher aux fichiers peut recevoir tools: Read, Grep, Glob, Bash et devient alors physiquement incapable de les modifier. Ce n’est pas une simple mesure d’ordre : c’est une véritable frontière de sécurité. Un reviewer en lecture seule ne peut pas réécrire accidentellement le fichier qu’il examine.

Autre réglage utile : isolation: worktree lance le sous-agent dans un worktree Git temporaire, c’est-à-dire une copie isolée du dépôt, automatiquement nettoyée si le sous-agent n’apporte aucune modification. Utilisez-le pour lui faire essayer une opération risquée sans qu’il interfère avec l’arbre de travail courant.

Quand utiliser un sous-agent — et quand s’en passer

C’est la partie que les simples collections de configurations sur GitHub laissent de côté, alors qu’elle permet réellement d’économiser du temps et de l’argent. Un sous-agent n’est pas gratuit. La bonne question n’est donc jamais « pourrais-je en utiliser un ici ? », mais « l’isolation rembourse-t-elle son propre coût ? ».

À l’inverse, voici les situations où le fonctionnement même de la fonctionnalité rend le sous-agent inadapté :

• Allers-retours fréquents. Si la tâche demande des ajustements répétés et votre jugement à chaque étape, conservez-la dans la conversation principale. La délégation casse cette boucle.
• Phases qui partagent le même contexte. Un enchaînement planification, implémentation, puis tests, dans lequel chaque phase repose sur la précédente, doit rester dans un même fil plutôt que d’être réparti entre trois sous-agents isolés qui redémarrent chacun à l’aveugle.
• Petites modifications ciblées. Lancer un sous-agent pour corriger une seule coquille coûte plus cher que la correction elle-même.
• Travail sensible à la latence. Un sous-agent repart de zéro et doit prendre le temps de reconstituer le contexte. Si la réponse doit arriver tout de suite, travailler dans le fil principal sera plus rapide.

Sous-agent, skill, fork ou équipe d’agents ?

Claude Code propose désormais quatre façons de structurer le travail, faciles à confondre. Leur différence tient entièrement au contexte.

La distinction qui prête le plus souvent à confusion est skill ou sous-agent, car les deux ressemblent à une forme d’« expertise enregistrée ». Un skill rassemble des instructions réutilisables exécutées dans le contexte de la conversation principale ; il voit donc tout ce qui s’y passe. Le sous-agent fonctionne à l’inverse : son isolation est intentionnelle et il ne connaît que la mission reçue. Si Claude doit appliquer votre charte éditoriale tout en poursuivant le travail avec vous, choisissez un skill. Si une enquête bruyante doit se dérouler hors champ avant de livrer sa conclusion, choisissez un sous-agent.

Le fork constitue un entre-deux utile : il hérite de toute la conversation jusqu’à cet instant — même prompt système, mêmes outils, même modèle et même historique de messages. Rien n’est à réexpliquer, mais ses appels d’outils restent malgré tout hors du contexte principal et seul son résultat final revient. Un fork est préférable lorsqu’un sous-agent nommé aurait besoin de trop d’informations préalables pour être efficace. (Le mode fork est conditionné par la variable d’environnement CLAUDE_CODE_FORK_SUBAGENT.)

Fonctions avancées et limites à connaître

Deux capacités récentes rendent les sous-agents bien plus puissants, chacune avec une limite qu’il faut respecter.

Imbrication. Depuis Claude Code v2.1.172, un sous-agent peut créer ses propres sous-agents. Un reviewer peut confier chaque constat à un vérificateur distinct ; tous les résultats intermédiaires restent enfouis et seule la synthèse du sous-agent de premier niveau vous parvient. La limite est fixe : l’imbrication s’arrête à cinq niveaux, ce réglage n’est pas modifiable et un sous-agent situé au cinquième niveau ne reçoit pas l’outil Agent, donc ne peut plus rien créer en dessous. Ce plafond a une raison d’être. Une arborescence profonde peut lancer accidentellement tout un essaim et faire exploser la consommation de tokens : considérez la profondeur comme un budget, jamais comme un objectif.

Mémoire. Ajoutez memory: project — ou user, ou local — et le sous-agent obtient un répertoire de mémoire persistant qu’il consulte et alimente d’une session à l’autre. Avec une mémoire de projet, un code-reviewer accumule progressivement les conventions du codebase et les problèmes récurrents ; sa pertinence augmente donc avec l’usage. project est la valeur recommandée par défaut, car elle peut être partagée dans le contrôle de version. Lorsque la mémoire est activée, Claude Code injecte au démarrage les 200 premières lignes — ou 25KB — du fichier MEMORY.md dans le prompt système du sous-agent. Ce fichier doit donc rester soigneusement organisé.

Pour commencer, créez un seul sous-agent bien ciblé — un code-reviewer en lecture seule est l’exemple canonique —, versionnez-le dans .claude/agents/ et lancez-le après chaque modification. Une fois son intérêt confirmé, ajoutez un sous-agent de recherche utilisant un modèle moins cher. Les équipes qui tirent profit de cette approche ne font pas tourner trente agents : elles en emploient trois, chacun excellent dans une seule mission. Si votre question porte plutôt sur le choix de l’outil de développement, consultez Codex face à Claude Code et Cursor, ainsi que notre tour d’horizon des meilleurs agents IA pour coder.

Si vous cherchez à intégrer Claude Code dans une méthode de livraison réellement opérationnelle, c’est précisément le sujet central de mes articles. Inscrivez-vous à la newsletter pour découvrir les configurations qui fonctionnent sur le terrain, loin du battage médiatique des lancements.