Un subagent Claude Code est un assistant IA secondaire qui tourne dans sa propre fenêtre de contexte, avec son propre system prompt, sa propre liste d'outils et ses propres permissions. Quand une tâche annexe (fouiller la codebase, relire un diff, chercher une info) risque d'inonder votre conversation principale de résultats que vous ne relirez jamais, Claude délègue ce travail à un subagent : il l'exécute à part et ne vous renvoie que le résumé. Les Claude Code subagents servent donc deux choses à la fois : garder votre contexte propre, et confier une sous-tâche à un ouvrier spécialisé que vous contraignez (outils limités, modèle moins cher). Voici ce qu'est un subagent, comment en créer un, quand préférer un subagent à un skill ou un hook, et trois cas d'usage concrets quand on build en solo.
Qu'est-ce qu'un subagent Claude Code ?
Un subagent est un travailleur que Claude convoque pour une mission précise, puis renvoie une fois le travail fait. La différence avec Claude lui-même tient en un mot : l'isolement. Chaque sous-agent Claude Code a sa propre fenêtre de contexte. Ce qu'il lit, fouille, teste reste chez lui. Votre conversation principale ne reçoit que sa conclusion.
Ça règle un problème très concret. Quand vous demandez à Claude « où est gérée l'authentification dans ce projet ? », il ouvre dix fichiers, lit trois mille lignes, et tout ça reste dans votre contexte, même quand vous êtes passé à autre chose. Un subagent Explore fait la même recherche dans sa bulle et vous rend trois lignes : le fichier, la fonction, le point d'entrée. Le bruit reste dehors.
Claude Code arrive avec des subagents fournis d'office :
- Explore : agent rapide en lecture seule, pour chercher et comprendre une codebase. Write et Edit lui sont interdits.
- Plan : agent de recherche utilisé en plan mode pour rassembler du contexte avant de proposer un plan. Lecture seule aussi.
- general-purpose : agent complet, tous les outils, pour les tâches qui mêlent exploration et modification.
Au-delà de ces trois, vous écrivez les vôtres. Et c'est là que le subagent devient un levier, parce qu'un subagent custom vous laisse régler quatre choses que Claude ne règle pas seul : quel modèle il utilise, quels outils il a le droit d'employer, quelles permissions il obtient, et quel comportement adopter (via son system prompt). Vous voulez un relecteur de code qui ne peut rien modifier et tourne sur un modèle bon marché ? Vous le décrivez, il existe.
C'est aussi un outil de coût. Router une tâche mécanique vers un modèle plus rapide et moins cher comme Haiku, plutôt que de la faire tourner sur le modèle qui pilote votre session, ça se paramètre en une ligne. Quand on compte chaque euro d'API, ce n'est pas un détail.
Subagent vs skill vs hook : lequel utiliser quand
Trois mécanismes d'extension de Claude Code, souvent confondus, qui ne font pas du tout la même chose. Le tableau d'abord, l'explication ensuite.
| Mécanisme | Ce que c'est | Contexte | Quand l'utiliser |
|---|---|---|---|
| Subagent | Un travailleur IA délégué, avec sa propre fenêtre de contexte | Isolé du vôtre | Une sous-tâche lourde (recherche, revue) dont vous ne voulez que le résultat |
| Skill | Des instructions ou une procédure que Claude charge | Dans votre contexte principal | Apprendre à Claude comment faire quelque chose de récurrent |
| Hook | Un script déclenché automatiquement sur un événement | Hors IA, déterministe | Garantir une action (formater, bloquer) à chaque fois, sans faillir |
La distinction se joue sur deux axes : l'isolement du contexte et le degré de contrôle.
Un skill vit dans votre contexte. Il charge des instructions que Claude applique pendant votre conversation. C'est une compétence à la demande, mais elle raisonne avec vous, dans la même bulle. Si la tâche va générer beaucoup de bruit (des logs, des fichiers), le skill le déverse chez vous.
Un subagent vit à côté. Il prend la même procédure, mais l'exécute dans sa propre fenêtre et ne rend que le résumé. La règle simple : si vous voulez juste que Claude sache faire un truc, c'est un skill. Si vous voulez qu'il aille le faire ailleurs et revienne avec la réponse, c'est un subagent. Les deux se combinent d'ailleurs : un subagent peut précharger un skill comme matériel de référence.
Un hook n'est pas de l'IA du tout. C'est un script que Claude Code exécute automatiquement à un moment précis (avant qu'un outil tourne, après une édition). Il ne décide pas, il s'exécute. Là où un subagent est un collaborateur intelligent mais faillible, un hook est une garantie mécanique : il se déclenche à chaque fois, sans jugement. Vous voulez qu'un formateur passe après chaque édition, sans exception ? Hook, pas subagent.
Structurer et créer un subagent
Un subagent est un simple fichier Markdown avec du frontmatter YAML. Le frontmatter configure le sous-agent, le corps devient son system prompt. Vous pouvez le créer de deux façons : demander à Claude de l'écrire pour vous (le plus rapide), ou écrire le fichier à la main.
Voici à quoi ressemble un relecteur de code, à enregistrer dans ~/.claude/agents/code-reviewer.md :
---
name: code-reviewer
description: Relit le code pour la qualité et les bonnes pratiques. À utiliser après avoir écrit ou modifié du code.
tools: Read, Grep, Glob
model: sonnet
---
Tu es un relecteur de code. Quand on t'invoque, analyse le code et donne un retour précis et actionnable sur la qualité, la sécurité et les bonnes pratiques.
Deux champs seulement sont obligatoires : name et description. C'est la description qui dit à Claude quand déléguer, exactement comme pour un skill. L'emplacement décide de la portée : .claude/agents/ pour un subagent lié à un projet (commitez-le, votre équipe en profite), ~/.claude/agents/ pour un subagent perso dispo sur tous vos projets. Petit piège à connaître : si le dossier agents/ n'existait pas au démarrage de la session, redémarrez Claude Code pour qu'il le détecte. Sinon, la détection est live : modifiez un fichier d'agent existant, et la délégation suivante utilise la version à jour en quelques secondes, sans redémarrage.
Un point important sur le fonctionnement. Un subagent ne reçoit que son system prompt (le corps du fichier) et quelques infos d'environnement comme le répertoire de travail. Il n'hérite ni de votre historique de conversation, ni du system prompt complet de Claude Code. C'est précisément ce qui le rend léger et prévisible : il part propre, avec les seules instructions que vous lui donnez. Le corollaire, c'est que le corps du fichier doit se suffire à lui-même. Un system prompt vague donne un agent vague.
Le champ model mérite aussi un mot. Par défaut un subagent hérite du modèle de votre session, mais vous pouvez le fixer : model: sonnet pour un relecteur soigné, model: haiku pour un agent de corvée que vous ne voulez pas payer au prix fort. Ce réglage à une ligne est votre principal levier de coût.
Invocation automatique vs manuelle
Un subagent se déclenche de deux manières. Automatique : Claude lit sa description et délègue tout seul quand la tâche correspond (« relis mes changements » réveille le code-reviewer). Manuelle : vous le convoquez explicitement, en le mentionnant avec @ ou en écrivant « utilise l'agent code-reviewer sur ce projet ». La règle qui compte : une bonne description, avec les mots que vous diriez vraiment, c'est ce qui fait qu'un subagent se déclenche au bon moment. Une description vague, et Claude l'ignore.
Scoper les outils (principe du moindre privilège)
Par défaut, un subagent hérite de tous les outils de la conversation principale. C'est rarement ce que vous voulez. Deux leviers pour cadrer :
toolsagit comme une liste blanche : vous ne listez que ce qu'il a le droit d'utiliser. Notre code-reviewer n'a queRead, Grep, Glob, donc il ne peut rien modifier. Impossible qu'une relecture tourne en réécriture non voulue.disallowedToolsagit comme une liste noire : vous partez de tout et vous retirez le dangereux.
Ce réflexe (donner à chaque agent le strict nécessaire) n'est pas de la paranoïa, c'est du bon sens opérationnel. Un agent qui ne peut pas écrire ne peut pas casser votre code par accident. Un agent de recherche à qui vous refusez le shell ne lancera jamais une commande de travers.
Notez aussi que certains outils ne sont jamais accessibles à un subagent, même listés dans tools : ceux qui dépendent de l'interface de votre session, comme la possibilité de vous poser une question en direct. Un subagent travaille en autonomie. Il ne peut pas s'arrêter en cours de route pour vous demander votre avis, il va au bout de sa mission et rend son résultat. C'est une contrainte à intégrer quand vous écrivez son system prompt : donnez-lui de quoi trancher seul, pas de quoi hésiter.
3 cas d'usage founder concrets
La théorie ne vaut rien tant qu'on ne l'a pas branchée sur votre quotidien de founder qui build. Trois usages où le subagent gagne du temps réel.
Revue de code en parallèle
Vous êtes seul dev, personne pour relire vos pull requests. Un subagent code-reviewer en lecture seule, sur un modèle correct, fait ce boulot : il relit votre diff, signale la gestion d'erreur manquante, les valeurs codées en dur, les tests à mettre à jour. Il tourne dans son coin, votre contexte principal reste propre, et vous récupérez une revue au lieu de merger à l'aveugle.
Recherche pendant que vous buildez
Vous codez une feature et vous avez besoin de comprendre comment un autre module marche, sans polluer votre session en cours. Un subagent Explore va fouiller, lire, cartographier dans sa bulle, et vous rend l'essentiel : les fichiers concernés, la logique, le point d'entrée. Vous gardez votre fil, la recherche se fait à côté. Bon à savoir : quand Claude convoque Explore, il choisit un niveau de profondeur selon le besoin, du lookup ciblé à l'analyse très fouillée. Vous n'avez pas à le régler à la main, mais vous pouvez le demander explicitement quand vous voulez une exploration exhaustive avant une grosse décision d'architecture.
Troisième usage, le plus sous-estimé : le travail mécanique routé sur un modèle bon marché. Générer des tests répétitifs, renommer à travers des fichiers, produire de la doc : confiez ça à un subagent en model: haiku. Vous gardez votre modèle puissant pour l'architecture, et vous ne payez pas le prix fort pour de la corvée. Sur un budget d'API de startup, ce simple aiguillage change la facture du mois.
Vers les Agent Teams
Un subagent a une limite : il travaille dans une seule session, et Claude ne délègue qu'une sous-tâche à la fois avant de récupérer la main. Ça suffit pour 90% des cas. Mais quand vous attaquez un chantier qui demande du parallélisme soutenu, plusieurs travailleurs qui avancent en même temps sur des morceaux différents, ou des agents qui doivent communiquer entre eux, vous sortez du cadre du subagent.
C'est là qu'interviennent les Agent Teams, une brique distincte de Claude Code où chaque travailleur a sa propre fenêtre de contexte indépendante et où les agents peuvent s'échanger des messages. Bonne nouvelle : vos définitions de subagents sont réutilisables sur ce terrain. Quand vous montez une équipe, vous pouvez référencer un type de subagent existant, et le coéquipier reprend ses outils et son modèle. Le travail que vous mettez à structurer vos subagents ne se jette pas, il devient la brique de vos équipes.
La progression logique, pour un founder : commencez par un ou deux subagents (un relecteur, un chercheur), prenez le réflexe de déléguer, et ne montez en Agent Teams que le jour où une seule session ne suffit plus à tenir le chantier.
Pour aller plus loin
FAQ
Qu'est-ce qu'un subagent dans Claude Code ?
Un subagent est un assistant IA spécialisé qui tourne dans sa propre fenêtre de contexte, avec un system prompt custom, des outils spécifiques et des permissions indépendantes. Claude lui délègue une sous-tâche (recherche, revue, débogage), il l'exécute à part et ne renvoie que le résumé. Ça garde votre conversation principale propre et permet de contraindre finement ce que l'agent peut faire.
Quelle différence entre un subagent et un skill ?
Un skill charge des instructions dans votre contexte principal : il apprend à Claude comment faire quelque chose. Un subagent exécute la tâche dans un contexte isolé et ne rend que le résultat. Règle simple : si vous voulez que Claude sache faire un truc, c'est un skill ; si vous voulez qu'il aille le faire ailleurs et revienne avec la réponse, c'est un subagent. Les deux se combinent, un subagent pouvant précharger un skill.
Comment créer un subagent Claude Code ?
Le plus rapide est de demander à Claude de l'écrire pour vous en décrivant ce que vous voulez et où l'enregistrer. Sinon, créez à la main un fichier Markdown avec frontmatter YAML dans ~/.claude/agents/ (perso, tous projets) ou .claude/agents/ (un seul projet). Seuls name et description sont obligatoires ; ajoutez tools, model et un system prompt dans le corps.
Comment limiter les outils d'un subagent ?
Utilisez le champ tools comme liste blanche pour n'autoriser que certains outils (par exemple Read, Grep, Glob pour un agent en lecture seule), ou disallowedTools comme liste noire pour retirer les outils dangereux. Sans ces champs, le subagent hérite de tous les outils de la session. Le principe du moindre privilège évite qu'un agent casse votre code par accident.
Subagents ou Agent Teams : lequel choisir ?
Les subagents suffisent pour déléguer une sous-tâche à la fois dans une seule session. Passez aux Agent Teams quand vous avez besoin de plusieurs travailleurs en parallèle, sur des contextes indépendants, qui communiquent entre eux. Vos définitions de subagents sont réutilisables comme briques d'une équipe.
