Agents secondaires Claude Code : configuration, paramétrage et cas d’utilisation

La plupart des sessions Claude Code deviennent lentes et encombrées pour la même raison : chaque grep exploratoire, chaque vidage de journal et chaque « laissez-moi vérifier un dernier fichier » restent dans la conversation principale pour toujours.

Les sous-agents existent pour résoudre exactement ce problème. Ils sont l’un des primitives d’agent intégrés à Claude Code pour gérer le travail bruyant et parallélisable — un moyen de déporter le désordre dans une fenêtre isolée et de ne ramener que le résumé qui compte.

Un sous-agent n’est pas un Claude plus intelligent, et ce n’est pas la même chose qu’une Compétence (Skill). C’est un agent de raisonnement séparé avec sa propre fenêtre de contexte, sa propre liste d’outils autorisés, et aucune mémoire de votre conversation actuelle à moins que vous ne le forkiez explicitement. Comprendre cette distinction fait la différence entre une configuration de sous-agent qui économise discrètement votre budget de contexte et une autre qui ajoute simplement de la latence sans aucun avantage.

Sous-agents vs Compétences vs MCP

Claude Code vous offre trois points d’extension qui résolvent des problèmes différents, et ils sont constamment confondus parce que les trois peuvent techniquement « aider avec une tâche ».

Une règle empirique utile : un hook impose une contrainte dure de manière déterministe, une Compétence donne à l’agent principal une capacité en ligne, et un sous-agent est destiné au travail que vous voulez déléguer et garder complètement hors du contexte principal. Si le travail d’une Compétence est d’orchestrer un outil qui n’existe pas encore, c’est généralement un signe que vous avez besoin d’un serveur MCP, pas d’un sous-agent. Claude Code n’est pas seul dans cette forme — l’écosystème d’OpenCode a une idée comparable avec ses agents spécialisés, qui séparent la planification, la recherche et la révision à travers des rôles dédiés d’une manière similaire.

Ce qu’est vraiment un sous-agent

Trois propriétés définissent un sous-agent Claude Code, et les trois sont importantes pour la façon dont vous l’utilisez :

• Contexte isolé. Un sous-agent commence avec une fenêtre fraîche. Il ne voit pas l’historique de votre conversation à moins que vous ne le forkiez explicitement, ce qui empêche sa sortie d’être polluée par ce que vous avez discuté il y a trois tours.
• Une liste d’outils autorisés restreinte. Les sous-agents ne peuvent utiliser qu’un sous-ensemble de ce que la session parente possède déjà — ils ne peuvent pas s’octroyer de nouvelles capacités, et un sous-agent bien conçu ne devrait recevoir que les outils nécessaires à son travail (outils en lecture seule pour un agent de recherche, par exemple).
• Aucune visibilité entre sous-agents. Les sous-agents ne peuvent pas voir le travail en cours des autres. Si la tâche B a réellement besoin de la sortie de la tâche A, c’est une dépendance séquentielle, pas quelque chose que vous pouvez paralléliser entre deux sous-agents.

Le déclencheur pour utiliser l’un n’est pas « cette tâche est difficile ». C’est « cette tâche est bruyante » — le genre de travail qui génère beaucoup de sortie intermédiaire (des dizaines de lectures de fichiers, un long journal, un grep exploratoire sur tout le dépôt) où aucun de ce matériel intermédiaire n’a besoin de survivre dans votre prochain tour de conversation.

Quand utiliser un sous-agent (et quand ne pas le faire)

Bons cas d’utilisation : exploration de la base de code avant un grand changement, exécutions de tests automatisés où vous ne vous souciez que du succès/échec et des résumés des erreurs, revues de sécurité ou de style, et toute tâche de recherche en plusieurs étapes dont la sortie brute inonderait autrement votre session principale.

Mauvais cas d’utilisation : recherches de deux secondes (« que retourne cette fonction »), tout ce qui nécessite une refinement serré aller-retour, et des tâches dépendantes que vous êtes tenté de « paralléliser » même si la deuxième a besoin de la réponse de la première. Utiliser un sous-agent pour une recherche triviale ajoute simplement la surcharge de démarrer une nouvelle fenêtre de contexte sans réel avantage d’isolation.

Mesurer le rendement : mathématiques du contexte et des coûts

Le discours sur les sous-agents est abstrait jusqu’à ce que vous mettiez des chiffres sur une tâche réelle. Prenons une courante : faire un grep sur un service d’environ 500 fichiers pour chaque endroit où une clé de configuration obsolète est encore lue, puis rapporter les correspondances exactes fichier:ligne.

C’est une réduction d’environ 15 à 20 fois de ce que votre session principale doit porter pour cette étape, ce qui est le mécanisme réel derrière « les sous-agents gardent les sessions plus rapides » — ce n’est pas de la magie, c’est du contexte qui n’est jamais chargé en premier lieu.

Le côté coût se compose de la même manière. En utilisant la tarification de la décomposition des prix de Claude Code, exécuter cette même passe d’exploration sur Opus (5 $/MTok entrée, 25 $/MTok sortie) coûte environ 0,20-0,25 $ pour les ~40K jetons d’entrée seuls. Le router vers Haiku (1 $/MTok entrée, 5 $/MTok sortie) réduit cela à 0,04-0,05 $ — et le budget Opus de la session principale n’est jamais touché par les jetons d’exploration, car il ne voit que le résumé de ~2K jetons.

Définir un sous-agent personnalisé

Les sous-agents personnalisés existent en tant que fichiers Markdown avec un frontmatter YAML, soit au niveau du projet dans .claude/agents/ (commité au dépôt, partagé par toute l’équipe) soit au niveau utilisateur dans ~/.claude/agents/ (outils personnels que vous apportez à chaque projet).

---
name: code-reviewer
description: >
  Reviews staged changes for bugs, security issues, and style violations
  before commit. Use when the user asks to review, audit, or check
  changes prior to committing or opening a PR.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
You are a careful code reviewer. Read the staged diff, flag concrete
issues with file:line references, and end with a short pass/fail summary.
Do not modify any files.

Le champ description est la ligne la plus importante du fichier. C’est ce que la logique de routage de la session parente lit pour décider si ce sous-agent convient à la tâche actuelle. Écrivez-le comme une offre d’emploi — nommez la condition de déclenchement explicitement, pas un « aide avec le code » vague. Les descriptions vagues sont ignorées ou mal appliquées par le déploiement automatique.

Le champ tools est votre frontière d’isolation. Donnez à un sous-agent de recherche Read, Grep et Glob et rien d’autre ; lui donner chaque outil disponible annule tout l’intérêt de l’exécuter dans un sandbox restreint. Le champ skills optionnel précharge le contenu complet des Compétences nommées dans le contexte de démarrage du sous-agent — utile lorsqu’un sous-agent a besoin de connaissances de domaine sans passer un tour à les découvrir et les charger en cours de tâche.

Routage des modèles : modèles bon marché pour le travail d’exécution

Les sous-agents sont aussi là où le contrôle des coûts devient réel. Routez la découverte de fichiers, le numérisation de journaux et autres travaux faciles à vérifier vers Haiku, et réservez Sonnet ou Opus pour les étapes lourdes de raisonnement — décisions d’architecture, débogage ambigu, tout ce qui est coûteux si on se trompe. Haiku est environ 15 fois moins cher par jeton que Opus, et sur le genre d’exploration bruyante pour laquelle les sous-agents sont conçus, cet écart s’accumule rapidement au fil d’une session de travail réelle.

Le modèle Explore, Plan, Exécuter

Pour un travail complexe en plusieurs étapes, le modèle qui résiste en pratique est Explore, Plan, Exécuter — en utilisant des sous-agents bon marché pour les parties qui génèrent du bruit, et en gardant la porte de révision humaine au seul endroit où elle compte vraiment.

Le détail clé que les gens inversent est l’endroit où doit se trouver la porte de révision. L’exploration est bon marché, donc laissez un sous-agent lire librement sans demander la permission d’abord. La planification est analytique, donc laissez l’agent concevoir l’approche lui-même. Mais avant que tout agent ne modifie des fichiers, vous voulez voir le plan et l’approuver — c’est pour cela que le mode plan de Claude Code (permissionMode: plan) existe, et c’est le même principe discuté dans les bonnes pratiques de vibe coding autour de la révision de chaque diff avant qu’il ne soit appliqué.

Erreurs courantes

Un certain nombre d’erreurs apparaissent régulièrement une fois que les équipes commencent à écrire des sous-agents personnalisés :

• Descriptions vagues. « Aide avec le code » ne routera jamais correctement. Nommez la condition de déclenchement exacte.
• Accès aux outils trop large. Donner à un sous-agent de recherche en lecture seule l’accès en écriture et à bash supprime la garantie d’isolation qui rendait sa création utile en premier lieu.
• Parallélisation de tâches dépendantes. Si la tâche B a besoin de la sortie finie de la tâche A, exécutez-les séquentiellement — les sous-agents ne peuvent pas coordonner en cours de tâche comme un orchestrateur partagé peut le faire. Pour les flux de travail qui ont réellement besoin d’agents qui se parlent en cours de tâche, c’est une forme différente de problème ; voir modèles d’orchestration multi-agent si vous construisez un système de production plutôt qu’un flux de travail mono-dépôt.
• Utilisation d’un sous-agent pour un travail trivial. « Formate ce JSON » ou « exécute cette commande » n’a pas besoin d’une nouvelle fenêtre de contexte ; faites-le directement.

Exemple détaillé : un sous-agent de revue de code de bout en bout

Disons que vous voulez que chaque commit non trivial soit révisé avant d’être appliqué. Déposez la définition code-reviewer montrée plus tôt dans .claude/agents/code-reviewer.md, committez-la pour que toute l’équipe partage le même réviseur, et invoquez-la avec une demande naturelle comme « révise mes changements en attente avant que je ne committe ». Claude Code associe votre demande à la description du sous-agent, le démarre avec uniquement l’accès Read, Grep et Glob, et il revient avec des découvertes référencées fichier:ligne et un résumé pass/fail — aucun du bruit fichier par fichier pour y arriver ne touche jamais votre session principale.

Ce à quoi cela ressemble dans la transcription principale, annoté :

You:  review my staged changes before I commit

Main: [dispatches code-reviewer subagent — 6 files read, 1 grep pass,
       zero of it shown here]

Main: code-reviewer findings:
      - auth/session.go:142 — token refresh path doesn't handle expired
        refresh token; falls through to nil dereference
      - auth/session.go:203 — style: error wrapped without %w
      PASS/FAIL: FAIL (1 blocking issue)

Six lectures de fichiers et une passe de grep se sont produites, et votre session principale a payé pour exactement quatre lignes de cela. Cet écart — tout ce que le sous-agent a fait versus le résumé en trois lignes que vous voyez réellement — est toute la proposition de valeur en une seule transcription.

Si votre équipe utilise également des échafaudages de développement piloté par spécification (Spec-Driven Development), un sous-agent de révision s’intègre naturellement dans l’étape de validation ; voir GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows pour voir comment cette porte de révision se compare entre les configurations SDD portables et intégrées à l’IDE.

Est-ce que ça vaut le coup de configurer des sous-agents personnalisés ?

Pas dès le premier jour. Le sous-agent généraliste intégré couvre déjà la plupart des délégations d’exploration et de recherche sans que vous n’écriviez un seul fichier YAML, et une seule passe Explore-Plan-Exécuter suffit pour la plupart des travaux quotidiens. Écrivez un fichier personnalisé .claude/agents/*.md seulement une fois que vous avez délégué la même tâche à la main trois fois — un réviseur de code, un triageur de tests, un agent de recherche de docs pour une seule bibliothèque interne. Les équipes qui écrivent cinq sous-agents dans leur première semaine finissent généralement avec cinq champs description périmés que personne ne met à jour lorsque la condition de déclenchement réelle dérive, ce qui casse discrètement le routage automatique des mois plus tard. Commencez avec zéro sous-agents personnalisés, ajoutez-en un à la fois, et seulement lorsque la répétition — pas l’utilité théorique — l’exige.

Limitations connues

Quelques angles rugueux vaut la peine d’être connus avant de construire autour des sous-agents :

• Pas de délégation récursive. Un sous-agent ne peut pas générer ses propres sous-agents. Si une tâche a réellement besoin d’une deuxième couche de délégation, c’est un signe que vous voulez une forme d’orchestration différente — voir modèles d’orchestration multi-agent pour ce à quoi cela ressemble en dehors d’une seule session Claude Code.
• Pas de mémoire entre les invocations. Chaque déploiement commence à zéro, même si vous avez appelé le même sous-agent il y a cinq minutes sur une tâche connexe. Il n’y a pas de mécanisme intégré pour qu’un sous-agent se souvienne de sa dernière exécution.
• L’isolation est une liste d’outils autorisés, pas un sandbox. Un sous-agent avec l’accès Bash peut encore toucher le système de fichiers et le réseau comme tout autre appel d’outil. Restreindre tools réduit le rayon d’explosion ; cela ne crée pas une frontière de sécurité dure.

Dépannage

Le sous-agent ne se déclenche jamais. La description est presque toujours le problème. Réécrivez-la autour de la condition de déclenchement spécifique au lieu d’une déclaration de capacité générale, et vérifiez bien que le fichier se trouve dans .claude/agents/ (projet) ou ~/.claude/agents/ (personnel) avec la bonne extension.

Le sous-agent consomme trop de contexte quand même. Vérifiez la liste d’outils autorisés tools — un ensemble d’outils trop large invite une exploration trop large. Vérifiez également si la tâche aurait dû être divisée en deux sous-agents au lieu d’un seul qui fait tout.

Une compétence listée ne se charge pas dans le sous-agent. Claude Code ignore une compétence manquante ou désactivée nommée dans le champ skills plutôt que d’échouer l’exécution, et journalise une ligne à cet effet dans la sortie de débogage (/debug depuis la session principale, puis reproduisez le déploiement) — quelque chose comme skill "security-checklist" not found, skipping. Exécutez /doctor ensuite pour confirmer que le reste de votre configuration est sain.

Les résultats semblent incohérents entre les exécutions. C’est souvent un problème de routage de modèle, pas un problème de conception de sous-agent — le travail lourd de raisonnement assigné à un modèle bon marché variera plus. Déplacez-le vers Sonnet ou Opus et gardez Haiku pour les étapes déterministes et à faible ambiguïté.

Les sous-agents sont une pièce d’une boîte à outils beaucoup plus large ; si vous comparez Claude Code avec le reste de l’écosystème d’outils de développement IA avant de vous engager dans ce flux de travail, cette vue d’ensemble est une bonne prochaine étape.

Liens utiles

• Installation et configuration de Claude Code pour Ollama, llama.cpp, tarification
• Compétences Claude et SKILL.md pour les développeurs
• GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows
• Qu’est-ce que le Vibe Coding ?
• Modèles d’Orchestration Multi-Agent : Un Guide Pratique
• Plongée Profonde dans les Agents Spécialisés Oh My Opencode
• Outils de Développement IA : Le Guide Complet