Partie 11 · Claude qui agit pour toi
Subagents Claude Code, déléguer une mission sans polluer ta conversation
Tu sauras quand spawner un subagent, comment le configurer, et pourquoi cette technique économise contexte et coût.
Il arrive un moment où une seule conversation ne suffit plus pour tout faire en même temps. C'est exactement le problème que résolvent les subagents dans Claude Code, le terminal officiel d'Anthropic qui fait travailler Claude sur ton ordinateur.
Tu lui demandes de lire un fichier, il le lit. Tu lui demandes d'écrire du code, il l'écrit. Tu lui demandes d'explorer un projet de 500 fichiers, il l'explore.
Mais tu rencontres un problème sur cette dernière tâche. Quand Claude explore 500 fichiers, il remplit ta conversation principale avec des centaines de résultats que tu n'utiliseras plus jamais.
Tu perds le contexte utile (ta vraie demande, les décisions prises) sous la masse des sorties intermédiaires. Anthropic a créé les subagents pour résoudre exactement ce problème.
En 10 minutes de lecture, tu comprends ce qu'est un subagent, quand l'utiliser, et tu sais le configurer dans un fichier de quelques lignes. Ce guide s'adresse à toute personne qui a déjà installé Claude Code et qui veut tirer parti de ses fonctionnalités avancées.
Tu lis le chapitre 61 d'un manuel de 67 chapitres disponible sur claude-pour-les-debutants.fr.
Ce qu'est un subagent
Tu peux voir un subagent comme un assistant spécialisé. Tu lui confies une mission, il part travailler seul, et il revient avec juste un rapport synthétique.
Claude principal (celui avec qui tu parles dans ton terminal) reçoit ta demande. Si la tâche nécessite une exploration lourde, Claude principal décide de déléguer à un subagent.
Le subagent reçoit la mission, travaille dans son propre contexte isolé, et retourne uniquement un résumé. Ta conversation principale reste propre.
✦ Tu gardes ton contexte utile pour les vraies décisions, pas pour les centaines de logs intermédiaires.
✦ Tu peux limiter les outils auxquels le subagent a droit, ce qui te protège contre les actions involontaires.
✦ Tu peux router le subagent vers un modèle moins cher (Haiku) pour les tâches répétitives, ce qui réduit ton coût.
→ Tu transformes Claude d'un assistant unique en une petite équipe spécialisée.
Quand utiliser un subagent
Tu utilises un subagent dans trois cas typiques.
Premier cas, l'exploration massive. Tu demandes à Claude de chercher tous les endroits dans ton code qui appellent une fonction donnée.
La recherche peut renvoyer 50 résultats avec leurs contextes. Tu n'as besoin que de la liste finale, pas des 50 fichiers complets.
Un subagent fait la recherche dans son contexte, te renvoie la liste, et libère ta conversation.
Deuxième cas, tu as une tâche spécialisée à répéter. Tu veux qu'un debugger expert intervienne chaque fois qu'un test plante.
Tu crées un subagent "debugger" avec un prompt système focalisé sur le diagnostic. Claude principal sait qu'il doit l'invoquer dans ce cas précis.
Troisième cas, tu veux optimiser le coût. Tu fais classer 1000 commentaires Instagram par sentiment.
Tu ne veux pas brûler Opus pour ça. Tu crées un subagent qui utilise Haiku, et tu lui délègues la tâche.
↳ Tu ne crées pas un subagent pour les petites tâches ponctuelles. Si tu demandes une seule chose simple, Claude principal s'en occupe sans déléguer.
Comment Claude principal choisit
Anthropic a mis en place un mécanisme simple pour le routage.
Quand tu crées un subagent, tu écris une description claire de quand l'utiliser. Claude principal lit cette description et il décide automatiquement de déléguer si la tâche correspond.
Tu peux aussi forcer l'invocation manuellement en tapant /nom-du-subagent dans ton terminal.
▸ Exemple de description claire : "Utilise ce subagent pour reviewer une pull request en checkant correctness, style, et sécurité."
▸ Exemple de description vague qui ne marche pas : "Aide à coder."
Plus la description est précise, plus Claude principal délègue au bon moment.
Différence avec les autres patterns
Tu peux confondre subagent avec deux autres concepts proches, donc tu dois bien distinguer.
Les subagents travaillent dans une session unique. Ils reçoivent la tâche, ils l'exécutent, ils retournent au thread principal.
Tu peux les voir comme des fonctions appelées à l'intérieur d'une conversation.
Les background agents sont des agents qui tournent en parallèle dans plusieurs sessions indépendantes. Tu les monitores depuis un endroit unique.
C'est utile pour lancer 10 explorations différentes en même temps et récupérer les résultats au fur et à mesure.
Les agent teams sont des sessions qui communiquent entre elles. Chacune a sa propre conversation, mais elles peuvent se passer des messages.
C'est le pattern le plus avancé, utile pour des workflows multi-rôles.
→ Pour 80 pour cent des cas, tu veux des subagents simples, pas un team complexe.
La structure d'un fichier subagent
Tu définis un subagent avec un fichier markdown qui contient un en-tête de configuration et un prompt système.
---
name: code-reviewer
description: Review une pull request pour correctness, style, et sécurité. Utilise quand l'utilisateur demande de relire du code.
tools: [Read, Grep, Glob, Bash(git diff *), Bash(gh pr *)]
model: sonnet
---
Tu es un reviewer de code senior avec 10 ans d'expérience. Quand tu
reviewes une pull request, tu vérifies trois axes dans cet ordre :
1. Correctness : le code fait-il ce qu'il prétend faire ? Y a-t-il
des bugs évidents ou des cas limites non gérés ?
2. Style : le code respecte-t-il les conventions du projet ?
3. Sécurité : y a-t-il des risques (injection SQL, secrets en dur,
permissions trop larges) ?
Tu rends un rapport structuré en 3 sections (Correctness / Style /
Sécurité). Pour chaque finding, tu cites le fichier et le numéro
de ligne. Si tu ne trouves aucun problème dans un axe, tu écris
explicitement "Aucun problème détecté".
Tu remarques quatre champs dans l'en-tête. Tu utilises le champ name pour invoquer le subagent manuellement avec une commande slash comme /code-reviewer.
Tu utilises le champ description pour aider Claude principal à décider quand déléguer. Tu utilises le champ tools pour limiter les outils auxquels le subagent a droit (par défaut, il hérite de tous les outils du parent).
Tu utilises le champ model pour router vers un modèle plus rapide ou moins cher.
Où ranger tes subagents
Tu disposes de deux emplacements possibles selon que tu veux partager le subagent ou le garder personnel.
Si tu veux que le subagent soit disponible uniquement pour un projet précis, tu le mets dans .claude/agents/ à la racine de ce projet. Les autres personnes qui clonent le projet récupèrent automatiquement le subagent.
C'est le bon choix pour des subagents qui parlent de la codebase spécifique (ex : un debugger qui connaît tes conventions internes).
Si tu veux que le subagent soit disponible pour tous tes projets sur ta machine, tu le mets dans ~/.claude/agents/. Il reste local à ta machine et ne se partage pas.
C'est le bon choix pour des subagents généralistes que tu utilises partout (ex : un code-reviewer qui marche pour n'importe quel langage).
↳ Tu peux avoir des subagents avec le même nom dans les deux emplacements. Le subagent du projet prend toujours la priorité sur le subagent utilisateur.
Trois exemples concrets à copier
Tu peux démarrer avec ces trois subagents prêts à l'emploi.
Le premier est un debugger qui prend un test qui plante et propose un fix.
---
name: debugger
description: Diagnostique pourquoi un test plante et propose un fix minimal. Utilise quand l'utilisateur partage une erreur de test.
tools: [Read, Grep, Glob, Bash(pytest *), Bash(python *)]
model: sonnet
---
Tu es un debugger expert. Quand tu reçois une erreur de test :
1. Lis le test qui plante (chemin + numéro de ligne).
2. Lis le code source que ce test couvre.
3. Lance le test isolément pour confirmer l'erreur.
4. Propose un fix minimal qui passe le test sans casser les autres.
5. Vérifie en relançant tous les tests du fichier.
Tu rends ton rapport en 4 sections : Diagnostic, Cause racine,
Fix proposé, Validation.
Le deuxième est un explorateur qui cartographie un projet inconnu.
---
name: explorer
description: Cartographie un projet inconnu et produit une vue d'ensemble. Utilise quand l'utilisateur ouvre un nouveau repo.
tools: [Read, Grep, Glob, Bash(ls *), Bash(tree *)]
model: haiku
---
Tu es un explorateur de codebase. Quand tu reçois un projet :
1. Liste les fichiers principaux (README, package.json, requirements.txt).
2. Identifie le langage et le framework principal.
3. Repère les répertoires importants (src, tests, docs, scripts).
4. Identifie les 3 fichiers d'entrée les plus probables.
Tu rends un rapport synthétique de 15 lignes maximum.
Le troisième est un security-auditor qui cherche les risques.
---
name: security-auditor
description: Audit de sécurité du code. Utilise avant un déploiement en production ou sur demande explicite.
tools: [Read, Grep, Glob, Bash(grep *)]
model: opus
---
Tu es un security auditor senior. Tu cherches dans le code :
1. Secrets en dur (clés, tokens, mots de passe).
2. Injections possibles (SQL, command injection, XSS).
3. Permissions trop larges (fichiers world-writable, endpoints sans auth).
4. Dépendances obsolètes avec CVEs connues.
Tu rends un rapport classé par sévérité (CRITICAL, HIGH, MEDIUM, LOW).
Pour chaque finding, tu cites le fichier, la ligne, et tu proposes un fix.
Le piège du subagent qui floode quand même
Tu peux mal configurer un subagent et perdre tout l'avantage.
Si tu donnes à ton subagent l'instruction "explique tout ce que tu trouves en détail", il te renvoie un pavé de 500 lignes au lieu d'un résumé synthétique. Tu n'as rien gagné par rapport à laisser Claude principal faire la tâche.
✦ La règle d'or, c'est de toujours préciser dans le prompt système du subagent que la sortie doit être une synthèse courte et structurée, pas un brain dump.
→ Un bon subagent renvoie 10 à 30 lignes structurées, pas 500 lignes de logs bruts.
Un dernier mot
Tu n'as pas besoin de subagents pour utiliser Claude Code au quotidien.
Pour les tâches simples (un fichier à lire, une fonction à corriger, un script à écrire), Claude principal te suffit. Tu sors les subagents quand tu sens que ta conversation se charge de logs intermédiaires que tu n'utiliseras plus, ou quand tu veux router une tâche répétée vers un modèle moins cher.
La règle, c'est de commencer simple et d'ajouter des subagents au fur et à mesure que tes workflows se stabilisent.
→ Essaie Claude maintenant : claude.ai
→ Chapitre suivant : Routines Claude, l'automatisation qui tourne sans toi
Ce chapitre t'a aidé ?
Sois le premier à donner ton avis.