Un subagent Claude Code, c’est un deuxième Claude que votre Claude principal envoie faire une tâche isolée et focalisée. Il travaille dans son propre contexte, remonte un résumé, puis disparaît. Vous gardez une conversation principale propre, votre subagent explose la tâche complexe, et tout le monde est content.
Dans ce guide, on voit concrètement à quoi sert un subagent, comment le créer en 3 minutes, quand l’utiliser vraiment (et quand éviter), 5 exemples qui tournent chez moi au quotidien, et comment en paralléliser plusieurs pour cartonner sur de grosses tâches. Tout est testé, rien de théorique.
Subagent, c’est quoi exactement ?
Imaginez que vous êtes chef de projet et que votre patron vous demande un audit complet du projet X. Au lieu de tout faire vous-même, vous déléguez à trois collègues : l’un audite le code, l’un audite la doc, l’un audite les tests. Chacun bosse de son côté, vous remonte un résumé, et vous synthétisez. C’est exactement ce que fait un subagent.
Techniquement, un subagent Claude Code est une instance secondaire du modèle, lancée par l’instance principale via l’outil « Task ». Il reçoit un prompt, dispose de ses propres outils (Read, Grep, Glob, parfois Bash), exécute sa mission, et renvoie une réponse unique au parent. Le parent ne voit que le résultat final, pas le détail de l’exécution du subagent.
Vous définissez les subagents disponibles dans votre dossier .claude/agents/ (au niveau projet) ou dans ~/.claude/agents/ (au niveau utilisateur global). Chaque subagent est un fichier markdown avec un nom, une description, des outils autorisés et un prompt système.
Pourquoi les subagents changent vos workflows
Le gros problème quand on bosse longtemps dans une même session Claude Code : le contexte s’alourdit. Chaque fichier lu, chaque commande lancée, chaque recherche effectuée consomme des tokens. Arrivé à 100k tokens de contexte, les réponses deviennent plus lentes, plus chères, et parfois moins précises.
Les subagents résolvent ce problème en isolant les tâches coûteuses en contexte. Exemple concret : je demande à un subagent « explore-codebase » de chercher toutes les occurrences d’une API dans mon projet. Il charge 40 fichiers, fait 15 greps, puis me renvoie un résumé de 500 tokens. Si je l’avais fait directement, ces 40 fichiers seraient dans mon contexte principal pour le reste de la session.
Trois bénéfices concrets :
- Contexte principal léger : vous gardez la conversation focalisée sur le vrai objectif, sans pollution par les détails d’exploration
- Parallélisation : vous pouvez lancer plusieurs subagents en même temps, chacun sur un morceau indépendant
- Spécialisation : un subagent peut avoir son propre prompt système, ses propres outils, son propre style, optimisé pour un type de tâche
Subagent vs simple appel Task
Claude Code dispose d’un outil « Task » qui peut lancer un agent générique. Quelle différence avec un subagent défini dans .claude/agents/ ?
Task générique : Claude crée à la volée un agent avec votre prompt, les outils par défaut, pas de personnalité particulière. Utile pour des tâches ponctuelles.
Subagent défini : vous avez écrit à l’avance le prompt système, les outils autorisés, la description du périmètre. Vous l’invoquez par son nom. Plus constant, plus reproductible, plus partageable avec l’équipe via Git.
Règle simple : si vous utilisez le même type de tâche plus de 2-3 fois, faites-en un subagent. Si c’est ponctuel, un Task générique suffit.
Créer votre premier subagent (3 minutes)
Créons ensemble un subagent « code-reviewer » qui relit vos changements avant un commit.
Étape 1 : créez le dossier
Si ce n’est pas déjà fait, créez .claude/agents/ à la racine de votre projet :
mkdir -p .claude/agentsÉtape 2 : créez le fichier du subagent
Créez .claude/agents/code-reviewer.md avec ce contenu :
---
name: code-reviewer
description: Relit les changements git et détecte bugs, régressions, problèmes de sécurité. Appeler avant un commit important.
tools: Read, Grep, Glob, Bash
---
Tu es un relecteur de code expérimenté, strict mais constructif.
À l'appel, tu exécutes cette routine :
1. `git diff --staged` pour voir les changements
2. Lis les fichiers modifiés en entier pour comprendre le contexte
3. Identifie : bugs potentiels, régressions, problèmes de sécurité,
typos, tests manquants, code mort, mauvaises pratiques
Remonte un rapport structuré en 4 sections :
- CRITIQUE (à corriger absolument)
- IMPORTANT (à corriger de préférence)
- SUGGESTIONS (optionnel)
- POINTS POSITIFS (pour équilibrer)
Sois concis. Pas de paraphrase du code. Cite les fichiers et lignes.Étape 3 : utilisez-le
Dans Claude Code, vous pouvez maintenant l’invoquer explicitement :
Lance le subagent code-reviewer sur mes changements stagésClaude va démarrer le subagent dans son propre contexte, qui va lancer git diff, lire les fichiers, et remonter son rapport. Tout le détail de son exploration reste dans son contexte à lui, vous ne récupérez que le rapport final.
5 subagents que j’utilise tous les jours
1. explore-codebase
Le plus utilisé. Pour répondre à une question du genre « où est géré l’authentification dans ce projet ? ». Le subagent fait 10 greps, lit les fichiers pertinents, et remonte un plan clair. Économise des milliers de tokens dans le contexte principal.
2. docs-writer
Prend un morceau de code et rédige la doc. Je l’appelle après avoir fini une fonctionnalité, il produit README, JSDoc, guide d’usage. Spécialisé pour un ton pédagogique.
3. test-generator
Regarde une fonction et génère la suite de tests associée. Prompt système très précis : utilise mon framework (Vitest), mon pattern (Arrange-Act-Assert), couvre les cas limites.
4. dependency-auditor
Fait tourner npm audit et npm outdated, identifie les paquets à mettre à jour, évalue le risque, propose une stratégie. Je le lance chaque lundi.
5. pr-summarizer
Prend une branche Git et rédige la description de PR. Regarde les commits, les fichiers modifiés, produit un titre clair et un corps structuré (Summary, Changes, Test plan). Gain de temps énorme.
Ce que vous remarquerez : chaque subagent a UN rôle précis. Ce n’est pas « l’assistant qui fait tout », c’est « le spécialiste de X ». Plus le rôle est focalisé, meilleur est le résultat.
Paralléliser avec plusieurs subagents
Vrai super-pouvoir des subagents : vous pouvez en lancer plusieurs en parallèle. Claude Code les exécute simultanément, attend que tous remontent, et utilise les résultats combinés.
Cas d’usage typique : « audite mon projet sur 3 axes en parallèle : sécurité, performance, accessibilité ». Un subagent par axe, les 3 tournent en même temps, chacun fait son travail pendant que les autres font le leur. Le rapport final combine les 3 retours.
Pour déclencher la parallélisation, il suffit de formuler la demande clairement :
Lance trois subagents en parallèle :
- le premier audite la sécurité (auth, inputs, CORS, secrets)
- le deuxième audite la perf (requêtes lentes, N+1, bundle size)
- le troisième audite l'accessibilité (ARIA, contraste, clavier)Claude va émettre les 3 appels dans le même tour. La réduction de temps est spectaculaire : au lieu de 3 fois 2 minutes, vous attendez 2 minutes total.
Attention : plus vous paralléllisez, plus vous consommez de tokens. Chaque subagent a son propre coût. La parallélisation est géniale pour gagner du temps, pas pour économiser.
Limites et pièges à connaître
Le subagent ne voit pas votre conversation
C’est la règle la plus oubliée. Votre subagent démarre avec le prompt que vous lui donnez ET le CLAUDE.md projet. Il ne voit pas les 30 derniers tours de conversation. Donc pour qu’il comprenne sa mission, votre prompt doit être complet et autonome.
Pas de mémoire entre deux appels
Chaque appel à un subagent crée une instance neuve. Si vous voulez continuer une tâche, relancez un subagent avec le résultat du précédent en contexte. Ce n’est pas un chat persistant.
Le résultat est textuel uniquement
Le subagent ne peut pas modifier votre repo à la place du parent (sauf si vous lui donnez l’outil Edit/Write explicitement). Par défaut, il explore et rapporte. Préservez cette séparation : exploration dans le subagent, action dans le parent.
Coût caché
Un subagent qui lit 50 fichiers, c’est 50 appels read. Ça coûte. Vérifiez que votre subagent est efficient, avec un prompt qui évite le « lit tous les fichiers pour voir ».
Contexte projet
Le subagent hérite du CLAUDE.md du projet. Donc vos conventions, règles dures et stack y sont accessibles. Profitez-en : pas besoin de répéter ces infos dans le prompt du subagent.
Subagent vs Skill : lequel choisir ?
Claude Code propose aussi un système de « Skills ». Question légitime : quand utiliser un subagent, quand utiliser un skill ?
Skill : une procédure pas-à-pas que Claude charge à la demande. Pas d’isolation de contexte. Idéal pour « voici comment faire X dans notre projet » (exemple : « voici comment déployer », « voici comment débugger les emails »). Claude applique les étapes dans votre contexte principal.
Subagent : une mission complète déléguée à une instance séparée. Isolation du contexte. Idéal pour les tâches qui nécessitent beaucoup d’exploration sans polluer la session.
Exemple simple pour choisir : si la tâche nécessite de lire 10+ fichiers pour produire un résultat court, c’est un subagent. Si c’est une procédure à 5 étapes qui modifie votre code, c’est un skill.
Et rien n’empêche de mixer : un skill peut lancer un subagent. C’est même souvent le meilleur pattern sur les workflows complexes.
Questions fréquentes
Combien de subagents puis-je avoir dans un projet ?
Pas de limite dure. J’ai vu des projets avec 15+ subagents spécialisés. L’essentiel est que chacun ait un rôle clair et distinct. Trop de subagents = confusion, Claude ne sait plus lequel invoquer.
Les subagents consomment ils mon abonnement Claude Pro/Max ?
Oui, comme tout appel à Claude Code. Un subagent = une instance du modèle. Son usage est compté dans votre quota, au même titre que la session principale. Plus de subagents en parallèle = consommation plus rapide.
Peut-on versionner les subagents dans Git ?
Oui, c’est recommandé. Les fichiers dans .claude/agents/ sont des markdown standards. Vous les committez, votre équipe en bénéficie, les subagents évoluent en PR comme le reste du code.
Un subagent peut il en appeler un autre ?
Oui, techniquement un subagent peut lancer un Task qui crée un autre subagent. En pratique, je déconseille au-delà de 2 niveaux de profondeur : le coût explose, le temps de réponse aussi, et le débogage devient pénible.
Comment passer des paramètres à un subagent ?
Via le prompt initial. Quand votre Claude principal lance le subagent, il formule une requête : « analyse le fichier X en te focalisant sur Y ». Tout le contexte dont le subagent a besoin doit être dans ce prompt.
Les subagents fonctionnent ils dans Claude Desktop ?
Oui, les subagents sont une feature du runtime Claude Code, disponible dans Claude Code CLI, Claude Desktop et les extensions IDE qui embarquent Claude Code. Le SDK Claude Agent expose aussi cette capacité pour vos apps custom.
Quelle différence avec les « agents » classiques des outils comme LangGraph ?
LangGraph et consorts proposent des frameworks multi-agents souvent pour des pipelines longs et autonomes. Les subagents Claude Code sont plus légers, embarqués nativement, optimisés pour des tâches courtes isolées dans le même workflow développeur. Les deux approches sont complémentaires mais ne couvrent pas les mêmes cas.
En résumé
Les subagents sont un levier de productivité énorme dès qu’on travaille sur des projets qui commencent à peser. Contexte principal propre, parallélisation, spécialisation : trois bénéfices qui se cumulent.
Commencez simple : créez UN subagent aujourd’hui (le code-reviewer est un excellent point de départ), utilisez-le une semaine, mesurez l’impact. Vous en aurez 5 avant la fin du mois, et vous ne pourrez plus vous en passer.
Pour creuser les autres briques avancées de Claude Code, voyez notre guide complet Claude Code qui couvre CLAUDE.md, Plan Mode, MCP, hooks et workflows avancés.
Articles similaires
Dans la catégorie Claude