Il est 10 h 20. Tu demandes à Claude Code de comprendre pourquoi la suite de tests est rouge depuis hier. Il lance PHPUnit, lit 4 000 lignes de sortie, ouvre une douzaine de fichiers, et ta conversation, qui contenait encore tout le raisonnement de ce matin, se remplit de bruit. Même semaine, autre cas : tu délègues à un sous-agent une retouche de trois lignes dans un fichier que tu viens de décrire en détail. Il repart d'un contexte vide, te rend un résumé juste mais appauvri, et tu perds dix minutes à tout lui réexpliquer.
Dans les deux cas, la délégation n'était pas le problème. Le problème, c'est de la traiter comme un réflexe au lieu d'un arbitrage. Ce premier article de la série sur les agents et sous-agents Claude Code te donne un arbre de décision pour choisir entre la conversation principale, un sous-agent intégré, un sous-agent custom, un fork et une session séparée, avec des cas concrets sur un monorepo Symfony.
Qu'est-ce qu'un sous-agent Claude Code, et qu'achète-t-il ?
Un sous-agent Claude Code est une instance de Claude lancée par la session principale, avec sa propre fenêtre de contexte, son prompt système, ses outils et ses permissions. Il ne rend à la session principale qu'un résumé, pas son historique. Selon la documentation officielle, c'est un fichier Markdown avec un frontmatter YAML, et Claude lui délègue une tâche quand elle correspond à sa description.
La délégation achète deux choses : un contexte principal qui reste propre, puisque les fichiers lus et les sorties de commandes restent chez le sous-agent, et la possibilité de restreindre les outils et les permissions. Elle n'achète pas de quota : les requêtes d'un sous-agent comptent sur les mêmes limites d'usage que ta conversation, comme le détaille l'article sur le coût réel des sous-agents en quota.
Elle coûte un contexte neuf (prompt système, définitions d'outils, CLAUDE.md, puis ses propres lectures) et, surtout, la perte de ton historique. Chaque handoff est une compression avec perte : ce qui n'est pas dans le message de délégation n'existe pas pour le sous-agent, et ce qui n'est pas dans son résumé n'existe plus pour toi. Toute la décision se joue entre ces deux colonnes.
Quelles sont les cinq options, et que voit chacune ?
Avant l'arbre, il faut savoir ce que chaque option reçoit. C'est ce qui détermine si elle peut faire le travail sans que tu le refasses derrière elle.
- Conversation principale (inline) : tout le contexte, tous les outils, aucun coût de démarrage. Tout ce que tu lis y reste. La documentation la recommande pour les allers-retours itératifs, le contexte partagé entre plusieurs phases et les changements ciblés rapides.
- Sous-agents intégrés :
Exploreest en lecture seule (Write et Edit refusés), avec trois niveaux d'exhaustivité (quick, medium, very thorough), et saute CLAUDE.md et le git status.Planest aussi en lecture seule, hérite du modèle principal et sert à la recherche en mode plan.general-purposedispose de tous les outils pour les tâches multi-étapes qui mêlent lecture et modification. - Sous-agent custom : un fichier dans
.claude/agents/(projet, versionné) ou~/.claude/agents/(tous tes projets), avec ses outils, son modèle, ses permissions, éventuellement ses hooks et sa mémoire. Il se justifie quand le même type de tâche revient. - Fork (
/subtask <tâche>, ou/forkquand l'agent view est désactivée) : il hérite de toute la conversation, prompt système, outils, modèle et historique compris. Ses appels d'outils restent hors de ton contexte, seul le résultat revient, et il partage le prompt cache du parent. - Session séparée : un autre terminal, un autre
claude, souvent un autre worktree. Elle n'hérite de rien et ne rend compte à personne. C'est une décision d'organisation plus que de délégation.
Le point qui fait échouer la plupart des délégations : un sous-agent non fork reçoit son propre prompt système (pas celui de Claude Code), le message de délégation rédigé par Claude, CLAUDE.md (sauf pour Explore et Plan, ou si omitClaudeMd est activé), un instantané du git status et ses skills préchargés. Il n'hérite ni de l'historique, ni de l'output style, ni de l'auto memory. Tu crois lui avoir dit quelque chose ; tu l'as seulement dit à la conversation.
Quel est l'arbre de décision pour déléguer ?
Voici l'arbre que j'applique, dans l'ordre. Ce n'est pas une règle officielle : c'est une heuristique construite sur les recommandations de la documentation et sur un critère simple, le volume isolé comparé au coût de démarrage d'un contexte.
1. La tâche est-elle longue, indépendante de ta session, ou destinée
à tourner sur une autre branche pendant que tu fais autre chose ?
OUI -> SESSION SÉPARÉE (idéalement un worktree dédié).
NON -> question 2.
2. La tâche est-elle itérative (tu vas corriger, relancer, affiner) ?
OUI -> INLINE. Un sous-agent repartirait de zéro à chaque correction.
NON -> question 3.
3. La modification est-elle petite et ciblée (1 à 3 fichiers que tu connais) ?
OUI -> INLINE. Le coût de démarrage dépasse le gain.
NON -> question 4.
4. Produit-elle un gros volume dont tu n'as besoin que du résumé
(exploration large, tests, logs, documentation) ?
NON -> INLINE.
OUI -> question 5.
5. Le sous-agent a-t-il besoin de ce qui s'est dit dans la conversation ?
OUI -> FORK (/subtask) : historique hérité, prompt cache partagé.
NON -> question 6.
6. La tâche revient-elle avec les mêmes contraintes
(outils limités, modèle imposé, format de sortie fixe) ?
OUI -> SOUS-AGENT CUSTOM (.claude/agents/).
NON -> INTÉGRÉ : Explore (lire), Plan (préparer), general-purpose (lire puis modifier).La question 5 est celle qu'on oublie. Un fork hérite de ton contexte, donc il démarre plus lourd qu'un sous-agent neuf, mais il réutilise le cache de la session et t'épargne de tout réexpliquer. Le sous-agent neuf, lui, est léger mais aveugle. Si tu dois réécrire une page de contexte pour que la tâche ait du sens, c'est un fork.
Quand rester dans la conversation principale ?
Plus souvent qu'on ne le pense. L'inline n'est pas un échec de délégation, c'est le choix par défaut. Renommer une constante dans deux fichiers que tu viens de lire, affiner une signature de méthode en trois itérations, corriger un bug que vous venez de reproduire ensemble : dans ces cas, le sous-agent relirait les fichiers dans un contexte neuf, tu paierais le démarrage pour quelques lignes, et chaque « non, plutôt comme ça » repartirait de zéro.
La règle tient en une phrase : si tu as encore besoin de ce que tu viens de dire ou de voir, reste inline. Et si la conversation finit par saturer, le bon outil n'est pas toujours la délégation : la dégradation du contexte et les commandes /clear et /rewind règlent une partie du problème sans handoff.
Comment ça se passe sur un monorepo Symfony ?
Cas 1, exploration large. Tu veux savoir qui appelle InvoiceNumberGenerator dans un monorepo d'une douzaine de bundles. Le volume de lecture est énorme et le résultat tient sur une page : c'est le cas idéal pour Explore, en lecture seule, qui ne peut rien casser. L'exemple de prompt ci-dessous est illustratif :
Votre équipe utilise Claude Code ?
Formation intra sur vos projets réels : de la demi-journée à 2 jours, 6 devs max.
Utilise Explore (very thorough) pour cartographier l'usage de
App\Billing\InvoiceNumberGenerator dans src/ et packages/.
Je veux : la liste des appelants (classe::méthode), les services Symfony
qui l'injectent (config/services.yaml ou attributs), et les endroits où le
numéro est reformaté. Ne modifie rien. Réponds en moins de 30 lignes,
chemins de fichiers à l'appui.Cas 2, tests et logs verbeux. Une suite PHPUnit qui sort des milliers de lignes, dont tu ne veux que les échecs. La documentation donne la formule : « Use a subagent to run the test suite and report only the failing tests with their error messages ». Précise la commande exacte (par exemple via Docker, si ton CLAUDE.md l'impose), car le sous-agent ne connaît que ce que le message de délégation lui transmet. Si cette demande revient chaque jour, c'est un candidat au sous-agent custom avec tools: Bash, Read, Grep et un modèle léger.
Cas 3, revue non ancrée. Tu veux un regard neuf sur un diff, sans que le raisonnement de la session ne biaise le relecteur. Ici, l'absence d'historique est un atout : le sous-agent ne reçoit pas tes justifications. C'est exactement le contraire du fork. Donne-lui le périmètre et les critères, pas ton interprétation :
Utilise un sous-agent pour relire git diff main...HEAD.
Cherche uniquement : injections SQL/DQL, contrôles d'accès manquants
(voters), requêtes N+1 Doctrine, services non typés.
Ne propose pas de refactoring de style.
Réponds par un tableau fichier:ligne | gravité | problème.Cas 4, tâche longue sur une autre branche. Une montée de version de bundle qui va durer l'après-midi pendant que tu continues ta fonctionnalité. Ni fork ni sous-agent : une session séparée dans son propre worktree, pour que les deux chantiers ne se marchent pas dessus. Le sujet est traité en détail dans l'article sur le subagent-driven development avec git worktrees.
Que mettre dans un prompt de délégation ?
Puisque le sous-agent n'hérite pas de l'historique, le message de délégation est tout son contexte de tâche. Tu peux l'orienter : décris la délégation dans ta demande plutôt que de laisser Claude la deviner. Un gabarit en quatre blocs couvre l'essentiel :
OBJECTIF : ce que tu veux savoir ou obtenir, en une phrase.
PÉRIMÈTRE : dossiers, fichiers, commandes autorisées ; ce qu'il ne touche pas.
CONTRAINTES : règles CLAUDE.md critiques recopiées explicitement
(exécution via Docker, pas de commit, version PHP cible...).
SORTIE : format et taille de la réponse (liste, tableau, moins de 30 lignes).Le bloc contraintes n'est pas redondant. Explore et Plan ne chargent pas CLAUDE.md, aucun sous-agent ne reçoit l'auto memory, et la documentation recommande elle-même de rappeler les règles critiques dans le prompt de délégation. Pour choisir l'agent, tu peux le nommer en langage naturel (« utilise le sous-agent test-runner »), le forcer avec @agent-<name>, ou faire tourner toute une session sous un agent avec claude --agent code-reviewer.
Quels pièges coûtent cher en pratique ?
- Le fork est actif par défaut (dans un terminal interactif depuis la version 2.1.232, partout depuis la 2.1.302). Tant qu'il l'est, Claude ne peut pas attendre un sous-agent dans une session interactive. Pour retrouver ce comportement :
CLAUDE_CODE_FORK_SUBAGENT=0. - Explore et Plan ne sont pas reprenables. Les autres sous-agents se reprennent via
SendMessage, avec leur historique complet. Pour un travail que tu voudras relancer, préfère general-purpose ou un custom. - Un sous-agent ne peut pas te poser de question.
AskUserQuestionfait partie des outils toujours retirés aux sous-agents : tout cadrage doit figurer dans le prompt. - Les permissions se propagent. Si ta session est en
acceptEdits,autooubypassPermissions, le sous-agent applique ce mode et son proprepermissionModeest ignoré. Un sous-agent délégué depuis une session permissive est donc tout aussi permissif. - Les limites existent. Profondeur d'imbrication de 3 niveaux sous la conversation principale (
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH), 20 sous-agents simultanés par défaut (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), et un fork ne peut pas lancer de fork.
Si tu veux couper un mécanisme pour toute l'équipe, les permissions le permettent : Agent(Explore) bloque un intégré, Agent(fork) bloque les forks, Agent bloque toute délégation. Par exemple, dans .claude/settings.json :
{
"permissions": {
"deny": ["Agent(fork)"]
}
}Et pour comprendre après coup pourquoi une délégation a mal tourné, les transcripts des sous-agents sont conservés dans ~/.claude/projects/{project}/{sessionId}/subagents/, selon cleanupPeriodDays (30 jours par défaut), indépendamment de la compaction de la session principale. /tasks montre ceux qui tournent encore.
Que retenir avant ta prochaine délégation ?
- Inline par défaut : délègue seulement quand tu isoles un volume dont tu n’utiliseras que le résumé.
- Le travail itératif et les petites modifications restent dans la conversation principale.
- Besoin de ton contexte : fork (
/subtask). Pas besoin : sous-agent neuf. Lecture seule : Explore. - Un prompt de délégation tient en quatre blocs : objectif, périmètre, contraintes recopiées, format de sortie.
- Si tu délègues la même chose trois fois, c'est un sous-agent custom.
Retiens l'ordre des questions plutôt que la liste des outils : d'abord ce dont tu as encore besoin dans ta conversation, ensuite le volume à isoler, ensuite l'historique à transmettre, et seulement après le mécanisme. Cette semaine, reprends trois délégations que tu as lancées et passe-les dans l'arbre : tu verras vite celles qui coûtaient plus qu'elles ne rapportaient.
La dernière règle ouvre l'article suivant : écrire un sous-agent custom avec son frontmatter, du fichier minimal aux champs qui comptent vraiment, avec des exemples Symfony et les erreurs qui le font ignorer sans le moindre message.

Écrit par
Flavien Métivier
Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.
Mon parcours