Subagents parallèles : répartir le travail sur des contextes neufs

Une conversation Claude Code ne peut traiter qu'une quantité limitée d'éléments à la fois. Quand la tâche est vraiment large, vous arrarrL'Annual Recurring Revenue (ARR) est le revenu normalisé et prévisible qu'une entreprise par abonnement attend de ses contrats actifs sur une année.Voir la définition complète →êtez de tout injecter dans un seul contexte et vous répartissez le travail vers des subagents : des instances Claude distinctes qui disposent chacune de leur propre fenêtre de contexte neuve, travaillent de façon indépendante et ne renvoient que leurs conclusions.

Vous savez déjà que la fenêtre de contexte est finie et que la saturer dégrade la qualité. Les subagents sont la réponse structurelle à ce problème dans Claude Code. Cette leçon porte sur le moment où y recourir, la façon de définir les vôtres, et ce que vous abandonnez en échange.

Ce qu'est réellement un subagent

Un subagent est une tâche enfant que Claude Code lance pour traiter une portion du travail. Il s'exécute avec un contexte vierge, fait son travail avec son propre accès aux outils, et renvoie un résumé à l'agent principal (l'orchestrateur) qui l'a lancé.

Trois propriétés comptent :

• Contexte neuf. Chaque subagent démarre à blanc. Il n'hérite pas de l'historique de votre conversation principale. C'est tout l'intérêt : il ne se dispute pas la place avec tout ce que vous avez fait par ailleurs.
• Exécution indépendante. Plusieurs subagents peuvent tourner en même temps. Claude Code les dispatche et attend qu'ils aient tous terminé.
• Retour limité au résumé. Vous ne récupérez pas la transcription complète du subagent dans votre contexte principal. Vous récupérez sa conclusion. Le raisonnement intermédiaire, brouillon, reste isolé.

Cette dernière propriété est l'astuce qui rend le fan-out scalable. Si un subagent lit 40 fichiers pour répondre à une question, ces 40 fichiers ne touchent jamais votre fenêtre principale. Seule la réponse y arrive.

Quand le fan-out parallèle bat une longue conversation unique

Le fan-out gagne quand le travail est large et séparable. Les morceaux ne dépendent pas des résultats des autres, donc les exécuter en séquence serait juste plus lent, sans bénéfice.

Bons candidats :

• Recherche de code étendue. « Trouve tous les endroits où l'on appelle l'APIAPIApplication Programming Interface : une interface standardisée qui permet aux applications de communiquer et d'échanger des données sans connaître leur fonctionnement interne respectif.Voir la définition complète → de paiement et vérifie si l'on gère le cas du timeout. » Un seul agent qui grep et lit en série va épuiser son contexte. Découpez par répertoire ou par service.
• Audits multi-fichiers. Revue de sécurité, revue des dépendances, passe d'accessibilité. Chaque sujet est une lentille distincte posée sur la même arborescence.
• Plusieurs tâches réellement indépendantes. Mettre à jour la documentation, écrire la migration, rédiger le changelog. Pas d'état partagé, donc aucune raison de sérialiser.

Le fan-out est le mauvais outil quand le travail est profond et séquentiel : un refactoring où l'étape trois dépend du résultat de l'étape deux, ou le debug d'une panne unique où chaque découverte affine la question suivante. Là, une conversation continue garde le fil. Des subagents qui ne se voient pas ne feraient que reconstruire le même contexte, avec un risque de conflit.

Le modèle mental : la largeur va aux subagents, la profondeur reste dans le fil principal.

La taxe du briefing

Comme chaque subagent démarre de zéro, vous payez un coût : vous devez le briefer complètement. Il ne connaît ni votre architecture, ni vos conventions de nommage, ni ce que « terminé » signifie, sauf si vous le lui dites dans le dispatch.

Un dispatch vague (« revois le module d'auth ») produit un résumé vague. Un subagent n'a aucun moyen de vous poser une question de clarification en cours de tâche, contrairement à une session interactive. Le prompt que vous lui confiez doit donc être autoportant :

• Quoi examiner (le périmètre)
• Quoi chercher (la question précise)
• Sous quel format rendre compte

C'est la discipline que le fan-out vous impose. La même que celle qu'exige une bonne délégation entre humains : plus le brief est clair, plus le résultat est utile.

Types de subagents personnalisés

Vous pouvez définir des types de subagents réutilisables pour ne pas réécrire les briefs à chaque fois. Dans Claude Code, les subagents existent sous forme de fichiers markdown avec un frontmatter YAML, soit dans .claude/agents/ pour un projet donné, soit dans votre configuration utilisateur pour tous les projets.

Le frontmatter définit l'identité et les permissions de l'agent. Le corps est son system prompt : les instructions permanentes qu'il reçoit à chaque exécution.

---
name: security-auditor
description: Reviews a directory for injection, auth, and secret-handling flaws. Use for security-focused code review.
tools: Read, Grep, Glob
---

You are a security reviewer. Given a directory path, inspect the code for:
- unsanitized inputs reaching queries, shell calls, or file paths
- missing authentication or authorization checks on sensitive routes
- secrets, tokens, or keys committed in source

Report only confirmed or strongly suspected issues. For each, give the
file, the line range, the risk, and a one-line fix. If you find nothing,
say so plainly. Do not summarize the whole codebase.

Deux points à noter. La description est ce que lit l'orchestrateur pour décider quand déléguer à cet agent : écrivez-la pour le routeur, pas pour vous. Et tools est volontairement restreint : cet agent peut lire et chercher, mais ni écrire ni exécuter de commandes. Le moindre privilège s'applique aux subagents comme à n'importe quelle autre automatisation.

Le schémamaUtiliser un logiciel pour automatiser les tâches et campagnes marketing répétitives, afin de personnaliser à grande échelle sur des canaux comme l'email, le web et le social.Voir la définition complète → complet et la différence entre agents au niveau projet et au niveau utilisateur sont documentés dans le guide des subagents Claude Code.

Un exemple concret : auditer une base de code en parallèle

Supposons que vous héritiez d'un service avec quatre grands domaines : api/, billing/, auth/ et workers/. Vous voulez une lecture rapide de sécurité sur l'ensemble avant une release. En séquentiel, un agent unique lirait toute l'arborescence et manquerait de place quelque part autour de workers/.

À la place, vous demandez à l'orchestrateur de répartir. Dans une session Claude Code interactive, cela se résume à le demander en langage courant :

Use the security-auditor subagent to review each of these
directories in parallel: api/, billing/, auth/, and workers/.
Give me one consolidated table of findings sorted by severity.

Claude Code lance quatre instances de security-auditor, une par répertoire. Chacune obtient un contexte neuf, ne lit que la portion qui lui est assignée et renvoie une courte liste de constats. L'orchestrateur attend les quatre, puis les fusionne dans le tableau que vous avez demandé.

Ce que vous récupérez dans votre contexte principal est compact : quatre résumés et un tableau fusionné. Ce que vous ne récupérez *pas*, ce sont les centaines de lignes que chaque agent a lues pour produire ces résumés. C'est exactement ce qu'il faut. Vous vouliez le verdict, pas les délibérations.

Comparez avec une seule longue session menant la même revue. Le temps d'arriver à workers/, les détails d'api/ seraient enfouis loin en amont du contexte, se disputant l'attention et dégradant silencieusement la précision du modèle. Le fan-out évite cela entièrement parce qu'aucun agent ne détient jamais plus que sa portion.

Dispatch programmatique avec l'agent SDK

Le flux interactif est parfait pour du travail ponctuel. Quand vous voulez du fan-out dans un script ou un pipelinepipelineL'ensemble des opportunités commerciales actives réparties selon les étapes du processus de vente, avec leur valeur potentielle cumulée et leur probabilité de conclusion.Voir la définition complète → CI, le Claude Agent SDK vous donne la même mécanique de subagents en code, de sorte que vous pouvez câbler un audit multi-fichiers dans un contrôle pré-release exécuté à chaque pull request via l'intégration GitHub.

Le pattern est identique : définir les types d'agents une fois, puis laisser l'orchestrateur leur router des portions de travail. Le SDK gère l'exécution parallèle et la collecte des résumés, vous n'avez donc pas à gérer les threads vous-même.

Les arbitrages, énoncés simplement

Le fan-out est puissant, pas gratuit. Gardez quatre coûts en tête.

Vous perdez la transcription. Le résumé est tout ce que vous obtenez. Si un subagent arrive à une conclusion fausse, vous ne pouvez pas facilement inspecter *comment* il y est arrivé sans le relancer. Concevez vos prompts d'agent pour qu'ils rapportent des preuves (fichier, ligne, raison), pas seulement des verdicts, afin que le résumé soit auditable par lui-même.

Pas de découverte partagée. Si l'agent auth/ trouve un pattern qui aiderait aussi l'agent api/, tant pis : ils ne peuvent pas se parler. Quand la connaissance transverse compte, faites soit une première passe pour établir un contexte commun et intégrez-le à chaque brief, soit gardez le travail dans un seul fil.

Plus d'agents, plus de tokens. Quatre contextes neufs qui lisent chacun des fichiers, c'est plus de travail total qu'un seul contexte lisant tout une fois, même si cela se termine plus vite en temps réel. Vous échangez de l'efficacité en tokenstokensUn token est l'unité de base de texte que traitent les modèles de langage : le plus souvent un fragment de mot, un mot entier ou un signe de ponctuation, plutôt qu'un simple caractère.Voir la définition complète → contre de la vitesse et de la qualité. Généralement rentable pour les travaux larges ; du gaspillage pour les petits.

Coût d'orchestration. Découper, dispatcher et fusionner a son propre coût dans le contexte principal. Si une tâche est assez petite pour qu'un seul agent la gère confortablement, répartir n'ajoute que du cérémonial. Réservez cela aux travaux qui débordent réellement d'un contexte unique.

Une règle de décision rapide

Avant de répartir, demandez-vous : puis-je découper cela en morceaux qui n'ont pas besoin de voir les résultats des autres ? Si oui, et s'il y en a plus de deux ou trois, répartissez. Si les morceaux sont enchevêtrés, ou s'il n'y en a que quelques-uns, restez dans une seule conversation.

Comment cela s'inscrit dans l'écosystème plus large

Les subagents sont une construction de Claude Code, mais la même forme se retrouve dans l'outillage d'Anthropic. L'Agent SDK l'expose pour les agents en production. La Messages API vous donne la primitive brute pour construire votre propre orchestration si vous avez besoin de quelque chose de sur mesure. Et comme les subagents héritent des connexions MCPMCPUn standard ouvert qui permet aux assistants IA de se connecter aux outils et données de l'entreprise de façon cohérente et gouvernée, sans intégration sur mesure à chaque fois.Voir la définition complète →, chacun peut atteindre les mêmes outils et sources de données (via le Model Context Protocol) que votre session principale, sans rien recâbler agent par agent.

Le fil conducteur : **l'outillage de Claude ne cesse de vous donner des moyens d'*isoler* le contexte délibérément plutôt que de le laisser s'accumuler par défaut**. Les Projects isolent la connaissance par espace de travail. Les Skills isolent des procédures réutilisables. Les subagents isolent une unité de travail. Chacun est une réponse différente à la même réalité d'un contexte fini.

Points clés

• Répartissez quand le travail est large et séparable, pas profond et séquentiel. Recherches étendues, audits multi-fichiers et tâches indépendantes sont le terrain idéal. Refactorings et chasses à un bug unique restent dans un seul fil.
• Briefez complètement chaque subagent. Un contexte neuf signifie aucun historique partagé et aucune possibilité de vous poser des questions. Périmètre, question et format de restitution vont dans le dispatch.
• Définissez des types d'agents réutilisables dans `.claude/agents/`. Écrivez la description pour le routeur et n'accordez que les outils dont chaque agent a besoin.
• Concevez les prompts pour renvoyer des preuves, pas seulement des verdicts. Vous ne récupérez que le résumé : rendez-le auditable par lui-même.
• Connaissez l'échange : vitesse et qualité de contexte en hausse, coût en tokens et visibilité inter-agents en baisse. Réservez le fan-out aux travaux qui débordent réellement d'un contexte unique.