Sous-agents Claude Code : ce qu'ils font et quand les utiliser

Réponse courte : un sous-agent est un contexte distinct auquel Claude Code délègue du travail, avec son propre prompt système, ses propres autorisations d’outils et, si vous le souhaitez, son propre modèle. La documentation d’Anthropic énumère cinq raisons de les utiliser : préserver le contexte en gardant l’exploration et l’implémentation hors de votre conversation principale, imposer des contraintes en limitant les outils accessibles, réutiliser des configurations d’un projet à l’autre, spécialiser le comportement par des prompts système ciblés et maîtriser les coûts en orientant des tâches vers des modèles plus rapides et moins chers. La première et la dernière sont celles qui changent le plus votre quotidien.

Le problème de contexte qu’ils résolvent

Chaque message d’une session Claude Code emporte avec lui toute la conversation. Lisez quarante fichiers en cherchant quelque chose, et ces quarante fichiers restent en contexte pour le reste de la session, en concurrence avec le travail qui vous intéresse vraiment.

Cela produit deux symptômes visibles. Les longues sessions deviennent plus lentes et plus coûteuses, car le facteur de coût est la fenêtre de contexte et non le nombre de messages. Et la qualité se dégrade, car le signal dont vous avez besoin se retrouve enfoui sous des sorties d’exploration qui n’étaient pertinentes que cinq minutes.

Un sous-agent règle cela structurellement. Le travail délégué se déroule dans son propre contexte et seul le résultat revient. Douze fichiers lus pendant une recherche vous coûtent un résumé dans la conversation principale au lieu de douze fichiers de bruit.

C’est pourquoi les agents d’exploration intégrés existent, et pourquoi ce sont ceux que vous utiliserez le plus, souvent sans le remarquer.

Les sous-agents intégrés

Anthropic documente plusieurs types livrés avec Claude Code, et savoir à quoi chacun est contraint explique bien des comportements autrement déroutants.

Deux détails de ce tableau méritent qu’on s’y arrête.

L’agent Explore est plafonné à Opus sur l’API Claude, ce qu’Anthropic explique par le fait qu’Explore ne doit jamais tourner sur un modèle plus cher que celui déjà choisi pour la session. C’est un garde-fou de coût délibéré, et cela signifie que fouiller votre base de code ne se facture pas discrètement au tarif d’un modèle de pointe.

Explore et Plan sont tous deux en lecture seule, Write et Edit refusés. C’est ce qui rend la délégation sûre : vous pouvez envoyer un agent enquêter sans qu’il puisse se mettre à modifier pendant qu’il y est.

Écrire le vôtre

Un sous-agent maison est un fichier Markdown avec un frontmatter. La structure est assez courte pour être retenue.

---
name: code-improver
description: Analyse les fichiers et propose des améliorations de lisibilité, de performance et de bonnes pratiques. À utiliser après avoir écrit ou modifié du code.
tools: Read, Grep, Glob
model: sonnet
---
Tu es spécialiste de l'amélioration de code. Pour chaque problème trouvé, explique la cause, montre le code actuel et fournis une version améliorée.

Quatre champs font tout le travail. name sert à l’invoquer. description est ce que Claude lit pour décider de déléguer ou non, ce qui en fait la ligne la plus importante du fichier. tools restreint ce qu’il peut faire. model choisit le palier.

La description mérite plus de soin qu’on ne lui en accorde. Claude s’en sert pour décider quand l’agent s’applique, donc une description vague produit un agent jamais sollicité ou sollicité à mauvais escient. Indiquez explicitement la condition de déclenchement, comme dans l’exemple ci-dessus avec « À utiliser après avoir écrit ou modifié du code ».

Le plus rapide pour en créer un est de demander à Claude Code de l’écrire. Décrivez ce que vous voulez, où il doit vivre et ce qu’il a le droit de faire, puis relisez le fichier généré avant de l’utiliser.

Où vivent les définitions de sous-agents

Anthropic documente cinq emplacements avec un ordre de priorité défini, et le connaître évite la confusion courante où un agent se comporte autrement que le fichier que vous avez sous les yeux.

1. Les réglages gérés, déployés de façon centralisée à l’échelle de l’organisation. Priorité maximale.
2. Le drapeau CLI --agents, qui prend du JSON et s’applique à la session en cours.
3. .claude/agents/, limité au projet en cours.
4. ~/.claude/agents/, disponible sur tous vos projets.
5. Le répertoire agents/ d’un plugin, partout où ce plugin est activé. Priorité minimale.

La règle pratique : les définitions au niveau du projet l’emportent sur les vôtres, et ce que votre organisation déploie via les réglages gérés l’emporte sur les deux.

Le drapeau --agents est sous-utilisé et pratique pour du travail ponctuel. Vous passez un objet JSON définissant des agents en ligne au lancement de Claude Code, ce qui convient quand vous voulez une configuration spécialisée une seule fois sans laisser de fichier derrière vous.

Ce qu’il faut savoir avant de bâtir une flotte

Déléguer coûte un aller-retour. Il faut lancer le sous-agent, lui donner du contexte et récupérer son résultat. Pour une tâche que la conversation principale réglerait en deux étapes, cette surcharge est une perte. La délégation paie quand le travail déverserait sinon beaucoup de matière dans votre contexte principal.

Le sous-agent ne voit pas votre conversation. Il part de zéro avec ce que vous lui transmettez. Un brief qui suppose un contexte partagé produit un agent qui travaille sur le mauvais problème, et c’est de loin l’échec le plus fréquent.

Les restrictions d’outils sont l’objectif, pas une limite. Un relecteur en lecture seule qui ne peut pas modifier est plus utile qu’un agent sans restriction, parce que vous pouvez le lancer sans vérifier ensuite ce qu’il a touché.

Les modèles moins chers suffisent souvent. Anthropic cite l’orientation de tâches vers des modèles plus rapides et moins chers comme Haiku parmi les cinq raisons d’utiliser des sous-agents. À 1 dollar par million de jetons d’entrée contre 5 pour Opus 5, une tâche mécanique déléguée à Haiku est une économie réelle sans perte de qualité.

Vous pouvez les désactiver. Pour bloquer un type intégré, ajoutez-le à permissions.deny. Pour couper la délégation entièrement, refusez l’outil Agent lui-même. Pour retirer seulement Explore et Plan, définissez CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, ce qui nécessite Claude Code v2.1.198 ou plus récent et fait lire les fichiers directement à Claude. En mode non interactif et dans l’Agent SDK, CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 supprime tous les types intégrés pour ne laisser que les vôtres.

Un cadre de décision : déléguer ou non

Faites passer une tâche par ces cinq questions avant de lui écrire un agent.

1. Est-ce que cela va générer beaucoup de sortie dont je n’aurai plus besoin ensuite ? Chercher, explorer, lire de nombreux fichiers, parcourir des journaux. Si oui, déléguez : c’est l’argument le plus fort.
2. Faut-il empêcher l’écriture ici ? Relecture, audit, analyse et enquête profitent tous d’un agent en lecture seule, et la restriction constitue justement la valeur.
3. Est-ce assez mécanique pour un modèle moins cher ? Mise en forme, refactorisations mécaniques, recherches simples. Orientez vers Haiku et gardez votre session principale sur le modèle dont vous avez réellement besoin.
4. Vais-je le refaire plus de deux ou trois fois ? Une opération unique ne justifie pas un fichier de définition. Quelque chose d’hebdomadaire si, et la réutilisation se cumule.
5. Puis-je le briefer sans mon historique de conversation ? Si la tâche n’a de sens qu’avec trois heures de contexte accumulé, la délégation vous décevra. Reformulez le brief ou gardez le travail dans le fil principal.

Trois oui ou plus signifient : écrivez l’agent. Moins signifie : faites-le en ligne.

Erreurs courantes en ce moment

• Écrire une description vague, si bien que Claude ne délègue jamais à cet agent ou lui délègue le mauvais travail.
• Donner tous les outils à chaque agent maison, ce qui annule le principal bénéfice de sécurité.
• Déléguer quelque chose de petit, où la surcharge de l’aller-retour dépasse l’économie.
• Supposer que le sous-agent voit la conversation et le briefer en conséquence.
• Bâtir une grande bibliothèque d’agents avant d’avoir établi qu’un seul d’entre eux sert.

Trois agents à écrire en premier

Si vous préférez des points de départ concrets aux principes, ces trois-là rentabilisent leur place dans la plupart des bases de code et prennent quelques minutes chacun.

Un relecteur en lecture seule. Outils limités à Read, Grep et Glob, modèle réglé sur Sonnet, avec un prompt système qui lui demande de signaler les problèmes du code actuel et de proposer un remplacement plutôt que d’apporter des changements. Comme il ne peut pas modifier, vous pouvez le lancer sur n’importe quoi sans vérifier ensuite ce qu’il a touché.

Un enquêteur sur les tests qui échouent. Donnez-lui la capacité d’exécuter des tests et de lire des fichiers, et un prompt lui demandant de trouver la cause racine et de la rapporter plutôt que de réparer quoi que ce soit. La séparation compte : un agent qui diagnostique et rapporte vous laisse décider si la correction vaut la peine, tandis qu’un agent qui diagnostique et corrige vous engage sur sa première hypothèse.

Un vérificateur de documentation sur Haiku. Travail mécanique consistant à comparer ce que la documentation affirme et ce que le code fait. C’est exactement le profil pour un modèle moins cher : gros volume, peu de jugement, sortie facile à vérifier.

Remarquez que deux des trois sont en lecture seule et que le troisième tourne sur le modèle le moins cher. Ce rapport n’est pas un hasard. Les agents qui servent sont ceux qu’on peut lancer sans surveillance ou qui sont assez bon marché pour être lancés souvent.

Où cela s’insère dans un flux plus large

Les sous-agents s’accordent naturellement avec le mode plan. Enquêter dans un agent en lecture seule, rapporter un résumé, planifier contre ce résumé dans la conversation principale, puis exécuter. L’exploration n’entre jamais dans votre contexte principal et le plan repose sur un condensé propre plutôt que sur quarante fichiers de sortie brute.

Ils changent aussi le comportement des longues sessions. L’effet pratique du détournement de l’exploration est qu’une session reste utilisable bien plus longtemps avant que la pression de contexte ne la dégrade, ce qui, pour quiconque avance sur une tâche importante, vaut davantage que l’économie de jetons.

Construire le jugement derrière la configuration

La mécanique de cette page s’apprend en vingt minutes. Ce qui prend plus longtemps, c’est de savoir quel travail déléguer, comment briefer un agent pour que sa sortie soit exploitable, et quand une restriction améliore un résultat au lieu de le limiter.

C’est le même jugement qui vaut pour tout outil à agents : découper une tâche en morceaux réalisables indépendamment, spécifier chacun pour que la sortie soit vérifiable, et concevoir l’étape de relecture qui attrape ce qui dérape. L’apprendre dans une séquence structurée plutôt qu’à tâtons produit une méthode qui tient quand l’outillage change, ce qui dans ce domaine arrive régulièrement. Si vous voulez une entrée structurée, explorez les leçons de Coursiv et vérifiez les détails de forfait en vigueur sur le site officiel.

Questions fréquentes

Votre prochaine étape

Prenez l’investigation que vous menez le plus souvent, celle où vous finissez par lire une douzaine de fichiers pour répondre à une question récurrente, et écrivez-lui un agent en lecture seule avec tools: Read, Grep, Glob et une description qui précise quand l’employer. Lancez-le une fois et comparez l’état de votre conversation principale ensuite avec une session où vous auriez fait la même recherche en ligne. Cette seule comparaison plaide pour la délégation mieux que n’importe quelle explication du mécanisme.