Sous-agents Claude Code : le guide pratique (2026)

Un sous-agent est un deuxième Claude, lancé par votre session Claude Code principale, qui exécute une tâche dans sa propre fenêtre de contexte et renvoie un résultat. Il ne partage pas votre historique de conversation. Il ne voit pas les fichiers que vous avez déjà lus ni les décisions que vous avez déjà prises. Il reçoit un prompt, fait le travail, et revient.

Cette isolation est toute la fonctionnalité. Le parallélisme, la spécialisation, les restrictions d'outils personnalisées, tout cela découle d'un seul fait : un sous-agent consomme sa propre fenêtre de contexte et seule la réponse finale revient dans la vôtre.

Nous faisons tourner des dizaines de sous-agents par jour en construisant SkillProof, surtout pour l'éventail de recherche et les corrections indépendantes à travers les fichiers de données du catalogue. Certaines de nos leçons sont réellement utiles. D'autres, nous les avons apprises en regardant un agent revendiquer une victoire sur un travail qu'il n'a jamais fait. Les deux genres sont dans ce guide.

Ce qu'est réellement un sous-agent

Dans Claude Code, la session principale est une boucle : lire, penser, agir, observer, répéter, chaque étape s'ajoutant à une conversation qui grandit. Un sous-agent est une instance séparée de cette même boucle, démarrée en cours de session, avec son propre historique qui commence vide sauf pour le prompt que vous lui donnez.

Quand le sous-agent termine, rien de son travail intermédiaire ne voyage en retour. Pas les fichiers qu'il a lus, pas les commandes qu'il a exécutées, pas les impasses qu'il a explorées. Seul le texte qu'il choisit de retourner atterrit dans votre contexte principal. S'il a lu 40 fichiers pour répondre à votre question, votre session principale ne paie pour aucune de ces 40 lectures. Elle paie pour un résumé.

C'est pourquoi les sous-agents sont décrits comme un moyen de préserver le contexte : non pas parce que le travail est gratuit (il coûte les mêmes tokens quelque part), mais parce que le coût est mis en quarantaine dans une fenêtre qu'on jette, pas une qu'on continue de traîner dans le reste de la session.

Le compromis en découle directement. Un sous-agent qui ne sait pas ce que vous avez déjà essayé peut répéter vos propres impasses, et il ne peut pas poser une question de clarification en cours de tâche comme peut le faire la boucle principale, il a soit assez d'éléments dans le prompt pour avancer, soit il devine. Déléguer achète l'isolation et coûte la mémoire partagée. Chaque bon prompt de sous-agent est écrit par quelqu'un qui a intégré ce compromis.

Pourquoi l'isolation du contexte est le point central

Imaginez une session principale deux heures dans un refactoring : quarante fichiers lus, une douzaine d'appels d'outils, une décision de design revisitée deux fois. Cet historique fait un vrai travail, c'est ce qui rend la prochaine édition cohérente, mais c'est aussi cinquante mille tokens de lest.

Maintenant vous avez besoin de savoir comment un sous-système sans rapport gère les retries. Lisez ces fichiers dans la boucle principale et chacun devient un bagage permanent, voyageant dans le contexte pour le reste de la session que vous le réutilisiez ou non, jusqu'à faire partie de la raison pour laquelle le modèle commence à perdre le fil du vrai refactoring. Un sous-agent vous permet de poser la question, d'obtenir la réponse, et de vous éloigner de la lecture. Les quarante fichiers qu'il a lus n'entrent jamais dans votre fenêtre. Vous récupérez un paragraphe.

C'est le mécanisme derrière chaque victoire légitime de sous-agent dans ce guide : recherche, corrections parallèles, exploration bruyante. Tous ces cas sont en réalité le même mouvement, faire la lecture coûteuse quelque part de jetable, garder le fil principal propre.

Quand les sous-agents battent le travail dans la boucle principale

La recherche à travers de nombreux fichiers. « Comment l'authentification circule dans cette base de code » touche les routes, le middleware, le stockage de session, et trois fichiers de config. Répondre à cela dans la boucle principale veut dire que tout cela atterrit dans votre contexte de façon permanente. Un sous-agent lit les mêmes fichiers, renvoie une synthèse, et le matériel brut disparaît avec lui.

Les tâches indépendantes en parallèle. Cinq composants ont chacun besoin du même renommage de prop. Aucun ne dépend des autres. Cinq sous-agents s'exécutant en même temps terminent à peu près dans le temps qu'en prendrait un, sans état partagé à coordonner entre les changements.

L'exploration bruyante. Grep-er un motif à travers un gros dépôt, essayer trois stratégies de recherche avant qu'une ne fonctionne, lire des fichiers qui s'avèrent hors sujet. C'est exactement le travail que vous voulez mettre en quarantaine. Un sous-agent peut patauger un moment et seule la partie utile revient.

Isoler une persona spécialisée. Un sous-agent code-reviewer qui ne fait que revoir du code, avec un jeu d'outils plus étroit et un prompt réglé pour le scepticisme, se comporte plus régulièrement que de demander à votre agent principal de basculer de contexte vers « sois maintenant critique de ton propre travail » en cours de session.

Quand les sous-agents sont pires

Les boucles itératives serrées. Déboguer un test qui échoue en changeant une ligne, relançant, lisant la nouvelle erreur, changeant une autre ligne, a besoin de tout l'historique de ce que vous avez déjà essayé. Donner ça à un sous-agent frais à chaque itération veut dire réexpliquer toute l'investigation à chaque fois, plus lent et moins bon que de rester dans la boucle principale. C'est le territoire que couvrent nos notes de débogage systématique : le débogage veut de la continuité, pas de la délégation.

Les tâches nécessitant toute la conversation. Si l'utilisateur a passé dix messages à affiner ce que « nettoyer cette API » veut dire exactement, un sous-agent qui ne voit que l'instruction finale va la nettoyer selon sa propre supposition de « propre », pas celle que vous avez négociée. Tout ce dont les exigences vivent dans la conversation plutôt que dans un prompt que vous pouvez reformuler est un mauvais candidat.

Les éditions simples d'un seul fichier. Déléguer « renomme cette variable dans ce fichier » à un sous-agent ajoute un aller-retour, un chargement de contexte frais, et un résultat que vous devez quand même lire et vérifier, pour un travail qui aurait pris quinze secondes directement. Lancer un travailleur isolé ne paie que quand le travail dont il vous protège est réellement conséquent.

Le schéma à travers ces trois cas : les sous-agents sont pires exactement quand la valeur du contexte partagé dépasse le coût de le porter. L'isolation cesse d'être une fonctionnalité au moment où la continuité est ce dont la tâche avait besoin.

Définitions d'agent personnalisées

Claude Code charge des sous-agents personnalisés depuis des fichiers markdown sous .claude/agents/ (niveau projet, partagé via git) ou ~/.claude/agents/ (personnel, chaque projet). Chaque fichier est un agent : frontmatter plus un prompt système, la même forme qu'une skill mais décrivant une persona plutôt qu'une procédure.

Voici un exemple complet et annoté, un code-reviewer ciblé sur du travail de revue en lecture seule :

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs,
  security issues, and missed edge cases. Use after a change is
  written and before it's committed, not while still drafting.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior engineer doing a pre-commit review. You did not
write this code and you have no attachment to it.

When given a diff or a set of changed files:

1. Read every changed file in full, not just the diff hunks.
   Bugs hide in the context around a change as often as in the
   change itself.
2. Check for: unhandled errors, off-by-one boundaries, null or
   undefined paths the type system doesn't catch, and any
   secret or credential that shouldn't be committed.
3. Do not comment on style or formatting unless it hides a bug.
   A linter's job is not your job.
4. For each finding, cite the file and line, and say what
   breaks and how you'd confirm it. If you're not sure something
   is a bug, say so explicitly instead of stating it as fact.
5. If you find nothing, say that plainly. Do not invent minor
   issues to look thorough.

Never run commands that modify files. You are reviewing, not fixing.

Plusieurs choses comptent ici. Le name est ce que vous invoquez (Utilise l'agent code-reviewer pour vérifier ce diff) ou ce que Claude Code invoque automatiquement sur une tâche correspondante. Le champ description porte le même poids que dans une skill : des conditions de déclenchement spécifiques battent un résumé vague.

tools est une véritable frontière de sécurité, pas une suggestion. Ne lister que Read, Grep, Glob, Bash veut dire que cet agent ne peut physiquement pas appeler Edit ou Write, même si son propre raisonnement a décidé qu'une correction était évidente. C'est délibéré : un agent de revue qui peut aussi corriger ce qu'il examine est un agent auquel vous ne pouvez pas faire confiance pour se contenter de revoir. model vous permet de router un agent mécanique et bien spécifié vers un modèle moins cher que votre session principale, puisque la tâche n'a pas besoin de tout le poids de votre modèle principal.

Le corps relève du même artisanat qu'une skill : les contraintes négatives (« ne commente pas le style », « n'invente pas de problèmes mineurs ») font plus de travail que les positives, parce que ce sont elles qui empêchent un reviewer de gonfler sa sortie pour paraître minutieux.

Schémas parallèles qui fonctionnent réellement

Lectures en éventail. Lancez plusieurs sous-agents à la fois, chacun assigné à une tranche différente de la même question : l'un lit le module d'authentification, l'autre la couche de données, l'autre la suite de tests. Chacun renvoie une courte synthèse. Vous obtenez trois réponses dans le temps qu'aurait pris une passe séquentielle, et le contenu brut des fichiers ne touche jamais votre contexte principal.

N corrections indépendantes. Un lot de composants a besoin du même changement mécanique identique, et aucun n'importe des autres. Lancez un sous-agent par composant, chacun avec un prompt autonome : le changement exact, le fichier exact, le contrôle d'acceptation exact. C'est le cas parallèle le plus propre, aucun sous-agent n'a besoin de savoir ce qu'un autre a fait.

Les deux schémas partagent une exigence facile à sauter et coûteuse quand on le fait : chaque prompt doit être autonome. Il n'a pas votre conversation. Si la tâche dépend d'une décision prise trois messages plus tôt, cette décision doit être reformulée dans le prompt, ou le sous-agent fera confiance et fera la mauvaise chose.

Modes d'échec que nous avons réellement rencontrés

C'est la partie que la plupart des guides sautent, écrite par quelqu'un qui a fait tourner un sous-agent deux fois et ça a marché. Nous en faisons tourner quotidiennement, et voici ce qui casse en pratique.

Des agents qui rapportent « terminé » sans avoir fait le travail. Un sous-agent revient avec un résumé propre et confiant : « Mis à jour les trois fichiers, tests passent, prêt à commit. » Vous vérifiez, et un fichier n'a pas été touché. Ce n'est pas le modèle étant malhonnête dans un sens délibéré quelconque, c'est le résumé de retour qui dérive de ce qui s'est réellement passé, surtout sur les tâches plus longues où le propre compte-rendu de l'agent sur son travail se retrouve compressé. La correction est ennuyeuse et non négociable : vérifiez par l'artefact, pas par le rapport. Lisez le diff vous-même. Exécutez le test vous-même. Le résumé d'un sous-agent est une affirmation, pas un reçu.

Des agents qui attendent des notifications fantômes. Nous avons eu des sous-agents en pause en cours de tâche, attendant un callback ou un signal d'un autre processus qui n'allait jamais arriver, parce que le mécanisme de coordination n'existait que dans l'imagination du prompt, pas dans quoi que ce soit réellement câblé. La correction est de ne jamais concevoir un prompt de sous-agent autour d'un événement dont vous n'avez pas vérifié qu'il se déclenche. Si la prochaine étape d'un sous-agent dépend de la sortie d'un autre agent, donnez-lui directement cette sortie au lancement, ne lui demandez pas de détecter un signal d'achèvement que vous n'avez pas construit.

Les deux échecs se rattachent à la même discipline : un prompt qui ne s'appuie pas sur du contexte partagé ou une notification supposée est un prompt qu'un agent peut réellement accomplir correctement, et un résultat que vous vérifiez en lisant le fichier, pas en lisant le compte-rendu de l'agent sur le fichier, est la seule façon de savoir qu'il l'a fait. Rien de tout cela n'est un argument contre les sous-agents. C'est un argument contre le fait de faire confiance à un résumé texte de la même manière qu'on ferait confiance à un diff. Nous en faisons tourner constamment. Nous ne mergeons simplement rien sur leur seule parole.

Les skills fonctionnent aussi dans les sous-agents

Un sous-agent reste une instance Claude, donc il charge des skills de la même façon que votre session principale : en faisant correspondre sa tâche aux descriptions de skills installées et en faisant entrer le corps au déclenchement. Un sous-agent code-review avec notre skill checklist de revue de code installée reçoit la même passe structurée qu'il aurait dans la boucle principale, ciblée sur le diff que vous lui avez donné.

Cela se compose proprement. Le sous-agent gère où le travail se passe, la skill gère comment il est fait. Ni l'un ni l'autre n'a besoin de connaître l'autre ; ils s'empilent automatiquement tant que les deux sont installés là où le sous-agent peut les voir, skills de projet dans .claude/skills/, skills personnelles dans ~/.claude/skills/. Notre page meilleures skills de code classe celles qui valent la peine d'être installées avant de câbler un agent de revue ou de recherche.

Sous-agents vs hooks vs skills

Trois mécanismes différents, trois métiers différents, et on les confond constamment :

	Ce que ça fait	Se déclenche sur	S'exécute où
Skill	Apprend à Claude une procédure ou un style	Claude faisant correspondre votre demande à une description	À l'intérieur du contexte actuel
Hook	Exécute une commande shell fixe automatiquement	Un événement de cycle de vie (avant un appel d'outil, après une réponse, début de session)	En dehors du modèle, déterministe
Sous-agent	Délègue une tâche à une instance Claude isolée	Un appel explicite, par vous ou par l'agent principal	Une fenêtre de contexte séparée

Une skill change la façon dont Claude aborde quelque chose qu'il va déjà faire. Un hook impose quelque chose à chaque fois, sans condition, sans demander au modèle de s'en souvenir : exécuter les tests après chaque édition, bloquer un commit si des secrets sont détectés. Un sous-agent change où le travail se passe, le déplaçant dans une fenêtre jetable au lieu de la vôtre principale. Nous couvrons les hooks en profondeur, y compris le même genre de cicatrices que ci-dessus, dans notre guide des hooks Claude Code.

Ils s'empilent. Une configuration d'équipe pourrait utiliser un hook pour linter après chaque écriture, une skill pour enseigner le style de code maison, et un sous-agent pour exécuter la passe de revue complète avant merge, trois couches, aucune redondante. Si vous assemblez encore le reste de votre configuration, notre guide de configuration 2026 explique où va chaque pièce, et notre guide du coût en tokens couvre ce que coûtent les trois au repos.

FAQ

Les sous-agents partagent-ils le contexte de ma session principale ?

Non, et c'est tout l'intérêt. Un sous-agent démarre avec un historique vide sauf pour le prompt que vous lui donnez. Rien de votre conversation principale ne se reporte automatiquement, et rien de ce que le sous-agent lit ou fait ne revient sauf le texte final qu'il retourne. S'il a besoin de contexte de votre conversation, mettez ce contexte dans le prompt.

Les sous-agents peuvent-ils s'exécuter en parallèle ?

Oui. En lancer plusieurs à la fois est le schéma standard pour la recherche en éventail et pour les corrections indépendantes et non chevauchantes. Chacun a sa propre fenêtre de contexte, donc ils n'interfèrent pas entre eux, mais ils ne peuvent pas non plus se coordonner en cours de tâche à moins que vous n'ayez explicitement injecté la sortie de l'un dans le prompt de l'autre.

Comment savoir si un sous-agent a réellement fait ce qu'il prétend ?

Vérifiez l'artefact, pas le résumé. Lisez le diff, exécutez le test, ouvrez le fichier. Nous avons eu des sous-agents rapporter un succès propre sur un travail partiellement défait, non par malhonnêteté mais parce qu'un résumé est une reconstruction, et les reconstructions dérivent. Traitez chaque rapport de sous-agent comme une affirmation à vérifier.

Où vivent les définitions d'agents personnalisés ?

.claude/agents/*.md pour les agents au niveau projet qui voyagent avec le dépôt via git, et ~/.claude/agents/*.md pour les agents personnels disponibles dans chaque projet. Chaque fichier a besoin de name et description dans son frontmatter au minimum ; tools et model sont optionnels mais valent la peine d'être définis délibérément plutôt que laissés à leurs valeurs par défaut.

Devrais-je restreindre les outils qu'un sous-agent peut utiliser ?

Oui, chaque fois que l'agent a un métier étroit. Un agent de revue qui ne peut pas appeler Edit ne peut pas accidentellement corriger ce qu'il est censé critiquer. Un agent de recherche en lecture seule qui ne peut pas appeler Bash ne peut pas exécuter quelque chose de destructeur par erreur en fouinant. Le champ tools dans le frontmatter d'un agent est le mécanisme, et le définir coûte moins cher que de déboguer ce qu'un agent trop puissant a fait de son temps restant.