Explication des sous-agents de Claude Code : ce qu’ils sont et quand les utiliser.

Les agents ne sont pas simplement des compétences déguisées

La première réaction courante face aux agents de Claude Code est de les considérer comme des compétences avec des étapes supplémentaires, une « compétence plus intelligente » qui agit de manière plus autonome parce que ses instructions sont formulées différemment. Cette vision est erronée. Un agent est en effet un prompt, tout comme une compétence. La différence importante réside dans le lieu où il s’exécute. Un agent ne s’exécute pas au sein de la conversation principale. Il dispose de sa propre fenêtre de contexte, de son propre prompt système, de son propre accès aux outils et de ses propres permissions ; il travaille en arrière-plan avant de restituer un résultat.

Ce qui suit part des bases : ce qu’ils sont, comment en créer un, et quand les efforts en valent la peine. Il part du principe que vous utilisez déjà Claude Code et que vous souhaitez bien comprendre cette fonctionnalité avant de modifier toute configuration. L’ordre est d’abord le problème de vocabulaire, puis les raisons pour lesquelles il existe des sous-agents, ensuite un premier sous-agent personnalisé, puis la manière dont ils diffèrent des compétences, puis les pratiques de travail, un aperçu des équipes d’agents, et enfin les cas où un agent n’est pas le choix approprié.

Quatre significations du terme « agent »

Dans Claude Code, le mot « agent » désigne au moins quatre choses distinctes, et les confondre rend toute la fonctionnalité plus difficile à comprendre. Un peu de précision ici s’avère utile, car elle permet de relier le vocabulaire aux outils que l’on peut réellement utiliser.

1. Claude Code est lui-même un environnement agent. Anthropic le présente comme un assistant de codage agent : il dispose d’outils et d’une boucle d’exécution, et il peut planifier et agir sur plusieurs étapes sans avoir besoin d’instructions à chaque fois. Il est déjà agent avant même que vous ne configuriez quoi que ce soit.
2. Les sous-agents sont les primitives d’agent personnalisées intégrées au produit. Lorsqu’un utilisateur affirme qu’il crée un agent dans Claude Code, il a presque toujours en tête un sous-agent. Selon la documentation officielle, il s’agit de sous-agents servant d’assistants spécialisés pour des types de tâches spécifiques, chacun disposant d’une fenêtre de contexte distincte, d’un prompt système personnalisé, d’un accès aux outils défini et de permissions indépendantes.

Les équipes d’agents relèvent d’une fonctionnalité différente, multi-session. La documentation des équipes précise clairement cette distinction : les sous-agents opèrent au sein d’une seule session, tandis que les équipes coordonnent leurs actions sur plusieurs sessions. Une équipe est un ensemble d’instances indépendantes de Claude Code qui communiquent grâce à une liste de tâches partagée et à des messages directs entre leurs membres. Il s’agit d’une fonctionnalité expérimentale, désactivée par défaut et activable via un paramètre d’environnement. Ce n’est pas simplement « plus de sous-agents » ; elle repose sur une couche différente de l’architecture.

Le SDK Claude Agent constitue une quatrième couche. Il met à disposition les mêmes outils et le mécanisme d’agent qui alimentent Claude Code, sous forme de bibliothèques Python et TypeScript, destinées aux équipes qui développent leurs propres applications d’agent en dehors de l’interface en ligne de commande.

Le reste porte sur le deuxième point, les sous-agents. Les équipes méritent d’être traitées séparément plus tard ; expliquer en détail un sous-agent est le bon point de départ.

Pourquoi les sous-agents existent

La cause fondamentale réside dans le fait que les modèles de langage ont un contexte fini, et tôt ou tard une session longue atteint cette limite. Sans mesure corrective, cela se reproduit sans cesse.

L’essai d’Anthropic sur la gestion du contexte décrit cette discipline comme l’art de sélectionner ce qui entre dans une fenêtre limitée. Chaque appel d’outil, lecture de fichier et analyse inachevée est ajouté au contexte et y reste. Plus une session dure, plus cette fenêtre est occupée par des éléments qui ont aidé à trouver une réponse mais qui deviennent inutiles par la suite. Ce désordre nuit à la qualité, un phénomène souvent qualifié de dégradation du contexte. Le modèle dispose alors d’un espace de travail réduit, et davantage de matériel irrelevant concourt pour attirer son attention.

Les sous-agents constituent une solution. La description générale de Claude Code l’indique clairement : un sous-agent peut lire des dizaines de fichiers ou effectuer des recherches approfondies, mais la conversation principale ne reçoit qu’un résumé, de sorte que le travail intermédiaire n’utilise jamais le contexte principal. C’est pratique lorsque les étapes intermédiaires n’ont pas besoin de rester visibles.

Exemple concret : vous demandez à Claude de découvrir pourquoi un ensemble de tests échoue. Dans la session principale, cette investigation implique la lecture de vingt fichiers, la recherche de motifs d’erreur, la vérification de la configuration des tests et le scan des commits récents. Tout cela finit par figurer dans votre contexte. À la fin, vous avez consacré plusieurs milliers de tokens à ce travail intermédiaire, sans que presque rien n’affecte ce que vous ferez ensuite.

Un sous-agent restructure le problème. L’enquête s’effectue dans sa propre fenêtre de contexte et avec son propre budget de tokens, et ce qui en ressort est un verdict bref, du type « la panne est due à une variable d’environnement absente de la configuration CI ; trois tests sont affectés, voici comment la réparer ». Le thread principal ne prend jamais en compte le bruit généré par les recherches.

L’isolation du contexte en est la raison principale, à laquelle s’ajoutent trois autres facteurs importants :

1. Spécialisation. Un sous-agent dispose de son propre prompt système. Un examinateur ciblé, doté d’instructions relatives aux normes de votre équipe, sera plus fiable qu’un assistant général qui tenterait d’appliquer ces normes en même temps que tout le reste qu’il connaît.

Application des contraintes. Vous décidez précisément quels outils un sous-agent peut utiliser. Un agent de recherche en lecture seule qui ne peut pas écrire de fichiers ni exécuter de commandes shell présente un profil de risque très différent de celui de l’assistant principal, et ces limites sont déclarées et appliquées de manière explicite plutôt que simplement espérées.

Contrôle des coûts. Un sous-agent peut fonctionner sur un modèle différent. Envoyer des tâches légères à Haiku tandis que la session principale utilise Sonnet est un moyen pratique de gérer les dépenses, une solution que beaucoup ne découvrent qu’après avoir reçu une facture désagréable.

Création d’un premier sous-agent personnalisé

Techniquement, un sous-agent n’est rien de plus qu’un document Markdown avec une en-tête YAML. Deux emplacements sont valables :

• .claude/agents/ à l’intérieur d’un projet, pour les agents liés à cette base de code. Communiquez-les afin que l’équipe puisse les partager et les améliorer.

~/.claude/agents/ dans le répertoire personnel, pour les agents personnels disponibles dans chaque projet.

Le frontmatter mérite attention

Les gens ont tendance à parcourir rapidement le frontmatter YAML, mais Claude Code le conserve en mémoire de la session principale afin de comprendre l’usage de chaque agent. En fait, il s’agit du résumé de l’agent. Deux champs sont obligatoires et plusieurs autres sont optionnels. Un exemple simple montre comment ils s’assemblent :

---
name: code-reviewer
description: Reviews code changes for quality, security, and best practices.
             Use proactively after any significant code change.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, read the changed files and provide
specific, actionable feedback on code quality, security, and best practices.
Focus on what matters. Don't restate what the code does — say what's wrong
or good about it. Flag security issues first, then logic problems, then style.

Champ par champ :

• name est l’identifiant unique, en minuscules et ne contenant que des tirets. Les journaux le affichent, et Claude l’utilise pour nommer l’agent en interne.
• description est le plus important. Claude s’y réfère pour déterminer si une tâche appartient à cet agent ; elle doit donc décrire son comportement : le travail qu’il effectue et les moments où il doit être sollicité. L’inclusion de l’expression « utiliser de manière proactive » est un indicateur documenté indiquant à Claude d’activer l’agent sans attendre une demande explicite. Omettez cette phrase si l’agent ne doit répondre qu’en cas de demande directe.

tools limite ce à quoi l’agent peut accéder. Le revueur mentionné ci-dessus peut lire des fichiers et effectuer des recherches, mais il ne peut pas les modifier, exécuter de commandes shell ni effectuer des appels réseau. C’est intentionnel : un revueur en lecture seule ne peut pas modifier par erreur ce qu’il examine. La documentation elle-même conseille d’accorder uniquement les outils dont l’agent a besoin, pour des raisons de sécurité et afin de maintenir son comportement prévisible.

model dirige l’agent vers un modèle spécifique : sonnet, opus, haiku, ou une identifiant complet tel que claude-opus-4-6. Sans cette valeur, l’agent utilise inherit, ce qui signifie qu’il utilise le même modèle que la session principale.

Tout ce qui se trouve dans le frontmatter devient la prompt système de l’agent. Cette prompt, ainsi que le répertoire de travail, constituent tout ce que l’agent reçoit de la session principale.

La liste complète des champs optionnels montre à quel point il est possible de personnaliser davantage : permissionMode, maxTurns, skills, mcpServers, effort, memory, hooks, disallowedTools, color et d’autres.

Après avoir vu un agent, on pourrait penser qu’il s’agit presque d’une compétence. On aurait partiellement raison, mais on manquerait aussi une partie essentielle, que les sections suivantes expliqueront en détail.

Où placer le fichier

Enregistrez l’exemple sous le nom .claude/agents/code-reviewer.md dans le projet. La structure résultante ressemblera à ceci :

your-project/
├── .claude/
│   ├── agents/
│   │   └── code-reviewer.md          ← your new agent file
│   ├── skills/
│   └── rules/
├── src/
├── tests/
├── README.md
└── package.json

Après enregistrement, Claude détecte l’agent. Demandez-lui d’examiner les modifications de code et il les déléguera automatiquement à code-reviewer, en fonction de la correspondance entre la demande et sa description. Pour un agent personnel utilisé sur tous les projets, déplacez le fichier vers ~/.claude/agents/code-reviewer.md. Le format et le contenu restent identiques ; seul le lieu change.

Agents versus compétences

Pourquoi les confond-on souvent

Trois similitudes expliquent la plupart des confusions :

1. Tous deux sont configurés à l’aide d’une structure de dossiers simple, soit dans .claude/skills, soit dans .claude/agents.
2. Tous deux utilisent du frontmatter, et dans les deux cas la description est l’élément le plus important.
3. Tous deux sont des ensembles d’instructions, c’est-à-dire des prompts. Une compétence et un agent peuvent contenir exactement les mêmes mots.

Vus de cette façon, ils ont l’air structuralement similaires.

Où se déroule le travail

Pourtant, une différence visible et pratique les sépare : l’endroit où le travail est effectué, c’est-à-dire où les tokens sont dépensés. C’est la distinction la plus simple à comprendre.

• Une compétence est intégrée dans la conversation en cours. Ses instructions, modèles et fichiers de support rejoignent le contexte actif ; Claude les traite dans le même fil de discussion, et chaque étape s’ajoute à la fenêtre principale.
• Un sous-agent fonctionne séparément dans sa propre fenêtre de contexte. Il effectue le travail, et la conversation principale reçoit un résultat.

Paramètres de réglage

Auparavant, une longue liste de champs que l’agent peut définir dans son frontmatter existait. En revanche, les compétences ne prennent en compte qu’une liste beaucoup plus courte, et partiellement différente. Cela indique le degré accru de contrôle accordé aux agents. Ce n’est pas une raison pour transformer tout en agent. Le problème, c’est que le modèle mental utilisé pour concevoir une configuration fiable pourrait nécessiter une réflexion approfondie.

Une tâche, deux solutions

Prenons l’exemple du souhait de voir les normes d’examen du code de son équipe appliquées de manière cohérente.

Si Claude doit être conscient de ces normes tout au long d’une session, les utiliser lorsqu’il écrit du code, les citer dans ses conseils et signaler les violations au fur et à mesure qu’elles apparaissent, une compétence convient. Il suffit d’écrire les normes une seule fois, et Claude les intégrera dans le contexte lorsque cela sera pertinent, afin que tout ce qui est fait pendant la session puisse s’appuyer sur elles.

Si, en revanche, vous souhaitez que quarante fichiers soient examinés d’un seul coup sans que le contexte principal ne soit envahi par les lectures de fichiers, les commentaires intermédiaires et les résultats de recherche, il s’agit alors d’un sous-agent. Configurez un agent d’examen de code, laissez-le fonctionner dans sa propre fenêtre, et obtenez un résumé structuré. Vous pourriez même lancer quarante sous-agents en parallèle, un par fichier. La conversation principale reçoit le résultat sans les étapes qui l’ont produit.

Une phrase résume cette distinction : une compétence modifie ce que Claude sait ou la manière dont il aborde un flux de travail, tandis qu’un sous-agent modifie celui qui effectue le travail, dans quel contexte et avec quels outils.

Pratiques de travail fiables

Considérez la description comme une interface de routage

Ce point n’est pas mis en évidence autant qu’il le devrait. Claude lit les descriptions des sous-agents pour décider quand déléguer, et il ne lit pas le corps du texte avant de prendre une décision. Tout élément spécifique que vous insérez dans le corps du prompt reste invisible jusqu’à ce que le sous-agent ait été créé. La description doit donc contenir suffisamment d’informations pour que Claude sache quand l’agent est nécessaire.

• Utilisez des formulations comportementales précises.
• Indiquez ce que fait l’agent et dans quels cas il doit être choisi.
• Mentionnez les types de tâches qu’il gère bien et, si nécessaire, celles qu’il ne doit pas traiter.
• « Utiliser de manière proactive après des modifications de code » est un modèle éprouvé, mentionné dans la documentation comme moyen d’encourager la délégation sans demande explicite. Omettez-le pour les agents qui ne doivent s’exécuter que lorsqu’ils sont invoqués directement.

Évitez les descriptions qui indiquent l’identité de l’agent, comme « un expert en révision ayant vingt ans d’expérience ». Cela doit figurer dans le prompt du système. La description sert le modèle de routage, pas l’agent.

Pour voir la différence, placez une description vague (« Aide à améliorer la qualité du code et aux tâches de révision ») à côté d’une autre conçue pour le routage : « Vérifie les modifications préparées en quête de failles de sécurité, d’erreurs logiques et de problèmes de style. L’exécutez proactivement après chaque modification importante. Il ne écrit jamais de code ni ne modifie de fichiers. »

Restreignez délibérément les outils

Un agent qui hérite de tous les outils de la session principale est difficile à gérer en cas de problème. Accordez uniquement ce dont le travail a besoin.

• Un réviseur doit pouvoir lire, et rien de plus : pas d’écriture, pas de shell, pas de réseau.
• Le travail de recherche nécessite des recherches et des récupérations, sans possibilité d’éditer les fichiers.
• La réalisation de tests implique un accès à Bash, mais aucune raison d’interagir avec le web.

Restreindre les outils améliore à la fois la sécurité et la clarté. Un ensemble d’outils restreint rend le comportement prévisible, et lorsque l’agent échoue ou renvoie des résultats inhabituels, une courte liste d’outils possibles accélère le diagnostic. Cela permet également de limiter les modes d’échec à des cas connus. Le champ disallowedTools permet à un agent d’hériter des outils de la session principale puis d’en exclure certains, ce qui convient à des cas tels que « tout sauf Bash » ou « tout sauf l’écriture ».

Donnez à chaque agent une seule tâche

La documentation relative aux sous-agents indique clairement que chaque sous-agent doit exceller dans une seule tâche. Une description telle que « examine le code, écrit des tests, met à jour la documentation et gère les vérifications de déploiement » regroupe quatre fonctions dans un seul champ. Claude peut les traiter de manière inégale, et l’instruction système doit gérer quatre modes de fonctionnement en même temps.

Restreignez le champ d’action et créez trois fichiers distincts, chacun avec une description claire. En science des données, il pourrait s’agir d’un agent de validation de modèles, d’un vérificateur de qualité des données et d’un examinateur de notebooks. En logiciel, il pourrait s’agir d’un examinateur de code, d’un générateur de tests et d’un metteur à jour de documentation. Ce principe s’applique dans tous les domaines. Chaque agent a une seule tâche, son propre fichier, ainsi qu’une description permettant une redirection sans ambiguïté.

Utilisez le champ du modèle pour gérer les coûts

Les personnes qui n’ont pas encore été surprises par leur facture d’utilisation ont tendance à ignorer ce champ le plus souvent. Définir model: haiku sur des agents légers permet de réduire considérablement les coûts lorsque plusieurs agents fonctionnent au cours d’une même session. Définir model: opus sur un agent qui doit raisonner longuement à partir d’un contexte volumineux justifie son prix élevé. Laisser la valeur par défaut, inherit, signifie que chaque agent utilise le même modèle que la session principale, souvent le modèle le plus performant, ce qui est appliqué de manière égale aux tâches qui n’en ont pas besoin.

Ce à quoi la communauté est parvenue

La collection de sous-agents VoltAgent recense plus d’une centaine de spécialistes, allant des experts en langages aux auditeurs de sécurité, en passant par les débogueurs, les assistants à l’infrastructure et les orchestrateurs. Un autre ensemble intéressant se trouve dans le répertoire Everything Claude Code. Peu de personnes auraient besoin même d’un cinquième d’entre eux, donc le nombre n’est pas l’aspect le plus important : c’est plutôt la structure. Chaque entrée de ces collections a un champ d’action restreint, qu’il s’agisse d’un spécialiste en TypeScript, d’un expert en SQL, d’un opérateur Kubernetes ou d’un auditeur de sécurité. Aucun ne cherche à couvrir plus d’un domaine. C’est la conclusion tirée après plus d’un an d’utilisation réelle : de nombreux agents spécialisés surpassent un agent polyvalent.

Un bref aperçu des équipes d’agents

Il est utile de connaître les équipes d’agents, mais il s’agit d’une fonctionnalité différente des sous-agents.

Les sous-agents restent au sein d’une seule session. L’instance principale de Claude Code les crée, ils travaillent de manière isolée et renvoient des résultats, tandis que vous restez l’orchestrateur.

Les équipes d’agents sont des sessions indépendantes de Claude Code qui communiquent entre elles grâce à une liste de tâches partagée et à des messages directs. Chaque membre de l’équipe dispose de sa propre fenêtre de contexte et d’état de session, et peut attribuer des tâches aux autres ainsi qu’en recevoir.

La documentation des équipes indique où ce mécanisme supplémentaire est utile : pour la recherche ou l’examen avec plusieurs membres de l’équipe qui explorent ensemble différents angles ; pour le débogage en testant des hypothèses concurrentes, avec les membres qui examinent mutuellement les théories ; et pour la création de nouveaux modules, où chaque membre gère sa propre composante tout en évitant les conflits avec les autres.

Leur mise en place n’est pas simple, ce qui les exclut du champ d’application ici ; il n’y a aucune raison de se lancer par peur de manquer quelque chose. Les équipes ajoutent une charge de coordination et consomment beaucoup plus de tokens, car chaque membre de l’équipe dispose d’une fenêtre de contexte facturée séparément. Il s’agit de solutions expérimentales désactivées par défaut, et leur activation se fait via une variable d’environnement.

Règle pratique : tant que vos sous-agents vous font rapport et n’ont pas besoin de communiquer entre eux, les équipes ne sont pas nécessaires. Lorsqu’un sous-agent doit transmettre ses résultats à un autre ou remettre en question ses conclusions, l’amélioration commence alors à justifier son coût. Jusque-là, des sous-agents suffisent.

Lorsqu’un agent est l’outil inadapté

Les directives d’Anthropic concernant la création d’agents efficaces méritent d’être prises au sérieux. Elles recommandent de trouver la solution la plus simple et fonctionnelle, et d’ajouter de la complexité uniquement lorsque c’est nécessaire, ce qui peut signifier de ne pas créer de systèmes d’agents du tout.

Cela s’applique directement. Voici quelques situations où un sous-agent crée des obstacles sans apporter de résultat :

• Tâches ponctuelles. Un sous-agent implique des coûts supplémentaires : nommer l’agent, rédiger sa description, choisir des outils, le tester, en assurer la maintenance. Une tâche à effectuer une seule fois ne justifie pas cela ; il vaut donc mieux rédiger un bon prompt. L’investissement ne s’avère rentable que lorsque le flux de travail se reproduit suffisamment souvent pour justifier la maintenance d’une définition.

Cas où le contexte n’est pas un problème. La raison principale d’utiliser un sous-agent est de protéger votre contexte principal des tâches lourdes. Si la tâche est légère, que la fenêtre de temps n’est pas saturée et qu’aucune limite liée à un outil spécial n’est nécessaire, un sous-agent ne fait qu’ajouter de l’indirection. Les instructions simples dans la session principale offrent un avantage en termes de vitesse, de simplicité et de facilité de débogage.

Le piège du monolithe. Un seul agent qui tente de gérer la recherche, l’implémentation, la revue et la documentation n’est pas complet. Il est impossible à tester et sa sélection est aléatoire. Une description plus précise et ciblée permet d’obtenir une cohérence bien meilleure.

Le principe général est de choisir l’outil le plus simple capable de résoudre le problème réel. Ajoutez des agents lorsque le problème concerne l’isolation du contexte, des contraintes spécialisées ou une exécution dédiée, et non parce que les agents semblent plus puissants.

La version courte

En termes simples, les sous-agents gèrent le contexte et délimitent les frontières d’exécution, bien que la plupart des gens les considèrent comme un moyen d’améliorer les performances.

Un agent soigneusement configuré représente un travail raisonnable pour une après-midi. Aucun système d’orchestration n’est nécessaire pour en tirer parti : une description ciblée, un ensemble d’outils restreint et une tâche claire suffisent. La complexité peut ensuite augmenter, mais elle n’est pas obligatoirement au départ.

Il y a quelques questions que vous devriez vous poser. Quelle tâche dans votre flux de travail actuel aimeriez-vous le plus confier à un travailleur isolé, et qu’est-ce qui vous en empêche ? Si vous utilisez déjà des sous-agents, quelle a été la première tâche pour laquelle l’isolement était vraiment crucial, où son exécution dans la session principale aurait causé un véritable problème ? Et comment gérez-vous l’accès aux outils : en les restreignant par agent, ou en les héritant de la session principale puis en les limitant ?